Interstage Shunsaku Data Manager Application Development Guide

Transcription

1 Interstage Shunsaku Data Manager Application Development Guide

2 Application Development Guide Trademarks Trademarks of other companies are used in this user guide only to identify particular products or systems. Product Microsoft, Visual C++, Windows, and Windows Server Solaris Linux Java CORBA Red Hat, RPM, and all trademarks and logos based on Red Hat Oracle Interstage Trademark/Registered Trademark Registered trademark or trademarks of Microsoft Corporation in the United States and other countries. Solaris and all other trademarks and logos related to Solaris are registered trademarks or trademarks of Sun Microsystems Inc. U.S.A. in the United States and other countries, and are used under license from the said company. Registered trademark or trademark of Linus Torvalds in the United States and other countries. Java and other trademarks comprising Java are trademarks of Sun Microsystems Inc. U.S.A. in the United States and other countries. CORBA is a registered trademark of Object Management Group Inc. in the United States and other countries. Trademarks or registered trademarks of Red Hat Inc. in the United States and other countries. Oracle is a registered trademark of Oracle Corporation. Interstage is a registered trademark of Fujitsu Limited. Fujitsu documentation may contain specific technologies that are subject to the Foreign Exchange and Foreign Trade Control Law. When such specific technology is described in a document, and that document is either exported or provided to a nonresident, permission must be sought under the above law. Fujitsu Limited First Edition (May 2005) Second Edition (September 2005) Third Edition (December 2005) The contents of this manual may be revised without prior notice. All Rights Reserved, Copyright FUJITSU Limited 2005 ii

3 Preface Purpose of this Manual This manual describes how to create applications that use the APIs provided by Interstage Shunsaku Data Manager (hereafter abbreviated as Shunsaku). Target Audience This manual is aimed at the following readers Persons using Shunsaku. Persons developing applications that use the Shunsaku APIs. Required Knowledge This manual assumes that the reader has an understanding of the following topics XML C language Java language Internet basics Windows Linux Solaris(TM) Operating System iii

4 Preface Organization of this Manual This manual is organized as follows Chapter 1 - Overview This chapter provides an overview of the functions of Shunsaku. Chapter 2 - Environment Setup This chapter explains the environment settings needed for creating applications that use the Shunsaku APIs. Chapter 3 - Data Search Methods This chapter explains the data search methods that use search expressions, return expressions and sort expressions specified as arguments for the APIs provided by Shunsaku. Chapter 4 - Data Updating Methods This chapter explains how to update data using the Shunsaku APIs. Chapter 5 - Developing Java Applications This chapter explains how to develop applications using Shunsaku s Java APIs. Chapter 6 - Developing C Applications This chapter explains how to develop applications using Shunsaku s C APIs. Appendix A - Execution Parameters in API Environment Files This appendix explains the execution parameters that are specified in the API environment file. Appendix B - Format of Search, Return and Sort Expressions This appendix explains the formats of the search expressions, return expressions and sort expressions that are specified as arguments of the Shunsaku APIs. Appendix C - Sample Java Programs This appendix provides sample programs that use the Java APIs. Appendix D - Sample C Programs This appendix provides sample programs that use the C APIs. Appendix E - Allowable Values This appendix explains the allowable values that are involved during the development of Shunsaku applications. Appendix F - Estimating Resources This appendix explains how to estimate resources when using applications to add, delete or search for data. Appendix G - Notes on XML Documents This appendix provides notes on the XML documents that are stored in Shunsaku. iv

5 Table of Contents Chapter 1 Overview Performing Data Searches from Applications Performing Data Updates from Applications Chapter 2 Environment Setup API Configuration Java APIs C APIs Setup Setting Environment Variables Setting Environment Variables (Java APIs) Setting Environment Variables (C APIs) (Linux/Solaris) Setting Up Environment Files Specifying a Separate API Environment File for Each Machine on which the APIs are Installed Specifying a Separate API Environment File for each Application to be Started Java APIs C APIs Priority of Execution Parameters Chapter 3 Data Search Methods Data Search Overview Specifying the Search Expression Searching with Character Strings Searching for Documents that Contain a Keyword Searching for Documents that Match a Search Keyword Exactly Performing a Size Comparison with a Search Keyword Searching by Numeric Value Searching by Joining Multiple Conditions with Logical Operators Sorting Search Results Sorting by Character String Sorting by Numeric Value Sorting with Multiple Keys Extracting Search Results Extracting Data in XML Format v

6 Table of Contents Extracting an Entire XML Document Extracting Data in XML Format by Specifying an Element Node Extracting Data in Text Format Extracting Aggregated Results Grouping Search Results Grouping by Character String Grouping by Numeric Value Grouping by Multiple Keys Aggregating Search Results Chapter 4 Data Updating Methods Overview of Data Updating Adding Data Deleting Data Updating Data Chapter 5 Developing Java Applications Java API Overview Developing Applications with Apworks Advantages of Developing with Apworks Flow of Development Using Apworks Create Project Create and Edit Source Create Shunsaku Access Class Create Search Method Create Sort Expression Create Data Classes Create Data Bean Create I/O Pages (JSP) Create Business Class Build Execute Debug How to Use Java APIs Establishing a Connection Configuring Settings in the API Environment File Setting Java Properties Specifying the Host Name and Port Number Directly Data Searches Obtaining the Number of XML Documents that Match Search Conditions Obtaining Search Results According to the Number of Data Items Obtaining Search Results While Adding Search Conditions Extracting Record IDs vi

7 Table of Contents Using Record IDs to Obtain Entire XML Documents Obtaining Sorted Data Obtaining Consecutive Groups of XML Documents that Match Conditions Aggregating the Content of Data that Matches Search Conditions Updating Data Adding Data Deleting Data by Specifying Record IDs Updating Data by Specifying Record IDs Closing Connections Error Handling Debugging Applications Debugging with the Debugger Debugging with Application Debugging Information Debugging with the API Snapshot Function Information Output by the API Snapshot Function Environment Settings of the API Snapshot Function Java API Method Information Character Encoding Used by Java APIs Error Messages that may be Output during API Use Message Output Format Response to Messages Chapter 6 Developing C Applications C API Overview Connection Handles Data Manipulation Handles Common Functions How to Use C APIs Establishing a Connection Configuring Settings in the API Environment File Specifying the Host Name and Port Number Directly Data Searches Obtaining the Number of XML Documents that Match Search Conditions Obtaining Search Results with a Specified Number of Data Items Obtaining Search Results while Adding Search Conditions Using Record IDs to Obtain Entire XML Documents Obtaining Sorted Data Obtaining Consecutive Groups of XML Documents that Match Conditions Aggregating the Content of the Data that Matches Search Conditions Updating Data Adding Data Deleting Data by Specifying Record IDs Updating Data by Specifying Record IDs vii

8 Table of Contents Closing Connections Error Handling Debugging Applications Debugging with the Debugger Debugging with Application Debugging Information Debugging with the API Snapshot Function Information Output by the API Snapshot Function Environment Settings of the API Snapshot Function C API Function Information Character Encoding Used by the C APIs Error Messages that may be Output during API Use Appendix A Execution Parameters in API Environment Files Format of Execution Parameters... A-2 Execution Parameters and their Meanings... A-3 Detailed Meaning of Execution Parameters... A-4 Sample Execution Parameter Specifications... A-6 Appendix B Format of Search, Return and Sort Expressions Syntax Notation Method... B-2 Common Format... B-3 Path Expressions... B-3 Text Expressions... B-5 Single-line Function Specification... B-6 Search Expressions... B-8 Conditional Expressions... B-10 Path Expressions...B-10 Keywords...B-10 Keywords and Relational Operators... B-12 Patterns... B-13 Character String... B-21 Numeric Values... B-22 Compatible Format... B-24 Filter Expressions... B-25 Return Expressions... B-27 Format Used when not Aggregating... B-27 Example Return Expressions when not Aggregating... B-28 Format Used when Aggregating... B-33 Example Return Expressions used when Aggregating... B-35 Sort Expressions... B-39 Sort Expression Format... B-39 Example Sort Expressions... B-42 viii

9 Table of Contents Appendix C Sample Java Programs Searching Data...C-2 Obtaining the Number of XML Documents that Match Search Conditions...C-4 Search Conditions...C-4 Obtaining XML Documents that Match Search Conditions in a Specified Format...C-6 An Example of Using the APIs...C-7 Obtain Every Instance of Particular XML Documents...C-9 An Example of Using the APIs...C-9 Obtaining XML Documents that Match Search Conditions after they have been Sorted...C-12 An Example of Using the APIs...C-13 Aggregating the Values of XML Documents that Match Search Conditions...C-15 An Example of Using the APIs...C-15 Updating Data...C-19 Adding Data...C-19 Deleting Data...C-21 An Example of Using the APIs...C-21 Updating Data...C-24 An Example of Using the APIs...C-24 Appendix D Sample C Programs Searching Data...D-2 Obtaining the Number of XML Documents that Match Search Conditions...D-4 Obtaining XML Documents that Match Search Conditions in a Specified Format...D-7 Obtain Every Instance of Particular XML Documents...D-10 Obtaining XML Documents that Match Search Conditions after they have been Sorted...D-16 Aggregating the Values of XML Documents that Match Search Conditions...D-19 Updating Data...D-24 Adding Data...D-24 Deleting Data...D-27 Updating Data...D-31 ix

10 Table of Contents Appendix E Allowable Values Allowable Values for Search Expressions and Return Expressions... E-2 Allowable Values for Sort Requests... E-3 Allowable Values for Aggregation Requests... E-5 Appendix F Estimating Resources Estimating Local Memory Requirements when Java APIs are Used... F-2 Estimating Local Memory Requirements when C APIs are Used... F-4 Appendix G Notes on XML Documents The Format of XML Documents...G-2 XML Document in Text Files...G-3 Notes on the XML Format...G-5 x

11 Chapter 1 Overview This chapter provides an overview of Shunsaku functions. Performing Data Searches from Applications Performing Data Updates from Applications 1-1

12 Chapter 1 Overview Performing Data Searches from Applications The Shunsaku APIs can be used to create applications that perform data searches. Shunsaku provides Java and C APIs. Figure 1-1 Searching Data from Applications 1-2

13 Performing Data Updates from Applications Performing Data Updates from Applications The Shunsaku APIs can be used to create applications that perform data updates. Shunsaku provides Java and C APIs. Figure 1-2 Updating Data from Applications 1-3

14 Chapter 1 Overview 1-4

15 Chapter 2 Environment Setup This chapter explains the environment settings that are required to create applications that can use Shunsaku. API Configuration Setup Setting Environment Variables Setting Up Environment Files 2-1

16 Chapter 2 Environment Setup API Configuration This section explains the configuration of Shunsaku APIs. Java APIs This section explains the configuration of Java APIs. File Configuration for Java APIs When Shunsaku APIs are installed, the following jar format file is created. Shunsaku installation folder\shunsaku\lib\shunapi.jar /opt/fjsvshnsk/lib/shunapi.jar API Package (shunapi.jar) This package contains Java classes for creating applications. Refer to the Java API Reference for more information on the functions that can be implemented by using each of the methods provided by the Shunsaku APIs. C APIs This section explains the configuration of C APIs. Directory Configuration for C APIs When the Shunsaku APIs are installed, include files and library files are created in the following directories. Shunsaku installation folder\shunsaku\include This is the include file provided by the Shunsaku APIs. Shunsaku installation folder\shunsaku\lib This is the library provided by the Shunsaku APIs. /opt/fjsvshnsk/include This is the include file provided by the Shunsaku APIs. /opt/fjsvshnsk/lib This is the library provided by the Shunsaku APIs. 2-2

17 API Configuration Include File A reference to this include file must be added to any application which uses a function from the Shunsaku APIs. The include file is shown below. Include file name libshun.h Usage This file is referenced by each function in Shunsaku APIs. Library The following file contains the C function library for creating applications f3hyshun.lib Note Specify "/MD" as the compiler option for multithreading when creating applications in Windows environments. libshun.so Refer to the C API Reference for more information on the functions that can be implemented by using the libraries provided by the Shunsaku APIs. 2-3

18 Chapter 2 Environment Setup Setup Refer to the Installation Guide for more information on installing the Shunsaku APIs on the application server. 2-4

19 Setting Environment Variables Setting Environment Variables This section explains the environment variables that are needed to use the Shunsaku APIs. Setting Environment Variables (Java APIs) Set the environment variables required for using the Shunsaku Java APIs. Add shunapi.jar to the CLASSPATH environment variable. Examples of how to set these environment variables are shown below. Example For a standard Shunsaku installation SET CLASSPATH=C\Program Files\Interstage Shunsaku\Shunsaku\lib\shunapi.jar;%CLASSPATH% Example 1 For bash, Bourne and Korn shells CLASSPATH=/opt/FJSVshnsk/lib/shunapi.jar$CLASSPATH; export CLASSPATH Example 2 For C shell setenv CLASSPATH /opt/fjsvshnsk/lib/shunapi.jar$classpath Setting Environment Variables (C APIs) (Linux/Solaris) Set the environment variables required for using the Shunsaku C APIs. Add /opt/fjsvshnsk/lib to the LD_LIBRARY_PATH environment variable. Examples of how to set these environment variables are shown below. 2-5

20 Chapter 2 Environment Setup Example 1 For bash, Bourne and Korn shells LD_LIBRARY_PATH=/opt/FJSVshnsk/lib$LD_LIBRARY_PATH ; export LD_LIBRARY_PATH Example 2 For C shell setenv LD_LIBRARY_PATH /opt/fjsvshnsk/lib$ld_library_path 2-6

21 Setting Up Environment Files Setting Up Environment Files This section explains how to set up the environment files for the Java and C APIs (hereafter abbreviated as "API environment files"). The following information is set in the API environment files. The host name and port number of the connection destination The maximum response wait time from Shunsaku Settings for the API snap function Setting up API environment files enables the operating environment to be changed without recompiling the application. API environment files can be specified in the following two ways Specifying a Separate API Environment File for Each Machine on which the APIs are Installed Specifying a Separate API Environment File for each Application to be Started Refer to Appendix A, Execution Parameters in API Environment Files for more information on the settings in the API environment file. Specifying a Separate API Environment File for Each Machine on which the APIs are Installed This section explains how to specify a separate API environment file for each machine where the APIs are installed. Copy and edit the following sample API environment file. Shunsaku installation folder\shunsaku\etc\api\api.cfg-sample /etc/opt/fjsvshnsk/etc/api/api.cfg-sample Save the edited API environment file to the same folder as the sample, using the file name "api.cfg". Shunsaku installation folder\shunsaku\etc\api\api.cfg 2-7

22 Chapter 2 Environment Setup /etc/opt/fjsvshnsk/etc/api/api.cfg Note The APIs will still run even if there is no API environment file. In this case the APIs will run using their default values. Refer to Appendix A, Execution Parameters in API Environment Files, the Java API Reference or the C API Reference for details. Specifying a Separate API Environment File for each Application to be Started This section explains how to specify a separate API environment file for each application to be started. Copy and edit the following sample API environment file. Shunsaku installation folder\shunsaku\etc\api\api.cfg-sample /etc/opt/fjsvshnsk/etc/api/api.cfg-sample Java APIs If a separate API environment file is specified for each application, the files do not need to be stored in the same folder as the sample. Specify the settings as described below, depending on the type of API being used. Specify the absolute path of the API environment file in the "com.fujitsu.shunsaku.api.configfile system property using the "D" option when the application is executed. Example To specify D\temp\api\api.cfg as the API environment file for an application called "app" Java Dcom.fujitsu.shunsaku.api.configfile=D\temp\api\api.cfg app Example To specify /tmp/api/api.cfg as the API environment file for an application called "app" Java Dcom.fujitsu.shunsaku.api.configfile=/tmp/api/api.cfg app 2-8

23 Setting Up Environment Files C APIs Specify the absolute path of the API environment file in the SHUN_API_CONFIG environment variable. Example To specify D\temp\api\api.cfg as the API environment file to be used SET SHUN_API_CONFIG=D\temp\api\api.cfg Example To specify /tmp/api/api.cfg as the API environment file to be used For bash, Bourne and Korn shells SHUN_API_CONFIG=/tmp/api/api.cfg; export SHUN_API_CONFIG FOR C shell setenv SHUN_API_CONFIG /tmp/api/api.cfg Priority of Execution Parameters Host names and port numbers can be specified using both the API environment file and the ShunConnection class constructor or the ShunConnect function. If host names and port numbers are specified in both places, priority is as follows 1. The ShunConnection class constructor or the ShunConnect function 2. The execution parameter in the API environment file that was specified when the application started 3. The execution parameter specified in the API environment file of the machine where the APIs are installed 4. The default value for the API Refer to Appendix A, Execution Parameters in API Environment Files, the Java API Reference, or the C API Reference for more information on the default values for host names and port numbers. 2-9

24 Chapter 2 Environment Setup 2-10

25 Chapter 3 Data Search Methods This chapter explains how search expressions, return expressions and sort expressions specified as arguments to Shunsaku API functions, are used to search for data. Data Search Overview Specifying the Search Expression Sorting Search Results Extracting Search Results Extracting Aggregated Results 3-1

26 Chapter 3 Data Search Methods Data Search Overview This section explains the basic approach to searching for XML documents stored in Shunsaku. A search expression is used to search for particular XML documents stored in Shunsaku. A sort expression is used to change the sequence in which XML documents are returned. A return expression is used to decide which elements will be aggregated or extracted from the XML documents that are found by a search. A group key is selected when aggregation is to be performed. The group key is specified in the sort expression. The following diagram illustrates the process used to search for XML documents stored in Shunsaku. Figure 3-1 Overview of the Search Process for XML Documents Stored in Shunsaku Refer to Appendix B, Format of Search, Return and Sort Expressions for more information on search expressions, return expressions and sort expressions. The explanations in the following sections use a Business Trip Report as an example. Assume that the following XML document exists 3-2

27 Data Search Overview Sample Document <doc> <employee> Employee information <eno>employee number</eno> <name>employee name</name> <sno>section number</sno> <phone>extension</phone> < >address</ > </employee> <basic> Basic information <date>trip date</date> <classification>classification</classification> <expense>trip expenses</expense> </basic> <detail> Details <destination>trip destination</destination> <area>trip area</area> <purpose>trip purpose</purpose> <train>traveling expenses</train> <taxi>taxi fares</taxi> <hotel>accommodation costs</hotel> <comment>comments</comment> </detail> <report>trip report</report> Trip report </doc> <doc> 3-3

28 Chapter 3 Data Search Methods Specifying the Search Expression A search expression is used to retrieve XML documents that satisfy specified conditions from the XML documents stored in Shunsaku. The search expression is specified in the APIs provided by Shunsaku. Refer to Search Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on search expressions. Searching with Character Strings It is possible to search for XML documents by specifying conditions that apply to character strings contained in any given element node of an XML document. The following three methods can be used to specify the conditions that apply to the character string Searching for Documents that Contain a Keyword Searching for Documents that Match a Search Keyword Exactly Performing a Size Comparison with a Search Keyword The following examples assume that Documents A, B, and C below, exist. Document A <doc> <basic> <date>2004/01/30</date> <classification>area-a</classification> </basic> <detail> <destination>melbourne Office</destination> <area>richmond, Melbourne</area> <purpose>interstage Shunsaku Sales Promotion Meeting attendance</purpose> <train>$20.00</train> <taxi></taxi> <hotel>$85.00</hotel> <comment>hotel charges were incurred due to attendance at an informal meeting</comment> </detail> <report>at the meeting, the Systems Manager of the IT Department of Company A requested that a search response of 10 seconds or less be attained.<report> </doc> 3-4

29 Specifying the Search Expression Document B <doc> <basic> <date>2004/01/31</date> <classification>area-c</classification> </basic> <detail> <destination>sydney branch</destination> <area>balmain, Darlinghurst, Bronte, Sydney </area> <purpose> V7.0L10 installation report </purpose> <train>$140.00</train> <taxi>$180.30</taxi> <hotel></hotel> <comment>plan to return home directly</comment> </detail> <report>because of the rapid installation, the client doubted that we could achieve their requested search response of 18 seconds. However, we were in fact able to achieve a search response of just 14 seconds.</report> </doc> Document C <doc> <basic> <date>2004/03/02</date> <classification>area-b</classification> </basic> <detail> <destination>head office</destination> <area>clearview, Belair, Adelaide</area> <purpose>interstage regular meeting</purpose> <train>$24.00</train> <taxi>$21.00</taxi> <hotel></hotel> <comment>sales meeting materials were verified in advance.</comment> </detail> <report>they were requested to get advance approval from the Sales Coordination Department to verify the materials.</report> </doc> Searching for Documents that Contain a Keyword It is possible to search for XML documents with an element node that has a character string that contains a search keyword. This type of search is called a partial match search. Partial match searches are specified by connecting the path expression and the search keyword with the relational operator =. Keywords can be specified in a variety of formats to specify more detailed and specific search conditions. A more detailed search condition specification format is referred to as a pattern. 3-5

30 Chapter 3 Data Search Methods Path Expression Refer to Path Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on path expressions. Example 1 Search for documents containing the keyword Shunsaku in the trip purpose (purpose) /doc/detail/purpose = 'Shunsaku' Result Document A is returned. If // is specified in the path expression, a search can be performed on all levels of element nodes under the element node represented by the path value preceding the //. By specifying * in the path expression, searches can be performed using all of the element nodes immediately under any element node as the search target. Note The // specification is a useful way to find documents that contain the search keyword in any element node of an entire XML document, and not just in a specific element node. Example 2 Search for documents containing the keyword Sales Meeting somewhere in the detailed information (detail) /doc/detail/* = 'Sales meeting' Result Document C is returned. Example 3 Search for documents containing the keyword installation report somewhere in the XML document /doc// = 'installation report' Result Document B is returned. Note The // specification is useful when the target element nodes can be uniquely determined without having to express a hierarchical structure. Example 4 Search for documents containing the keyword Sydney in the trip destination (destination) //destination = 'Sydney' 3-6

31 Specifying the Search Expression Keywords Result Document B is returned. Broadly speaking, the following three keyword specification formats are available Character String Searches This format searches for documents that contain a given character string. Character string searches can ignore linefeeds and other characters that are not relevant. The characters that are to be ignored as search targets can be changed using SkipChar. Refer to System Environment Files and Director Environment Files in Appendix A, Execution Parameters in Environment Files of the Operator's Guide (Advanced) for more information on SkipChar. Word Searches This format searches English-language XML documents. Searches detect the character that is used to delimit words. This delimiter can be changed using SeparateChar. Refer to System Environment Files and Director Environment Files in Appendix A, Execution Parameters in Environment Files of the Operator's Guide (Advanced) for more information on SeparateChar. Logical Operation Searches This format makes it possible to perform searches that are a combination of character string searches and word searches. The following table shows the different keyword specification formats and search methods. Table 3-1 Keyword Specification Formats and Search Methods Specification format Character string searches Word searches Logical operation searches Search method String Match Specification Search Prefix Search Suffix Search Free Character Specification Search Character Interval Specification Search Partial Character Specification Search Character Range Specification Search Numeric Range Specification Search Word Match Specification Search Word Interval Specification Search Logical Conjunction Specification Search Logical Disjunction Specification Search Negation Specification Search 3-7

32 Chapter 3 Data Search Methods String Match Specification Search This method can search for documents that contain a desired keyword. Example Refer to String Match Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the string match specification search. Search for documents containing the keyword V7.0L10 in the trip purpose (purpose) /doc/detail/purpose = 'V7\.0L10' Result Document B is returned. Note \ is an escape character that is used to search for. Refer to Conditional Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on escape characters. Prefix Search This method can search for documents that begin with a desired keyword. Example Refer to Prefix Match Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the prefix search. Search for documents whose trip purpose (purpose) begins with the keyword Interstage /doc/detail/purpose = '^Interstage' Result Documents A and C are returned. Suffix Search This method can search for documents that end with a desired keyword. Example Refer to Suffix Match Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the suffix search. Search for documents whose trip destination (destination) ends with the keyword branch /doc/detail/destination = 'branch$' 3-8

33 Specifying the Search Expression Result Document B is returned. Note By combining the prefix search and the suffix search, the user can search for documents whose element node character string perfectly matches a specified keyword. Example 1 Search for documents whose trip destination (destination) consists of the keyword Sydney branch only /doc/detail/destination = '^Sydney branch$' Result Document B is returned. Example 2 Search for documents whose accommodation cost (hotel) is the empty string /doc/detail/hotel = '^$' Result Documents B and C are returned. Free Character Specification Search This method can search for documents where two desired keywords are located on either side of a given character string. Refer to Free Character Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the free character specification search. Example 1 Search for documents whose detailed information (detail) contains a keyword consisting of sales and meeting separated by zero or more characters. /doc/detail/* = 'sales.*meeting' Result Documents A and C are returned. Example 2 Search for documents whose detailed information (detail) contains a keyword consisting of $1 and. separated by 2 characters /doc/detail/* = '\$1..\. ' Result Document B is returned. 3-9

34 Chapter 3 Data Search Methods Character Interval Specification Search This method can search for documents that contain two desired keywords separated by no more than a specified number of characters. Example Refer to Character Interval Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the character interval specification search. Search for documents whose trip purpose (purpose) contains the keywords Interstage and meeting that are separated by no more than nine characters. /doc/detail/purpose = 'Interstage,9C,meeting' Result Document C is returned. Document A is not returned because its keywords are separated by more than nine characters. Partial Character Specification Search This method can search for documents that have one of a set of specified character strings located between two desired keywords. Example Refer to Partial Character Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the partial character specification search. Search for documents that have the keywords Richmond, Melbourne or Brighton, Melbourne in the trip area (area) /doc/detail/area = '(Richmond Brighton)\, Melbourne' Result Document A is returned. Character Range Specification Search This method can search for documents that include characters that lie within a specified range. Example Refer to Character Range Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the character range specification search. Search for documents whose classification (classification) contains the keyword Area-A, Area-B or Area-C /doc/basic/classification = Area\-[A-C] Result Documents A, B, and C are returned. Note This example achieves the same result as when Area\-(A B C) is specified in a partial character specification search. 3-10

35 Specifying the Search Expression Numeric Range Specification Search This method can search for documents whose keywords contain numeric characters that lie within a specified range. Example Refer to Numeric Range Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the numeric range specification search. Search for documents whose trip report (report) contains one of the following keywords search response of 1 second, search response of 2 seconds, search response of 3 seconds,..., search response of 11 seconds or search response of 12 seconds /doc/report = 'search response of [1,12] seconds' Result Document A is returned. Notes This example achieves the same result as when search response of ( ) seconds is specified in a partial character specification search. To prevent erroneous results, specify characters on both sides of the numerals when performing a numeric range specification search. For example, if a search is conducted using the expression search response of [1,12], the 1 character in search response of 18 seconds in Document B will satisfy the expression and cause Document B to be returned, even though it is not an intended target of the search. Word Match Specification Search This method can search for documents that contain a desired word. Example In the case of a word search, character strings separated by a delimiter such as a space character are recognized as keywords and searches are performed for individual words. Refer to Word Match Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the word match specification search. Search for documents that contain the keyword Manager in the report (report) /doc/report = '\<Manager\>' Result Document A is returned. Note By specifying a series of keywords, the user can search for documents that contain a phrase made up of a series of words. 3-11

36 Chapter 3 Data Search Methods Example Search for documents that contain the keywords IT Department of Company A in the report (report) /doc/report = '\<IT\>\<Department\>\<of\>\<Company\>\<A\>' Result Document A is returned. Word Interval Specification Search This method can search for documents that contain a phrase that contains two keywords separated by no more than a specified number of words. Example Refer to Word Interval Specification in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the word interval specification search. Search for documents in the report (report) that contain a phrase that begins with the keyword response and ends with the keyword seconds, and in which both keywords are separated by no more than five words /doc/report = '\<response\>,5w,\<seconds\>' Result Documents A and B are returned. Logical Conjunction Specification Search This method can search for documents in which the character string for the element node specified by the path expression matches all of a number of specified conditions. Refer to Logical Conjunction in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the logical conjunction specification search. Example 1 Search for documents whose comments (comment) begin with the keyword sales meeting and include the keyword verified /doc/detail/comment = '^sales meeting&verified' Result Document C is returned. Example 2 Search for documents whose detailed information (detail) contains the keyword Interstage and the keywords sales /doc/detail// = 'Interstage&sales' 3-12

37 Specifying the Search Expression Result Document A and C are returned. Note The same search as in Example 2 can be performed even if "AND" is used as follows Example /doc/detail// = 'Interstage' AND /doc/detail// = 'sales' Result Documents A and C are returned. Logical Disjunction Specification Search This method can search for documents in which the character string for the element node specified by the path expression matches one of a number of specified conditions. Example Refer to Logical Disjunction in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the logical disjunction specification search. Search for documents whose trip area (area) contains the keyword Paddington, Sydney, Bronte, Sydney or Adelaide /doc/detail/area = '(Paddington Bronte)\, Sydney Adelaide' Result Documents B and C are returned. Negation Specification Search This method can search for documents that do not match specified conditions. Refer to Negation in Patterns in Appendix B, Format of Search, Return and Sort Expressions for more information on the negation specification search. Example 1 Search for documents whose trip destination (destination) does not contain the keyword head office /doc/detail/destination = '~(head office)' Result Documents A and B are returned. Example 2 Search for documents whose trip area (area) contains the keyword Melbourne but does not contain the keyword Brighton /doc/detail/area = 'Melbourne&~(Brighton)' 3-13

38 Chapter 3 Data Search Methods Result Document A is returned. Searching for Documents that Match a Search Keyword Exactly Example It is possible to search for documents with an element node that contain a character string that exactly matches a given keyword. This type of search is known as a complete match search. The complete match search is specified by connecting the path expression and the search keyword with the relational operator ==. Refer to Path Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on path expressions. Refer to Character Strings in Conditional Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on complete matches and relational operators. The following example shows how to search for documents in which the trip destination (destination) is specified as Head Office /doc/detail/destination == 'Head Office' Result Document C is returned. Performing a Size Comparison with a Search Keyword Example It is possible to search for documents that meet conditions by comparing the size between a character string in any element node of an XML document and any keyword. (The size relationship between character strings refers to the size relationship between the character code values of those strings.) This type of search is known as a size comparison search. The size comparison search is specified by connecting the path expression and the search keyword with the relational operator <, <=, > or >=. Refer to Path Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on path expressions. Refer to Character Strings in Conditional Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on size comparisons and relational operators. The following example shows how to search for documents in which the trip date (date) is later than 2004/02/01 /doc/basic/date > '2004/02/01' Result Document C is returned. Note To perform a size comparison between character codes, the character strings need to be in the same format. For example, if the date is specified as 2004/2/1, the intended documents will not be found. 3-14

39 Specifying the Search Expression Searching by Numeric Value Document A It is possible to search for documents that meet conditions by comparing the size between the data in any element node of an XML document and the numeric value of a keyword. For document searches using a numeric value, the character string in an element node in the XML document is treated as a numeric value. Therefore, unlike the size comparison search, the format of the character string need not be considered. The data in the element node specified by the path expression is treated as a numeric value and is compared to the numeric value specified by the keyword. The path expression and the search keyword are specified using a relational operator. The following relational operators can be used =,!=, <, <=, > and >=. The keyword is specified as a numeral not enclosed in quotes. Refer to Path Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on path expressions. Refer to Numeric Values in Conditional Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on numeric values and relational operators. The explanation that follows assumes that Documents A, B, and C, below exist <doc> <employee> <eno> </eno> <name>sara Jones</name> <sno>1001</sno> <phone> </phone> < >sara.jones@shunsaku.fujitsu.com.au/</ > </employee> <basic> <date>2004/02/16</date> <expense>$157.00</expense> </basic> </doc> Document B <doc> <employee> <eno> </eno> <name>lisa Taylor</name> <sno>2002</sno> <phone> </phone> < >lisa.taylor@shunsaku.fujitsu.com.au</ > </employee> <basic> <date>2004/02/18</date> <expense>$85.00</expense> </basic> </doc> 3-15

40 Chapter 3 Data Search Methods Example 1 The following example shows how to search for documents in which the section number (sno) is specified as 1001 /doc/employee/sno = 1001 Result Document A is returned. Searching by Joining Multiple Conditions with Logical Operators Document A Searches can be conducted using multiple conditions joined by logical operators. Logical operators make it possible to search for XML documents that satisfy two conditions, or that satisfy only one of two conditions. Logical operators include AND and OR. When both AND and OR are specified in a search expression, AND is evaluated before OR. Refer to Search Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on logical operators. The explanation that follows assumes that the following documents exist <doc> <basic> <date>2004/01/30</date> <expense>$157.00</expense> </basic> <detail> <destination>melbourne Office </destination> <area>richmond, Melbourne</area> <purpose>attendance at Shunsaku Sales Meeting</purpose> </detail> </doc> 3-16

41 Specifying the Search Expression Document B <doc> <basic> <date>2004/02/16</date> <expense>$160.20</expense> </basic> <detail> <destination>sydney branch</destination> <area>balmain, Darlinghurst, Sydney</area> <purpose>v7.0l10 installation report</purpose> </detail> </doc> Document C <doc> <basic> <date>2004/03/02</date> <expense>$24.00</expense> </basic> <detail> <destination>head office</destination> <area>clearview, Belair, Adelaide</area> <purpose>regular Interstage meeting</purpose> </detail> </doc> Example 1 The following example shows how to search for documents that contain the keyword Interstage or Shunsaku in the trip purpose (purpose) /doc/detail/purpose = 'Interstage' OR /doc/detail/purpose = 'Shunsaku' Result Documents A and C are returned. 3-17

42 Chapter 3 Data Search Methods Example 2 The following example shows how to search for documents in which the trip expenses (expense) are more than $100.00and the trip area (area) includes Sydney /doc/basic/expense >= AND /doc/detail/area = 'Sydney' Result Document B is returned. Note Enclose the conditional expression in parentheses if it is necessary to evaluate OR preferentially. Example 3 To force OR to have precedence over AND, the OR conditional expression must be enclosed in parentheses. The following example shows how to search for documents in which the trip destination (destination) is Head Office or Sydney Branch and the trip date (date) includes 2004/02 (/doc/detail/destination == 'Head Office' OR /doc/detail/destination == 'Sydney Branch') AND /doc/basic/date = '2004/02' Result Document B is returned. 3-18

43 Sorting Search Results Sorting Search Results XML documents found using a search expression can be sorted according to a specified key before being returned. To do so, a sort expression is specified in the Shunsaku APIs. The sort expression is specified as a sort key text expression or as a single-line function specification. Refer to Sort Expressions in Appendix B, Format of Search, Return and Sort Expressions for more information on sort expressions. Sorting by Character String Document A It is possible to sort search results using a character string in any element nodes of an XML document. The size relationship between character strings refers to the size relationship between the character code values of those strings. To use a character string to sort search results, a key specification in the sort expression must be defined using either a text expression or the rlen singleline function. Refer to Sort Expression Format in Appendix B, Format of Search, Return and Sort Expressions for more information on key specifications. The explanation that follows assumes that the following documents exist <doc> <basic> <date>2004/01/22</date> </basic> <detail> <area>clayton, Richmond, Melbourne</area> </detail> </doc> Document B <doc> <basic> <date>2004/02/03</date> </basic> <detail> <area>manly, Balmain, Darlinghurst, Sydney</area> </detail> </doc> 3-19

44 Chapter 3 Data Search Methods Document C <doc> <basic> <date>2004/01/13</date> </basic> <detail> <area>ashgrove, Ascot, Brisbane</area> </detail> </doc> Document D <doc> <basic> <date></date> </basic> <detail> <area>griffith, Kingston, Deakin, Canberra</area> </detail> </doc> Example 1 The following example shows how to sort documents in ascending order according to the trip date (date) /doc/basic/date/text() Example 2 Result Documents are returned in the order C, A, B, D. To sort character codes in descending order, specify DESC after the key specification. The following example shows how to sort documents in descending order according to the trip date (date) /doc/basic/date/text() DESC 3-20

45 Sorting Search Results Result Documents are returned in the order B, A, C, D. Note If an XML document does not contain the text node specified in the text expression, that XML document will be returned last, regardless of whether a DESC specification is in place. In the above example, Document D would be returned last in both an ascending sort and a descending sort. Example 3 When a sort is performed using a character string, the first 20 bytes of that string are used as the sort key. Therefore, if the length of the character string specified as the key is greater than 20 bytes, bytes 21 onwards will not become part of the key, and the XML documents will not be sorted correctly. In such cases, the rlen function can be used in the key specification to determine how many characters from the start of the string will be used as the sort key. Refer to Single-line Function Specification in Appendix B, Format of Search, Return and Sort Expressions for more information on the rlen function. The following example shows how to sort documents according to the trip area (area) rlen(/doc/detail/area/text(),30) When the above is specified, the first 30 characters of the trip area will be used as the sort key. Sorting by Numeric Value Document A It is possible to sort character strings in element nodes of XML documents as if they were numeric values. To do so, specify the single-line val function in the key specification in the sort expression. A text expression is specified as the argument of the val function. Refer to Single-line Function Specification in Appendix B, Format of Search, Return and Sort Expressions for more information on single-line function specifications. The explanation that follows assumes that Documents A, B, C, and D below exist <doc> <basic> <expense>$76.50</expense> </basic> </doc> 3-21

46 Chapter 3 Data Search Methods Document B <doc> <basic> <expense>$129.80</expense> </basic> </doc> Document C <doc> <basic> <expense>no trip expenses required</expense> </basic> </doc> Document D <doc> <basic> <expense>$4.80</expense> </basic> </doc> Example 1 The following example shows how to sort documents in ascending order according to the trip expenses (expense) val(/doc/basic/expense/text()) Result Documents are returned in the order C, D, A, B. Notes If the character string in the text node in the XML document specified by the text expression does not contain a numeric value, the val function will treat the value of the node as 0. In this example, the trip expenses in Document C will be treated as 0. If the text node in the XML document specified by the text expression does not exist, that XML document will be returned last. 3-22

47 Sorting Search Results Example 2 Specifying DESC after the key specification will sort numeric values in descending order. The following example shows how to sort documents in descending order according to the trip expenses (expense) val(/doc/basic/expense/text()) DESC Result Documents are returned in the order B, A, D, C. Sorting with Multiple Keys Document A It is possible to perform a sort using the values of more than one element node in an XML document. Commas are used to separate key specifications in the sort expression. The keys can be either a numeric or character string. Multiple keys make it possible to perform more sophisticated sorting operations. For example, XML documents can be sorted in ascending order using one element node and, if that element node is the same in more than one document, the documents can be further sorted in ascending order using a second element node. Up to eight keys can be specified. The explanation that follows assumes that Documents A, B, and C below exist <doc> <basic> <date>2004/03/03</date> <expense>$76.50</expense> </basic> </doc> Document B <doc> <basic> <date>2004/03/03</date> <expense>$115.00</expense> </basic> </doc> 3-23

48 Chapter 3 Data Search Methods Document C <doc> <basic> <date>2004/03/10</date> <expense>$76.50</expense> </basic> </doc> Example Sort documents according to the trip date (date) and, if multiple documents contain the same trip date, then sort in descending order according to the trip expenses (expense) /doc/basic/date/text(),val(/doc/basic/expense/text()) DESC Result Documents are returned in the order B, A, C. 3-24

49 Extracting Search Results Extracting Search Results It is possible to search XML documents stored in Shunsaku and extract data in XML or text format. The search results are extracted using the return expression in the APIs provided by Shunsaku. Refer to Format Used when not Aggregating in Appendix B, Format of Search, Return and Sort Expressions for more information on return expressions. Extracting Data in XML Format Extracting the XML documents found by a search in XML format enables XML data manipulation APIs such as DOM and SAX to be used. To extract data in XML format, specify a path expression in the return parameter. This can be done in two ways, as shown below. Use the method appropriate to the situation. Extracting an Entire XML Document Extract the original XML document stored in Shunsaku without changing its format. This is the extraction method most often used. Extracting Data in XML Format by Specifying an Element Node Extract specified element nodes in XML format. Extracting an Entire XML Document An entire XML document can be extracted by specifying only / in the return expression. Example Extract an entire XML document / Result <doc> <employee> <eno> </eno> <name>sara Jones</name> <sno>1001</sno> <phone> </phone> < >sara.jones@shunsaku.fujitsu.com.au</ > </employee> <basic> <date>2004/02/16</date> <expense>$72.00</expense> </basic> <detail> <destination>head Office</destination> <area>clearview, Belair, Adelaide</area> <purpose>regular project meeting</purpose> <train>$66.00</train> <taxi>$6.00</taxi> <hotel></hotel> 3-25

50 Chapter 3 Data Search Methods <comment>none</comment> </detail> <report>must create and report a sales results chart by next meeting</report> </doc> Note When a sort expression is specified, XML documents found using the search expression will be returned in the order determined by the sort expression. Extracting Data in XML Format by Specifying an Element Node It is possible to specify a path expression in the return parameter to extract data under any node of an XML document in XML format. The data in the element node indicated by the path expression is expressed in XML format as an element under the root tag of the XML document. The explanations accompanying the following examples assume that the following single XML document has been found using a search expression. <doc> <employee> <eno> </eno> <name>sara Jones</name> <sno>1001</sno> <phone> </phone> < >sara.jones@shunsaku.fujitsu.com.au</ > </employee> <basic> <date>2004/02/16</date> <expense>$72.00</expense> </basic> <detail> <destination>head office</destination> <area>clearview, Belair, Adelaide</area> <purpose>regular project meeting</purpose> <train>$66.00</train> <taxi>$6.00</taxi> <hotel></hotel> <comment>none</comment> </detail> <report>must create and report a sales results chart by next meeting</report> </doc> Example 1 The following example shows how to extract the employee's name (name). /doc/employee/name 3-26

51 Extracting Search Results Example 2 Figure 3-2 Extracting Data in XML Format More than one return parameter can be specified in the return expression. Each path expression must be separated using a comma. The following example shows how to extract the employee name (name), basic information (basic) and the trip purpose (purpose). /doc/employee/name,/doc/basic,/doc/detail/purpose Result <doc><name>sara Jones</name><basic> <date>2004/02/16</date> <expense>$72.00</expense> </basic><purpose>regular project meeting</purpose></doc> Notes When a sort expression is specified, XML documents found using the search expression will be returned in the order determined by the sort expression. When multiple return parameters are specified, they must all be in the form of a path expression. They cannot be specified together with text expressions or single line function specifications (result is returned in XML format). If a return parameter that can match multiple elements is specified (i.e. more than one path expression, // or * is specified), the application will not be able to determine the relationship between the elements that have been extracted. If some elements do not exist, the application will not be able to determine which they are. The application will not be able determine the path to the extracted elements. In these situations, either extract the entire XML document, or extract data using a specification where the return parameter isolates a single element. 3-27

52 Chapter 3 Data Search Methods Extracting Data in Text Format It is possible to specify a text expression in the return expression to extract data under any node of an XML document in text format. It is also possible to include a single-line function specification in the return expression. When a single-line function specification is used, the results of the rlen function or the val function can be extracted in text format. Refer to Single-line Function Specification in Appendix B, Format of Search, Return and Sort Expressions for more information on single-line function specifications. The explanations accompanying the following examples assume that the following single XML document has been found using a search expression. <doc> <employee> <eno> </eno> <name>sara Jones</name> <sno>1001</sno> <phone> </phone> < >sara.jones@shunsaku.fujitsu.com.au</ > </employee> <basic> <date>2004/02/16</date> <expense>$72.00</expense> </basic> <detail> <destination>head Office</destination> <area>clearview, Belair, Adelaide</area> <purpose>regular project meeting</purpose> <train>$66.00</train> <taxi>$6.00</taxi> <hotel></hotel> <comment>none</comment> </detail> <report>must create and report a sales results chart by next meeting</report> </doc> Example 1 The following example shows how to extract a trip report (report) /doc/report/text() Result Must create and report a sales results chart by next meeting 3-28

53 Extracting Search Results Example 2 The following example shows how to extract numeric values from trip expenses (expense) val(/doc/basic/expense/text()) Result 7200 Example 3 More than one return parameter can be specified in the return expression. Each return parameter must be separated with a comma. If multiple return parameters are specified, the values of the results returned by those parameters are separated with a delimiter. When the Java APIs are used, the delimiter is a comma. When the C APIs are used, the delimiter is the character represented by character code \001. The following example shows how to extract the employee number (eno), the employee name (name), the trip date (date) and the trip purpose (purpose) /doc/employee/eno/text(),/doc/employee/name/text(),/doc/basic/date/text(), /doc/detail/purpose/text() Result When the Java APIs are used ,Sara Jones,2004/02/16,Regular project meeting Notes When a sort expression is specified, the search results will be returned in the order determined by the sort expression. When multiple return parameters are specified, all return parameters must be specified as either text expressions or single-line function specifications. They cannot be specified together with a path expression (result returns in XML format). 3-29

54 Chapter 3 Data Search Methods Extracting Aggregated Results XML documents found using a search expression can be grouped and aggregated according to a given key. To perform aggregation, include the aggregation function specification in the return expression. A group key must also be specified in the sort expression. To produce the results of the aggregation function specification, XML documents with the same group key are treated as a single group. The data indicated by the text expression specified as the argument of the aggregation function specification is treated as a numeric value for each group, and then totals, averages, and other values are determined. Refer to Format Used when Aggregating in Appendix B, Format of Search, Return and Sort Expressions for more information on return expressions. The following figure provides an overview of the aggregation process. Figure 3-3 Overview of the Aggregation Process This is the method used to decide how search results will be grouped, and what will be aggregated. Grouping Search Results Aggregating Search Results Grouping Search Results XML documents found using a search expression are grouped according to a given key. The key used to perform the grouping is specified in the sort expression. 3-30

55 Extracting Aggregated Results Grouping by Character String Document A Grouping can be performed using the value of an element node in an XML document. To group by a character string, specify a text expression in the key specification of the sort expression. The explanation that follows assumes that Documents A, B, C, and D, below exist <doc> <employee> <name>sara Jones</name> </employee> <detail> <area>griffith, Kingston, Deakin, Canberra </area> </detail> </doc> Document B <doc> <employee> <name>sara Jones</name> </employee> <detail> <area>clayton, Richmond, Melbourne</area> </detail> </doc> Document C <doc> <employee> <name>lisa Taylor</name> </employee> <detail> <area>clayton, Richmond, Melbourne</area> </detail> </doc> 3-31

56 Chapter 3 Data Search Methods Document D <doc> <employee> <name>lisa Taylor</name> </employee> <detail> <area>forrest, Kingston, Deakin, Canberra</area> </detail> </doc> Example 1 The following examples show how to group according to the employee name (name) /doc/employee/name/text() Example 2 Result Documents A and B are handled as one group, and documents C and D are handled as another group. The process of grouping by a character string takes place using the first 20 bytes of the string as a key. If the value in the XML document indicated by the key exceeds 20 bytes, differences in character strings from byte 21 onwards will be ignored, and dissimilar documents may end up being placed in the same group. In such cases, the rlen function can be included in the key specification to specify the number of characters from the start of the string that will be used as the key. Refer to Single-line Function Specification in Appendix B, Format of Search, Return and Sort Expressions for more information on the rlen function. The following example shows how to group according to the trip area (area) rlen(/doc/detail/area/text(),30) When the above is specified, grouping will occur using the first 30 characters of the trip area. Grouping by Numeric Value Search results are grouped by treating the value of an element node in an XML document as a numeric value. To group by numeric values, specify the single-line val function in the key specification of the sort expression. Specify a text expression as the argument of the val function. Refer to Single-line Function Specification in Appendix B, Format of Search, Return and Sort Expressions for more information on the val function. The following explanation assumes that Documents A, B, C, and D, below exist 3-32

57 Extracting Aggregated Results Document A <doc> <employee> <sno>2001</sno> </employee> </doc> Document B <doc> <employee> <sno>2002</sno> </employee> </doc> Document C <doc> <employee> <sno>2001</sno> </employee> </doc> Document D <doc> <employee> <sno>2002</sno> </employee> </doc> Example The following example shows how to group XML documents that contain the same section number (sno) val(/doc/employee/sno/text()) 3-33

58 Chapter 3 Data Search Methods Result Documents A and C are handled as one group, and documents B and D are handled as another group. Grouping by Multiple Keys Document A To group by multiple keys, specify the key specifications in the sort expression by separating them with commas. Each key specification can be specified as either a numeric or character string. When multiple key specifications are specified, XML documents that match all the key values will be handled as a single group. Up to eight key specifications can be specified. The following explanation assumes that Documents A, B, C, below exist <doc> <basic> <date>2004/03/03</date> </basic> <detail> <destination>head Office</destination> </detail> </doc> Document B <doc> <basic> <date>2004/03/03</date> </basic> <detail> <destination>head Office</destination> </detail> </doc> 3-34

59 Extracting Aggregated Results Document C <doc> <basic> <date>2004/03/10</date> </basic> <detail> <destination>head Office</destination> </detail> </doc> Example The following example shows how to group documents according to the trip destination (destination) and the trip date (date) /doc/detail/destination/text(),/doc/basic/date/text() Result Documents A and B are handled as one group, and document C is handled as another group. Aggregating Search Results Document A When an aggregation is performed, a group key is also extracted at the same time. The aggregation function specification and the key specified by the sort expression can be included in the return expression. Each return parameter is separated with a comma. If multiple return parameters are specified, the values returned by those parameters are separated with a delimiter. When the Java APIs are used, the delimiter is a comma. When the C APIs are used, the delimiter is the character represented by character code \001. The explanations accompanying the following examples assume that the following six XML documents have been found using a search expression. <doc> <detail> <destination>head Office</destination> <train>$86.00</train><taxi></taxi><hotel>$68.00</hotel> </detail> </doc> 3-35

60 Chapter 3 Data Search Methods Document B <doc> <detail> <destination>head Office</destination> <train>$9.00</train><taxi></taxi><hotel></hotel> </detail> </doc> Document C <doc> <detail> <destination>head office</destination> <train>$130.00</train><taxi></taxi><hotel>$80.00</hotel> </detail> </doc> Document D <doc> <detail> <destination>melbourne Office</destination> <train>$16.00</train><taxi>$6.00</taxi><hotel></hotel> </detail> </doc> Document E <doc> <detail> <destination>melbourne Office</destination> <train>$4.00</train><taxi>$7.00</taxi><hotel></hotel> </detail> </doc> 3-36

61 Extracting Aggregated Results Document F <doc> <detail> <destination>melbourne Office</destination> <train>$4.00</train><taxi>$6.00</taxi><hotel>$90</hotel> </detail> </doc> It is assumed that the following sort expression has been specified in all the examples that follow Sort expression /doc/detail/destination/text() Note The sort expression used for aggregation specifies the grouping key. Sorting is also performed using that key. DESC can also be specified in a sort expression used for aggregation. When DESC is specified, aggregation results can be extracted in descending order according to the size of the grouping key. Example 1 The following example shows how to find the average of traveling expenses (train) Return expression /doc/detail/destination/text(),avg(/doc/detail/train/text()) Result When the Java APIs are used Melbourne Office,75 Head Office,8 Example 2 The following example shows how to count the number of people who used taxis Return expression /doc/detail/destination/text(),count(/doc/detail/taxi/text()) Result When the Java APIs are used Melbourne Office, 3 Head Office,0 3-37

62 Chapter 3 Data Search Methods Notes If no value is indicated by the text expression used as the argument of the aggregation function, it will not be targeted for aggregation. In the above example, no one used a taxi to travel to the head office, so the count result is 0. If the value 0 is stored in the taxi element node, it will be targeted for aggregation. To prevent data stored in this way from being aggregated, the data can be excluded from the search process by specifying in the search expression the condition that the taxi fare must be greater than 0. Example 3 This example shows how to obtain the maximum taxi fare (taxi), the total accommodation costs (hotel), and the number of trips Return expression /doc/detail/destination/text(),max(/doc/detail/taxi/text()),sum(/doc/detai l/hotel/text()),count(/doc/detail/destination/text()) Result When the Java APIs are used Melbourne Office,7,90,3 Head Office,,225,3 Note If no value is indicated by the text expression used as the argument of the aggregation function, it will not be targeted for aggregation. In the above example, no one used a taxi to visit the head office, so there is no maximum value. 3-38

63 Chapter 4 Data Updating Methods This chapter explains how to use the Shunsaku APIs to update data. Overview of Data Updating Adding Data Deleting Data Updating Data 4-1

64 Chapter 4 Data Updating Methods Overview of Data Updating This section explains the basic concepts of updating XML documents stored in Shunsaku. XML documents can be updated with Shunsaku in the following two ways By adding, deleting or updating XML documents using an application By adding or deleting XML documents using the Management Console or commands. The following figure shows an overview of updating XML documents stored in Shunsaku. Figure 4-1 Updating XML Documents Stored in Shunsaku The XML document update process can be executed without holding up applications that search the XML documents. Multiple update processes initiated using an application can be executed at the same time. This is also true for update processes initiated using an application, update processes initiated from the Management Console, update processes initiated using an application and update processes initiated from commands. 4-2

65 Overview of Data Updating Multiple update processes for XML documents can run at the same time without conflict so long as they are updating different XML documents. If the XML documents being updated are the same, one process will be performed but the other process will report an error. Refer to the Operator's Guide (Advanced) for more information on conflicts between applications and commands. Refer to the Operator's Guide for more information on adding and deleting XML documents using the Management Console. Use the shundimport command when adding or deleting XML documents with commands. Refer to the Command Reference for more information on the shundimport command. 4-3

66 Chapter 4 Data Updating Methods Adding Data To add data using the API, specify the XML documents to be added. Multiple XML documents are added by either consecutively allocating multiple XML documents to a single area, or by allocating XML documents to multiple areas and then specifying them together. The following figure shows how to specify multiple XML documents when adding data using APIs. Figure 4-2 How to Specify Multiple XML Documents when Adding Data Using the API When multiple directors are being used, XML documents are added to either the insert point director in the Management Console, or to the director specified by in the InsertPoint parameter in the conductor environment file. Refer to the Operator's Guide for more information on the Management Console. 4-4

67 Adding Data Refer to the Operator's Guide (Advanced) for more information on the conductor environment file. The following figure shows how to specify the insert point director using the Management Console when multiple directors are being used. Figure 4-3 How to Specify the Data Insert Point Director using the Management Console 4-5

68 Chapter 4 Data Updating Methods The following figure shows how to specify the insert point director using the InsertPoint parameter in the conductor environment file when multiple directors are being used. Figure 4-4 How to Specify the Data Insert Point Director Using the Conductor Environment File 4-6

69 Deleting Data Deleting Data The following figure shows the flow for deleting data using the API. Figure 4-5 Flow for Deleting Data Using the API 1. Obtain the record ID of the XML document to be deleted. Perform a data search to identify the XML document to be deleted, and obtain its record ID. 2. Specify the record ID and delete the XML file. Invoke the API that will perform the deletion, specifying the obtained record ID, and delete the XML document. More than one record ID can be specified at once to delete multiple XML documents. 4-7

70 Chapter 4 Data Updating Methods Updating Data The following figure shows the flow for updating data using the API. Figure 4-6 Flow for Updating Data Using the API 1. Obtain the record ID of the XML document to be updated. Perform a data search to identify the XML document to be updated, and obtain its record ID. 2. Specify the record ID and XML document, and update the XML file. Invoke the API to perform the update, specifying the obtained record ID and the replacement XML document, and update the XML document. More than one record ID and replacement XML document can be specified at the same time to update multiple XML documents. If an XML document has been replaced since it was obtained, Shunsaku will notify an error in order to maintain the integrity of the data. The following figure shows how Shunsaku notifies errors in order to maintain data integrity. 4-8

71 Updating Data Figure 4-7 How Shunsaku Notifies Errors to Maintain Data Integrity If an error occurs with update processing, the following action will be taken. 4-9

72 Chapter 4 Data Updating Methods The following figure shows the flow of action taken when errors occur with update processing. Figure 4-8 Flow of Action Taken when Errors Occur with Update Processing 1. Re-identify the XML document to be updated and re-obtain its record ID. Perform another data search to identify the XML document to be updated, and re-obtain the latest XML document to be updated and its record ID. Alternatively, if it is known that the items specified in the search condition have not been updated, it is also possible to re-obtain the latest XML document to be updated and its record ID by specifying the known record ID. 2. Specify the record ID and XML document, and update the XML document. Invoke the API that will perform the update, specifying the re-obtained record ID and the replacement XML document, and update the XML document. 4-10

73 Chapter 5 Developing Java Applications This chapter explains how to develop applications that use the Java APIs provided by Shunsaku. Java API Overview Developing Applications with Apworks How to Use Java APIs Debugging Applications Character Encoding Used by Java APIs Error Messages that may be Output during API Use 5-1

74 Chapter 5 Developing Java Applications Java API Overview A Java API is an interface for manipulating Shunsaku data from an application written in Java. The following table lists the Java API classes. Table 5-1 Java API Classes Class ShunConnection ShunPreparedRecordID ShunPreparedStatement ShunResultSet ShunException Description Represents the connection with Shunsaku. Uses record IDs to perform data searches and update, and delete XML documents. Performs data searches and adds XML documents using search expressions. Represents the set of search results. Provides information about errors that occur in the Shunsaku Java API. Refer to the Java API Reference for more information on the Java APIs provided by Shunsaku. The Java APIs are used to create objects. The following table shows the timing by which the objects of each class are created and released. Table 5-2 Timing by Which the Objects of Each Class Are Created and Released Object name Creation timing Release timing ShunConnection ShunPreparedRecordID ShunPreparedStatement ShunConnection objects are created using a constructor. ShunPreparedRecordID objects are created by the preparedeleterecordid method, the preparesearchrecordid method and the prepareupdaterecordid method of the ShunConnection class. ShunPreparedStatement objects are created by the prepareinsert method and the preparesearch method of the ShunConnection class. ShunConnection objects are released using the close method of the ShunConnection class. ShunPreparedRecordID objects are released using the close method of the ShunPreparedRecordID class. ShunPreparedStatement objects are released using the close method of the ShunPreparedStatement class. 5-2

75 Java API Overview Object name Creation timing Release timing ShunResultSet ShunException ShunResultSet objects are created by the searchbyrecordid method of the ShunPreparedRecordID class and the executesearch method of the ShunPreparedStatement class. ShunException objects are created when an error occurs in the Java API. ShunResultSet objects are released using the close method of the ShunResultSet class. ShunException objects are released when the application terminates. 5-3

76 Chapter 5 Developing Java Applications Developing Applications with Apworks Shunsaku applications can be developed efficiently using the Java integrated development environment Apworks. Apworks is equipped with functions that can aid in the development of Shunsaku applications. It features an interactive wizard that enables application prototypes to be developed automatically, which makes it possible to develop applications efficiently and with a minimum of effort. Advantages of Developing with Apworks Using Apworks to develop Shunsaku applications has the following benefits Prototypes of classes to return search results from Shunsaku are created automatically. Business applications can be created easily by simply adding business logic to source code that is generated automatically. It is easy to create Web applications that link to Interstage Application Server and Framework Suite. Flow of Development Using Apworks This section briefly explains the flow of Web application development using Apworks. For details, refer to the following online Interstage Apworks manuals Apdesigner Programmer s Guide Apdesigner User s Guide Apdesigner Tutorial The following diagram shows the flow of development using Apworks. 5-4

77 Developing Applications with Apworks Figure 5-1 Flow of Development Using Apworks Create Project Create a project for the type of application to be created. Projects can be created easily using a creation wizard. To create a Shunsaku Web application, select Web Application Project (Apcoordinator). Create and Edit Source A prototype Web application to display search results obtained from Shunsaku on the screen is automatically created. The developer can efficiently create applications with a minimum amount of development work. Note that Apworks does not create a prototype application for updating Shunsaku. This means that the developer needs to write an application that uses Java APIs to update Shunsaku access classes, and business classes are generated automatically. Create Shunsaku Access Class This class makes it easy to handle interfaces that can search for XML documents that use the Java APIs. It is created using the Shunsaku access source creation wizard. Create Search Method Use the Search Methods page of the Shunsaku Access Source Wizard to add a search method to the Shunsaku access class. More than one search method can be created. 5-5

78 Chapter 5 Developing Java Applications Create Sort Expression Use the Sort Expression page of the Shunsaku Access Source Wizard to add a sort expression to the Shunsaku access class. Create Data Classes This class stores XML documents and record IDs that were found with a search. Data classes are created using information defined by the Data Classes page of the Shunsaku Access Source Wizard. Create Data Bean This class stores I/O data exchanged between a Web application and a client. Data beans are created by inheriting the com.fujitsu.uji.databean class and their properties are created in JavaBean format. Create I/O Pages (JSP) Create the pages needed by the Web application. It is also possible to create pages to display errors. Create Business Class This class data specifies processing to be performed on data that is input from a client. The developer should code business logic in the prototype business class generated automatically. The following diagram shows the typical configuration of an automatically created Web application for accessing Shunsaku. Figure 5-2 Configuration of Automatically Created Web Application for Accessing Shunsaku The content of each process is as follows (1) The character string entered into the search page is passed to the application. (2) The received character string is passed to the access class, and search conditions and other information are set. (3) Search results are obtained from Shunsaku. (4) The XML structure of each search result is analyzed and the appropriate data classes are created. (5) A list is created based on the search results and the list is set in the data bean. 5-6

79 Developing Applications with Apworks (6) The search result list is displayed. (7) Results selected from the search result list are obtained. (8) JSP files that match the data classes of the selected results are used to display all the data of the results. Build It is easy to build source code that has been created or edited. Execute Created Web applications can be executed easily. Debug If a created Web application contains a bug, the debugger can be used to correct logical errors. 5-7

80 Chapter 5 Developing Java Applications How to Use Java APIs This section explains how to use the Java APIs. Establishing a Connection To establish a connection, a ShunConnection object is created. Specify the host name and port number of the connection destination by one of the following methods Configuring Settings in the API Environment File Setting Java Properties Specifying the Host Name and Port Number Directly Configuring Settings in the API Environment File Entry Format This section explains how to establish a connection by configuring settings in the API environment file. ShunConnection object name = new ShunConnection(); Entry Example ShunConnection con = new ShunConnection(); Entry Examples for Apworks When using Apworks, specify code in the business class similar to that shown in the example above. Refer to Setting Up Environment Files in Chapter 2, Environment Setup for more information on API environment file settings. Setting Java Properties This section explains how to establish a connection by setting Java Properties. Entry Format for the Java Properties Object connection.host= host name or IP address connection.port= port number 5-8

81 How to Use Java APIs Entry Items connection.host Specify either the host name or the IP address of the connection destination. connection.port Specify the port number of the connection destination. Specification Example When the host name is 'DirSvr1' and the port number is '33101' connection.host=dirsvr1 connection.port=33101 Entry Example // Specify the file name String sfilename = "Property.txt"; // Load the host name and port number from the file Properties property = new Properties(); property.load(new FileInputStream(sFileName)); // Create a ShunConnection object ShunConnection con = new ShunConnection(property); Entry Examples for Apworks When using Apworks, specify code in the business class similar to that shown in the example above. Specifying the Host Name and Port Number Directly Entry Format This section explains how to establish a connection by specifying the host name and port number directly. ShunConnection object name = new ShunConnection(host name, port number); Arguments host name Specify either the host name or the IP address of the connection destination. port number Specify the port number of the connection destination. 5-9

82 Chapter 5 Developing Java Applications Entry Example When the host name is 'DirSvr1' and the port number is '33101' ShunConnection con = new ShunConnection("DirSvr1",33101); Entry Examples for Apworks When using Apworks, specify code in the business class similar to that shown in the example above. Data Searches Java APIs can be used to perform the following operations Obtain the number of XML documents that match search conditions Obtain the XML documents that match search conditions in a specified format Obtain all of a particular XML document Find XML documents that match search conditions and obtain the documents after they are sorted Obtain consecutive groups of XML documents that match search conditions Find XML documents that match search conditions and obtain the documents after their contents are aggregated These operations can be combined to create a wide range of applications. Sample programs for finding data are provided in Searching Data in Appendix C, Sample Java Programs. The following sections explain how to create an application that will perform data searches. Obtaining the Number of XML Documents that Match Search Conditions Sometimes it is desirable to obtain the number of items that match specific search conditions before extracting the actual data. To obtain only the number of matching items, specify 0 as the number of items to return per request (requestcount) for the setrequest method. The following diagram shows the process for obtaining the number of XML documents that match specified conditions. 5-10

83 How to Use Java APIs Figure 5-3 Flow of the Process for Obtaining the Number of XML Documents that Match Conditions Entry Example ShunConnection con = new ShunConnection(); String queryexpression = "/document/base/city == 'Sydney'"; String returnexpression = "/ "; ShunPreparedStatement pstmt = con.preparesearch(queryexpression, returnexpression); (1) pstmt.setrequest(1,0); (2) ShunResultSet rs = pstmt.executesearch(); (3) System.out.println("[Number of hits] = " + rs.gethitcount()); (4) rs.close(); (5) pstmt.close(); (5) con.close(); (1) Create a ShunPreparedStatement Object Create a ShunPreparedStatement object by specifying a search expression and a return expression as parameters of the preparesearch method. Refer to Appendix B, Format of Search, Return and Sort Expressions for more information on search expressions and return expressions. (2) Set the Reply Start Number and the Number of Items to Return per Request Specify the reply start number and the number of items to return per request in the setrequest method. To obtain only the number of matching items, specify 0 as the number of items to return per request. (3) Execute the Search (create a ShunResultSet Object) Execute the search using the executesearch method. A ShunResultSet object will be created to hold the results of the search. (4) Obtain the number of XML documents that match search conditions Use the gethitcount method to obtain the number of XML documents that match the search conditions. (5) Release the ShunResultSet Object and the ShunPreparedStatement Object Always use the close methods of the ShunResultSet object and the ShunPreparedStatement object to release these objects when they are no longer required. 5-11

84 Chapter 5 Developing Java Applications Entry Examples for Apworks The following is sample code for a business class that uses a Shunsaku access class created with the Apworks interactive wizard, and a prototype Shunsaku access class that is used by the business class. Business Class ShunConnection con = new ShunConnection(); ShunsakuAccessController controller = new ShunsakuAccessController(con); controller.search(key); int hitcount = controller.gethitcount(); controller.close(); con.close(); ShunPreparedStatement Object public class ShunsakuAccessController { private ShunPreparedStatement pstmt; search Method of Shunsaku Access Class public void search(java.lang.string keys) throws ShunException { querystring = /document/base/city == + keys + ; returnstring = / ; getpreparedstatement(querystring, returnstring); (a) (b) private void getpreparedstatement(string querystring, String returnstring) { pstmt = con.preparedsearch(querystring, returnstring); (1) (a) Search Expression This expression is defined using the interactive wizard. The interactive wizard can also be used to create complex search expressions. (b) Return Expression / is specified here to extract the entire XML document. 5-12

85 How to Use Java APIs gethitcount Method of Shunsaku Access Class public int gethitcount() throws ShunException { resultset = getresultset(shunsakuaccesscontroller.sort_none, 1, 0); hitcount = resultset.gethitcount(); (4) resultset.close(); (5) public ShunResultSet getresultset(string sortstring, int position, int requestcount) throws ShunException { pstmt.setrequest(position, requestcount); (2) return pstmt.executesearch(); (3) close Method of Shunsaku Access Class public void close() throws ShunException { pstmt.close(); (5) Obtaining Search Results According to the Number of Data Items In general, Web applications do not display all the search results on a single page, but limit the number of items shown on each page. Specify the reply start number (position) and the number of items to return per request (requestcount) in the setrequest method to control the number of items of data to be obtained. The following diagram shows the process for obtaining search results according to the number of data items. 5-13

86 Chapter 5 Developing Java Applications Figure 5-4 Flow of the Process for Obtaining Search Results According to the Number of Data Items Entry Example ShunConnection con = new ShunConnection(); String queryexpression = "/document/base/city == 'Sydney'"; String returnexpression = "/document/base/name, /document/base/price "; ShunPreparedStatement pstmt = con.preparesearch(queryexpression, returnexpression); (1) pstmt.setrequest(11,5); (2) ShunResultSet rs = pstmt.executesearch(); (3) System.out.println("[Number of hits] = " + rs.gethitcount());(3) while(rs.next()) { (4) System.out.println("[Search results] = " + rs.getstring());(4) rs.close(); (5) pstmt.close(); (5) con.close(); 5-14

87 How to Use Java APIs (1) Create a ShunPreparedStatement Object Create a ShunPreparedStatement object by specifying a search expression and a return expression as parameters of the preparesearch method. Refer to Appendix B, Format of Search, Return and Sort Expressions for more information on search expressions and return expressions. (2) Set the Reply Start Number and the Number of Items to Return per Request Specify the reply start number and the number of items to return per request in the setrequest method. If the setrequest method is omitted, the number of items to return per request will be set to the value specified in the AnsMax parameter in the conductor or director environment file. Note For the number of items to return per request, specify the number of data items to display on each page. (3) Execute the Search (Create a ShunResultSet Object) Execute the search using the executesearch method. A ShunResultSet object will be created to hold the results of the search. Note The number of hits (XML documents that match the search conditions) can be obtained using the gethitcount method. This value can be used to find such things as the number of pages of the search results. (4) Extract the Results of the Search Always invoke the next method before extracting the results of the search. The next method returns true if there is still more data that can be extracted and false otherwise. Different methods can be used to extract XML documents for different objectives. The following table shows the methods that can be used. Table 5-3 Methods that Can be Used to Extract XML Documents Method getstring getstringarray getstream Function Extracts XML documents as String objects. Extracts XML documents as a two-dimensional array of String objects. Extracts XML documents as InputStream objects. Note The getstringarray method is an effective way to extract search results in text format. The getrecordid method can be used to obtain record IDs (which uniquely identify each data item) in addition to the results of the search. Record IDs are used to extract, delete, and update the corresponding XML documents. (5) Release the ShunResultSet Object and the ShunPreparedStatement Object Use the close methods of the ShunResultSet object and the ShunPreparedStatement object to release these objects when they are no longer required. 5-15

88 Chapter 5 Developing Java Applications Entry Examples for Apworks The following is sample code for a business class that uses a Shunsaku access class created with the Apworks interactive wizard, and a prototype Shunsaku access class that is used by the business class. Business Class ShunConnection con = new ShunConnection(); ShunsakuAccessController controller = new ShunsakuAccessController(con); controller.search(key); Object[] resultdata = controller.getresultdata(shunsakuaccesscontroller.sort_none, 11, 5); controller.close(); con.close(); ShunPreparedStatement Object public class ShunsakuAccessController { private ShunPreparedStatement pstmt; search Method of Shunsaku Access Class public void search(string keys) throws ShunException { querystring = /document/base/city == + keys + ; returnstring = / ; getpreparedstatement(querystring, returnstring); (a) (b) private void getpreparedstatement(string querystring, String returnstring) { pstmt = con.preparedsearch(querystring, returnstring); (1) (a) Search Expression This expression is defined using the interactive wizard. The interactive wizard can also be used to create complex search expressions. (b) Return Expression / is specified here to extract the entire XML document. 5-16

89 How to Use Java APIs getresultdata Method of Shunsaku Access Class public Object[] getresultdata(string sortstring, int position, int requestcount) throws ShunException { ShunResultSet resultset = getresultset(sortstring, position, requestcount); Object[] resultdata = parseresultset(resultset); (4) resultset.close(); (5) public ShunResultSet getresultset(string sortstring, int position, int requestcount) throws ShunException { if(!sortstring.equals(sort_none)) { pstmt.setsort(sortstring); pstmt.setrequest(position, requestcount); (2) return pstmt.executesearch(); (3) close Method of Shunsaku Access Class public void close() throws ShunException { pstmt.close(); (5) Obtaining Search Results While Adding Search Conditions When a search produces a large number of hits, it is sometimes useful to be able to narrow down the scope of the search by adding more search conditions. In such cases, perform a new search process by creating a new search expression and adding extra search conditions to the search expression specified with the preparesearch method. By repeating this operation, the user can narrow the scope of the search while referring to the search results displayed on the screen. The following diagram shows the process for obtaining search results while adding search conditions. 5-17

90 Chapter 5 Developing Java Applications Figure 5-5 Flow of the Process for Obtaining Search Results While Adding Search Conditions Entry Example Sample code to add conditions while obtaining search results is provided in Obtaining Search Results According to the Number of Data Items. Conditions should be added to the search expression specified by the preparesearch method. Entry Examples for Apworks Sample code to add conditions while obtaining search results when using Apworks is provided in Obtaining Search Results According to the Number of Data Items Conditions should be added to the search expression specified by the search method of the Shunsaku access class. Extracting Record IDs Record IDs are used to extract, delete, and update the corresponding XML documents. The getrecordid method is used to extract record IDs. The following diagram shows how a record ID is extracted. 5-18

91 How to Use Java APIs Figure 5-6 Record ID Extraction Entry Example ShunConnection con = new ShunConnection(); String queryexpression = "/document/base/city == 'Sydney'"; String returnexpression = "/document/base/name, /document/base/price "; ShunPreparedStatement pstmt = con.preparesearch(queryexpression, returnexpression); (1) pstmt.setrequest(11,5); (2) ShunResultSet rs = pstmt.executesearch(); (3) while(rs.next()) { (4) System.out.println("[Record ID] = " + rs.getrecordid()); (4) rs.close(); (5) pstmt.close(); (5) con.close(); (1) Create a ShunPreparedStatement Object Create a ShunPreparedStatement object by specifying a search expression and a return expression as parameters of the preparesearch method. Refer to Appendix B, Format of Search, Return and Sort Expressions for more information on search expressions and return expressions. (2) Set the Reply Start Number and the Number of Items to Return per Request Specify the reply start number and the number of items to return per request in the setrequest method. If the setrequest method is omitted, the number of items to return per request will be set to the value specified in the AnsMax parameter in the conductor or director environment file. Note For the number of items to return per request, specify the number of data items to display on each page. (3) Execute the Search (Create a ShunResultSet Object) Execute the search using the executesearch method. A ShunResultSet object will be created to hold the results of the search. 5-19

92 Chapter 5 Developing Java Applications (4) Extract the Results of the Search As with extracting search results, always use the next method before extracting a record ID. The next method returns true if there is still more data that can be extracted and false otherwise. (5) Release the ShunResultSet Object and the ShunPreparedStatement Object Use the close methods of the ShunResultSet object and the ShunPreparedStatement object to release these objects when they are no longer required. Entry Examples for Apworks The following sample business class coding shows how to extract a record ID. For the Shunsaku access class, use the prototype created with the Apworks interactive wizard. Refer to Obtaining Search Results According to the Number of Data Items for more information on the Shunsaku access class prototype. Business Class ShunConnection con = new ShunConnection(); ShunsakuAccessController controller = new ShunsakuAccessController(con); controller.search(key); Object[] resultdata = controller.getresultdata(shunsakuaccesscontroller.sort_none, 11, 5); ShunAddressListModel listdata = new ShunAddressListModel(resultData); databean.setresultlist(listdata); ListModel resultlist = databean.getresultlist(); for(int i = 0; i < resultlist.getsize(); i++) { Object result = resultlist.getelementat(i); AddressData new_result = (AddressData)result; String recordid = new_result.getrecordid(); controller.close(); con.close(); Using Record IDs to Obtain Entire XML Documents When searching for a particular XML document, do not obtain the entire document immediately. Instead, start by obtaining the partial information that can effectively identify the document. The user can then use this partial information to pick out the desired XML document and obtain detailed information. To extract an entire XML document, use the record ID that is returned when the partial information is extracted. Using a record ID enables desired entire XML documents to be extracted. The following diagram shows the process for using record IDs to obtain an entire XML document. 5-20

93 How to Use Java APIs Figure 5-7 Flow of the Process for Using Record IDs to Obtain an Entire XML Document Entry Example ShunConnection con = new ShunConnection(); ShunPreparedRecordID prid = con.preparesearchrecordid(); (1) prid.add(recordid); (2) ShunResultSet rs = prid.searchbyrecordid(); (3) while (rs.next()) { (4) System.out.println("[Result] = " + rs.getstring()); (4) rs.close(); (5) prid.close(); (5) con.close(); (1) Create a ShunPreparedRecordID Object Use the preparesearchrecordid method to create a ShunPreparedRecordID object. (2) Specify the Record ID Use the add method to specify the record ID. Record IDs can be obtained using the getrecordid method. Multiple record IDs can be specified with the add method. Any existing record IDs will be overwritten if they are specified again. 5-21

94 Chapter 5 Developing Java Applications Note By specifying multiple record IDs with the add method, multiple XML documents can be obtained at once. (3) Execute the Search (Create a ShunResultSet Object) Execute the search using the searchbyrecordid method. A ShunResultSet object will be created to hold the results of the search. (4) Extract the Results of the Search Always invoke the next method before extracting the results of the search. The next method returns true if there is still more data that can be extracted and false otherwise. Different methods can be used to extract XML documents for different objectives. The following table shows the methods that can be used. Table 5-4 Methods that Can be Used to Extract XML Documents Method getstring getstream Function Extracts XML documents as String objects. Extracts XML documents as InputStream objects. (5) Release the ShunResultSet Object and the ShunPreparedRecordID Object Use the close methods of the ShunResultSet object and the ShunPreparedRecordID object to release these objects when they are no longer required. Entry Examples for Apworks The following sample code shows how to use a record ID to extract an entire XML document in the case of the business class and the Shunsaku access class. Business Class ShunConnection con = new ShunConnection(); ShunsakuAccessController controller = new ShunsakuAccessController(con); Object[] resultdata = controller.detail(recordid); controller.close(); con.close(); Shunsaku Access Class public Object[] detail(string recordid) throws ShunException { Object[] resultdata = null; ShunPreparedRecordID prid = con.preparesearchrecordid(); (1) prid.add(recordid); (2) ShunResultSet rs = prid.searchbyrecordid(); (3) try { resultdata = parseresultset(rs); (4) finally { rs.close(); (5) prid.close(); (5) 5-22

95 How to Use Java APIs return resultdata; Obtaining Sorted Data Sometimes it is useful to be able to sort the results of a search, using a particular element as a sort key. To obtain sorted partial information about the data, use the setsort method. The following diagram shows the process for obtaining data after it has been sorted. Figure 5-8 Flow of the Process for Obtaining Data after It Has Been Sorted Note When search results are sorted, the sort process looks up all of the XML documents that match the search conditions. To improve response performance, it is important to narrow down the data to be sorted by specifying a search expression that produces an appropriate number of hits. To find out how many XML documents match the search conditions before starting a sort process, specify 0 in the requestcount parameter (the number of items to return per request) of the setrequest method. 5-23

96 Chapter 5 Developing Java Applications Entry Example ShunConnection con = new ShunConnection(); String queryexpression = "/document/base/city == 'Sydney'"; String returnexpression = "/document/base/name, /document/base/price "; String sortexpression = "val(/document/base/price/text()) DESC"; (1) ShunPreparedStatement pstmt = con.preparesearch(queryexpression, returnexpression); (2) pstmt.setsort(sortexpression); (3) ShunResultSet rs = pstmt.executesearch(); (4) while(rs.next()) { (5) System.out.println("[Search results] = " + rs.getstring()); (5) rs.close(); (6) pstmt.close(); (6) con.close(); (1) Create a Sort Expression Create a sort expression. Refer to Sort Expressions in Appendix B Format of Search, Return and Sort Expressions, for more information on sort expressions. (2) Create a ShunPreparedStatement Object Specify a search expression and a return expression with the preparesearch method () to create a ShunPreparedStatement object. Refer to Appendix B Format of Search, Return and Sort Expressions for more information on search expressions and return expressions. (3) Set the Sort Expression Use the setsort method to set the sort expression. Note The total length of the sort keys specified in the sort expression determines the number of data items that can be returned. A maximum of 1,000 items can be returned. No more data can be returned even if a higher value is specified for the reply start number or the number of items to return per request. Use the getreturnablecount method to obtain the maximum number of data items that can be returned. Appendix E, Allowable Values provides a guide to the key lengths and the number of data items that can be returned. Consecutive data can be extracted by specifying an acquisition start position. This can be used to extract upwards of 1,000 items of data. Refer to Obtaining Consecutive Groups of XML Documents that Match Conditions for details. (4) Execute the Search (Create a ShunResultSet Object) Execute the search using the executesearch method. A ShunResultSet object will be created to hold the results of the search. (5) Extract the Results of the Search Always invoke the next method before extracting the results of the search. The next method returns true if there is still more data that can be extracted and false otherwise. Different methods can be used to extract XML documents for different objectives. The following table shows the methods that can be used. 5-24

97 How to Use Java APIs Table 5-5 Methods that Can be Used to Extract XML Documents Method getstring getstringarray getstream Function Extracts XML documents as String objects. Extracts XML documents as a two-dimensional array of String objects. Extracts XML documents as InputStream objects. Note The getstringarray method is an effective way to extract search results in text format. The getrecordid method can be used to obtain record IDs (which uniquely identify each data item) in addition to the results of the search. Record IDs are used to extract or delete the corresponding entire XML documents. (6) Release the ShunResultSet Object and the ShunPreparedStatement Object Use the close methods of the ShunResultSet object and the ShunPreparedStatement object to release these objects when they are no longer required. Entry Examples for Apworks The following is sample code for a business class that uses a Shunsaku access class created with the Apworks interactive wizard, and a prototype Shunsaku access class that is used by the business class. Business Class ShunConnection con = new ShunConnection(); ShunsakuAccessController controller = new ShunsakuAccessController(con); controller.search(key); Object[] resultdata = controller.getresultdata(shunsakuaccesscontroller.sort_1); controller.close(); con.close(); ShunPreparedStatement Object public class ShunsakuAccessController { private ShunPreparedStatement pstmt; search Method of Shunsaku Access Class Public void search(string keys) throws ShunException { querystring = /document/base/city == + keys + ; returnstring = / ; getpreparedstatement(querystring, returnstring); (a) (b) 5-25

98 Chapter 5 Developing Java Applications private void getpreparedstatement(string querystring, String returnstring) { pstmt = con.preparedsearch(querystring, returnstring); (2) (a) Search Expression This expression is defined using the interactive wizard. The interactive wizard can also be used to create complex search expressions. (b) Return Expression / is specified here to extract the entire XML document. getresultdata Method of Shunsaku Access Class public Object[] getresultdata(string sortstring) throws ShunException { resultset = getresultset(sortstring); resultdata = parseresultset(resultset); (5) resultset.close(); (6) public ShunResultSet getresultset(string sortstring) throws ShunException { return getresultset(sortstring, 1, Integer.MAX_VALUE); public ShunResultSet getresultset(string sortstring, int position, int requestcount) throws ShunException { if(!sortstring.equals(sort_none)) { pstmt.setsort(sortstring); (3) return pstmt.executesearch(); (4) Sort Expression The sort expression is created using the interactive wizard, and the sort identifier is defined as a constant of the Shunsaku access class. Public class ShunsakuAccessController { public static final String SORT_NONE = ; (1) public static final String SORT_1 = val(/document/base/price/text()) ; (1) 5-26

99 How to Use Java APIs close Method of Shunsaku Access Class public void close() throws ShunException { pstmt.close(); (6) Obtaining Consecutive Groups of XML Documents that Match Conditions It is often desirable for a Web application to be able to divide up search results into a fixed number of items and to obtain these as consecutive groups. XML documents can be obtained consecutively by specifying the last position information or the first position information obtained by the preceding search process as the acquisition start position or acquisition end position parameter of the setrequest method. The following diagram shows the process for obtaining consecutive groups XML documents that match conditions. Figure 5-9 Flow of the Process for Obtaining XML Documents that Match Conditions Consecutively 5-27

100 Chapter 5 Developing Java Applications Entry Example String queryexpression = "/document/base/prefecture == 'Sydney'"; String returnexpression = "/document/base/name, /document/base/price "; String sortexpression = "val(/document/base/price/text()) DESC"; ShunConnection con = new ShunConnection(); ShunPreparedStatement pstmt = con.preparesearch(queryexpression, returnexpression); pstmt.setsort(sortexpression); // Extraction direction int direction = 0; // First position information String sfirstpos = null; // Last position information String slastpos = null; // Change the setrequest settings according to the page to be displayed // To display the next page, set the direction to "NEXT". To display the previous page, set the direction to "PREV" if(direction == NEXT) { // Display the next page (2) pstmt.setrequest(slastpos, 30, pstmt.shun_direction_forward_exclusive); else if(direction == PREV) { // Display the previous page (3) pstmt.setrequest(sfirstpos, 30, pstmt.shun_direction_backward_exclusive); else{ // Display the first page (1) pstmt.setrequest(null, 30, 0); // Execute the search (4) ShunResultSet rs = pstmt.executesearch(); // Extract the results of the search (5) System.out.println("[Number of hits] = " + rs.gethitcount()); while(rs.next()) { System.out.println("[Search results] = " + rs.getstring()); // Store the first position information and last position information (6) sfirstpos = rs.getfirstposition(); slastpos = rs.getlastposition(); // Release ShunResultSet object (7) // Release ShunPreparedStatement object rs.close(); pstmt.close(); con.close(); 5-28

101 How to Use Java APIs (1) Display the First Page Specify the data acquisition position and the number of items to return per request with the setrequest method. Search processing that displays the first page will start extracting data from the first item, so specify null for the data acquisition position (the position of the first or last data item to be acquired). If null is specified for the data acquisition position, data will be extracted from the first item. (2) Display the Next Page Specify the data acquisition position, the number of items to return per request and the extraction direction with the setrequest method. For search processing that displays the next page, use the getlastposition method to obtain the last position information from the previous search, and then specify this position information as the data acquisition position (the acquisition start position). This specification makes it possible to obtain the data that follows the previously acquired data. (3) Display the Previous Page Specify the data acquisition position, the number of items to return per request and the extraction direction with the setrequest method. For search processing that displays the previous page, use the getfirstposition method to obtain the first position information from the previous search, and then specify this position information as the data acquisition position (the acquisition end position). This specification makes it possible to obtain the data that precedes the previously acquired data. (4) Execute the Search Execute the search using the executesearch method. A ShunResultSet object will be created to hold the results of the search. (5) Extract the Results of the Search Always invoke the next method before extracting the results of the search. The next method returns "true" if there is still more data that can be extracted and "false" otherwise. Use the getstring method to extract XML documents. (6) Store the first position information and last position information Store the first position information using the getfirstposition method. Store the last position information using the getlastposition method. (7) Release the ShunResultSet Object and the ShunPreparedStatement Object Use the close methods of the ShunResultSet object and the ShunPreparedStatement object to release these objects when they are no longer required. Entry Examples for Apworks Business Class // Search data on next page public void next(dispatchcontext context, shunproduct.shunproductbean databean) { execute(context, databean, ShunAccessController.FORWARD); // Search data on previous page public void back(dispatchcontext context, shunproduct.shunproductbean databean) { execute(context, databean, ShunAccessController.BACKWARD); // Execute search private void execute(dispatchcontext context, shunproduct.shunproductbean databean, int direction) { 5-29

102 Chapter 5 Developing Java Applications String key = databean.getkey(); ShunConnection connection = null; ShunsakuAccessController accesscontroller = null; // Connect to Shunsaku server connection = new ShunConnection("localhost", 33101); accesscontroller = new ShunsakuAccessController(connection); // Prepare for search accesscontroller.search(key); // Obtain data acquisition position String dataposition = null; if(direction == ShunsakuAccessController.FORWARD) { dataposition = databean.getlastposition(); else if(direction == ShunsakuAccessController.BACKWARD) { dataposition = databean.getfirstposition(); // Execute search Object[] resultdata = accesscontroller.getresultdata(shunaccesscontroller.sort_1, dataposition, 30, direction); int hit = resultdata.length; // Set number of hits, acquisition start position and acquisition end position in data Bean databean.sethitcount(hit); databean.setfirstposition(accesscontroller.getfirstposition()); databean.setlastposition(accesscontroller.getlastposition()); accesscontroller.close(); connection.close(); // Create and set result data and transfer to next page ShunProductListModel listdata = new ShunProductListModel(resultData); DataBean.setResultList(listData); DataBean.setVerb("output"); Context.setResponseBean("body", databean); Sort Expression public class ShunsakuAccessController { public static final String SORT_NONE = ""l; public static final String SORT_1 = "val(/document/base/price/text()) DESC"; 5-30

103 How to Use Java APIs Shunsaku Access Class public void search(string keys) throws ShunException { querystring = "/document/base/city == '" + keys + "'"; returnstring = "/"; getpreparedstatement(querystring, returnstring); private void getpreparedstatement(string querystring, String returnstring) { pstmt = con.preparedsearch(querystring, returnstring); public Object[] getresultdata(string sortstring, String dataposition, int requestcount, int direction)throws ShunException { ShunResultSet resultset; Object[] resultdata = null; // Execute search resultset = getresultset(sortstring, dataposition,requestcount,direction); this.lastposition = resultset.getlastposition(); this.firstposition = resultset.getfirstposition(); resultdata = parseresultset(resultset); return resultdata; public ShunResultSet getresultset(string sortstring, String dataposition, int requestcount, int direction)throws ShunException { ShunResultSet resultset; Object[] resultdata = null; // Specify sort expression if (!sortstring.equals(sort_non)) { this.fpreparedstatement.setsort(sortstring); // Set number of items to return per request this.fpreparedstatement.setrequest(dataposition, requestcount, direction); // Execute search and create ShunResultSet object return this.fpreparedstatement.executesearch(); public String getfirstposition() { return firstposition; public String getlastposition() { return lastposition; 5-31

104 Chapter 5 Developing Java Applications Aggregating the Content of Data that Matches Search Conditions Sometimes it is useful to be able to aggregate the results of a search, using the values of particular elements. Use the setsort method to aggregate the content of the data. By specifying an aggregation function in the return expression used as a parameter of the preparesearch method, the results of the search will be aggregated before they are returned. The aggregation process can be used to calculate totals, averages, maximums, minimums, and the number of items. The following diagram shows the process for aggregating the content of data that matches conditions. Figure 5-10 Flow of the Process for Aggregating the Content of the Data that Matches Search Conditions Entry Example ShunConnection con = new ShunConnection(); String queryexpression = "/document/base/city == 'Sydney'"; String returnexpression = "max(/document/base/price/text())"; (1) String sortexpression = "/document/base/city/text() "; (2) ShunPreparedStatement pstmt = con.preparesearch(queryexpression, returnexpression); (3) pstmt.setsort(sortexpression); (4) ShunResultSet rs = pstmt.executesearch(); (5) while(rs.next()) { (6) System.out.println("[Search results] = " + rs.getstring()); (6) rs.close(); (7) pstmt.close(); (7) con.close(); 5-32

105 How to Use Java APIs (1) Create a Return Expression Create a return expression. To aggregate the search results, specify an aggregation function in the return expression. Refer to Return Expressions in Appendix B, Format of Search, Return, and Sort Expressions for more information on how to specify return expressions and aggregation functions. (2) Create a Sort Expression Create a sort expression. Refer to Sort Expressions in Appendix B, Format of Search, Return, and Sort Expressions for more information on sort expressions. (3) Create a ShunPreparedStatement Object Specify a search expression and a return expression with the preparesearch method () to create a ShunPreparedStatement object. Refer to Appendix B Format of Search, Return and Sort Expressions for more information on search expressions and return expressions. (4) Set the Sort Expression Use the setsort method to set the sort expression. Note The total length of the sort keys specified in the sort expression determines the number of groups that can be returned. The maximum number of groups is 1,000. No more data can be returned even if a higher value is specified for the reply start number or the number of items to return per request. Use the getreturnablecount method to obtain the maximum number of data items that can be returned. Appendix E, Allowable Values provides a guide to the key lengths and the number of groups that can be returned. Consecutive data can be extracted by specifying an acquisition start position. This can be used to extract the data of upwards of 1,000 groups. Refer to Obtaining Consecutive Groups of XML Documents that Match Conditions for details. (5) Execute the Search (Create a ShunResultSet Object) Execute the search using the executesearch method. A ShunResultSet object will be created to hold the results of the search. (6) Extract the Results of the Search Always invoke the next method before extracting the results of the search. The next method returns true if there is still more data that can be extracted and false otherwise. Different methods can be used to extract XML documents for different objectives. The following table shows the methods that can be used. Table 5-6 Methods that Can be Used to Extract XML Documents Method getstring getstringarray getstream Function Extracts XML documents as String objects. Extracts XML documents as a two-dimensional array of String objects. Extracts XML documents as InputStream objects. (7) Release the ShunResultSet Object and the ShunPreparedStatement Object Use the close methods of the ShunResultSet object and the ShunPreparedStatement object to release these objects when they are no longer required. 5-33

106 Chapter 5 Developing Java Applications Entry Examples for Apworks To accomplish this process, specify an aggregation function in the return expression of the Shunsaku access class that has been generated automatically. The following examples show how to specify a Shunsaku access class and a business class that contain a return expression where an aggregation function has been specified. Business Class ShunConnection con = new ShunConnection(); ShunsakuAccessController controller = new ShunsakuAccessController(con); controller.search(key); ShunResultSet resultdata = controller.getresultset(shunsakuaccesscontroller.sort_1); controller.close(); con.close(); ShunPreparedStatement Object public class ShunsakuAccessController { private ShunPreparedStatement pstmt; search Method of Shunsaku Access Class public void search(string keys) throws ShunException { querystring = /document/base/city == + keys + ; returnstring = max(/document/base/price/text()) ; getpreparedstatement(querystring, returnstring); (a) (1)(b) private void getpreparedstatement(string querystring, String returnstring) { pstmt = con.preparedsearch(querystring, returnstring); (3) (a) Search Expression This expression is defined using the interactive wizard. The interactive wizard can also be used to create complex search expressions. (b) Return Expression Specify an aggregation function. 5-34

107 How to Use Java APIs getresultdata Method of Shunsaku Access Class public ShunResultSet getresultset(string sortstring) throws ShunException { return getresultset(sortstring, 1, Integer.MAX_VALUE); public ShunResultSet getresultset(string sortstring, int position, int requestcount) throws ShunException { if(!sortstring.equals(sort_none))) { pstmt.setsort(sortstring); (4) return pstmt.executesearch(); (5) Sort Expression The sort expression is created using the interactive wizard, and the sort identifier is defined as a constant of the Shunsaku access class. public class ShunsakuAccessController { public static final String SORT_NONE = ; (2) public static final String SORT_1 = val(/document/base/city/text()) ; (2) close Method of Shunsaku Access Class public void close() throws ShunException { pstmt.close(); (7) Updating Data Java APIs can be used to perform the following data updates Adding Data Deleting Data by Specifying Record IDs Updating Data by Specifying Record IDs A sample program to update data is provided in Updating Data in Appendix C, Sample Java Programs. The following sections explain how to create an application to perform data updates. 5-35

108 Chapter 5 Developing Java Applications Adding Data Use the prepareinsert method to add data. The following diagram shows the process for adding data. Figure 5-11 Flow of the Process for Adding Data Entry Example ShunConnection con = new ShunConnection(); ShunPreparedStatement pstmt = con.prepareinsert(); (1) // Read data from file FileInputStream ofis = new FileInputStream("newData.xml"); pstmt.add(ofis); (2) pstmt.executeinsert(); (3) pstmt.close(); (4) con.close(); (1) Create a ShunPreparedStatement Object Use the prepareinsert method to create a ShunPreparedStatement object. (2) Specify the Data to Add The following table shows the methods that can be used to add data. Table 5-7 Methods that Can be Used to Add Data Method add(string data) add(inputstream data) Function Adds String object data. Adds InputStream object data. Multiple items of data can be specified with the add method. Also, data that is stored in multiple files can be added by invoking the add method multiple times. However, a single data item cannot be split into multiple segments and then specified in multiple instances of the add method. (3) Add the Data Use the executeinsert method to add the data. 5-36

109 How to Use Java APIs (4) Release the ShunPreparedStatement Object Use the close method of the ShunPreparedStatement object to release the object when it is no longer required. Entry Examples for Apworks The following are entry examples available when Apworks is used. Business Class ShunConnection con = new ShunConnection(); ShunsakuAccessController controller = new ShunsakuAccessController(con); controller.insert(data); controller.close(); con.close(); Shunsaku Access Class public void insert(string data) throws ShunException { ShunPreparedStatement pstmti = fconnection.prepareinsert(); (1) pstmti.add(data); (2) pstmti.executeinsert(); (3) pstmti.close(); (4) Deleting Data by Specifying Record IDs Use the preparedeleterecordid method to delete data. The Java APIs use record IDs to delete data. Before deleting data, use the getrecordid method to obtain the record IDs of the data items to be deleted. The following diagram shows the process for deleting data by specifying a record ID. 5-37

110 Chapter 5 Developing Java Applications Figure 5-12 Flow of the Process for Deleting Data by Specifying a Record ID Entry Example ShunConnection con = new ShunConnection(); ShunPreparedRecordID prid = con.preparedeleterecordid(); (1) prid.add(recordid); (2) prid.deletebyrecordid(); (3) prid.close(); (4) con.close(); (1) Create a ShunPreparedRecordID Object Use the preparedeleterecordid method to create a ShunPreparedRecordID object. (2) Specify the record IDs of the Data Items to be Deleted Use the add method to specify the record ID. Record IDs can be obtained using the getrecordid method. Multiple record IDs can be specified with the add method. Any existing record IDs will be overwritten if they are specified again. Note By specifying multiple record IDs with the add method, multiple XML documents can be obtained at once. 5-38

111 How to Use Java APIs (3) Delete the Data Execute the delete process using the deletebyrecordid method. (4) Release the ShunPreparedRecordID Object Use the close method of the ShunPreparedRecordID object to release the object when it is no longer required. Entry Examples for Apworks The following are entry examples available when Apworks is used. Business Class String recordid = databean.getdetailbutton(); ShunConnection con = new ShunConnection(); ShunsakuAccessController controller = new ShunsakuAccessController(con); controller.delete(recordid); con.close(); Shunsaku Access Class public void delete(string recordid) throws ShunException { ShunPreparedRecordID prid = con.preparedeleterecordid(); (1) prid.add(recordid); (2) prid.deletebyrecordid(); (3) prid.close(); (4) Updating Data by Specifying Record IDs Use the prepareupdaterecordid method to update XML documents. The Java APIs use record IDs to update data. Before updating data, use the getrecordid method to obtain the record IDs of the data to be updated. The process of using a record ID to update an XML document refers to replacing an existing XML document with a new XML document. It is not possible to update part of the data contained in an existing XML document. The following diagram shows the process for updating data specifying a record ID. 5-39

112 Chapter 5 Developing Java Applications Figure 5-13 Flow of the Process for Updating Data Specifying a Record ID Entry Example ShunConnection con = new ShunConnection(); ShunPreparedRecordID prid = con.prepareupdaterecordid(); (1) prid.add(recordid, updatedata); (2) prid.updatebyrecordid(); (3) prid.close(); (4) con.close(); (1) Create a ShunPreparedRecordID Object The prepareupdaterecordid method is used to create a ShunPreparedRecordID object. (2) Specify the Record ID and the Data to be Updated The add method is used to specify the record ID and the data to be updated. The record ID is obtained using the getrecordid method. Multiple record IDs and items of data to be updated can be specified with the add method. If the same record ID already exists, both the record ID and the data to be updated will be overwritten if that record ID is specified again. 5-40

113 How to Use Java APIs Note By specifying multiple record IDs and items of data to be updated with the add method, multiple XML documents can be updated at once. (3) Execute the Update Use the updatebyrecordid method to execute the update process. (4) Release the ShunPreparedRecordID Object Use the close method of the ShunPreparedRecordID object to release the object when it is no longer required. Entry Examples for Apworks The following are entry examples available when Apworks is used. Business Class String recordid = databean.getdetailbutton(); ShunConnection con = new ShunConnection(); ShunsakuAccessController controller = new ShunsakuAccessController(con); controller.update(recordid, updatedata); con.close(); Shunsaku Access Class public void update(string recordid, String updatedata) throws ShunException { ShunPreparedRecordID prid = con.prepareupdaterecordid(); (1) prid.add(recordid, updatedata); (2) prid.updatebyrecordid(); (3) prid.close(); (4) Closing Connections Entry Example After the data searches or data updates have finished, close the connection to Shunsaku. Use the close method to close the connection. ShunConnection con = new ShunConnection(); con.close(); Entry Examples for Apworks When using Apworks, specify code similar to that shown in the above example. 5-41

114 Chapter 5 Developing Java Applications Error Handling If an error occurs with an application that uses the Java APIs, a ShunException is thrown. The methods of the ShunException class can be used to obtain the following information Error level Error message Entry Example try { catch (ShunException ex) { int errorlevel = ex.geterrlevel(); (1) switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message " + ex.getmessage()); (2) (1) Error level The error level can be obtained using the geterrlevel method. When errors occur, the connection to Shunsaku is sometimes closed forcibly. Users can check the error level to find out the state of the application where the error occurred. There are two error levels, as shown in the following table Table 5-8 Error Levels Constant SHUN_ERROR SHUN_ERROR_CONNECTION_ TERMINATED Meaning Indicates that a warning level error (such as a parameter error) has occurred. Retry from the point where the error occurred. An error has occurred, causing the connection to Shunsaku to be forcibly closed. Close the ShunConnection object where the error occurred, and then restart from establishing the connection. (2) Error message The error message can be obtained using the getmessage method. Refer to Error Messages that may be Output during API Use for more information on the error message. 5-42

115 Debugging Applications Debugging Applications This section explains how to debug applications. The following debugging methods are available during application development Debugging with the Debugger This method uses the Apworks debugger to examine or modify program variables while checking the behavior of an application. Debugging with Application Debugging Information This method checks debugging information that is output to the standard output or standard error output while an application is running. Debugging with the API Snapshot Function This method uses an API snapshot to check a variety of logged information. Each method is explained below. Debugging with the Debugger This debugging method uses the debugger provided by Apworks. The debugger makes it possible to detect logical errors in a newly developed application while the application is running. Debugging is normally carried out by setting breakpoints within a program s source code and then examining or modifying program variables while the program is paused at each breakpoint. Refer to the following Apworks online manuals for more information on debugging with the debugger Apdesigner User s Guide Debugging with Application Debugging Information This method involves coding the process for sending debugging information to standard output or standard error output into the application being developed, and then debugging the application based on the debugging information obtained. Debugging with the API Snapshot Function The API snapshot function logs a variety of I/O information relating to Java APIs. The following information can be read from this log and used for debugging purposes when developing applications that use Java APIs Method invocation sequences Return information, parameter information and any exception information relating to methods Method execution times. 5-43

116 Chapter 5 Developing Java Applications Information Output by the API Snapshot Function The following table shows the information that is output by the API snapshot function. Table 5-9 Information Output by the API Snapshot Function Type Various Java API I/O information Content Outputs the following information relating to a Java API that has been invoked by an application - Information relating to when the method was invoked - Information relating to when the method was returned - Information relating to when an exception occurred in the method Detailed information about the output content and format, and output examples, etc., can be found in Java API Method Information below. Environment Settings of the API Snapshot Function To output an API snapshot, set the following execution parameters in the API environment file SnapLevel LogFile LogFileSize LogFileBackup Refer to Setting Up Environment Files in Chapter 2, Environment Setup or Appendix A, Execution Parameters in API Environment Files for more information on the API environment file. Java API Method Information Output Format Level 1 Information about a method invoked from an application is output when the method is invoked by an application, when the method returns, and when an exception occurs. The API snapshot is output in CSV format. The output format for each output level is shown below. When a Method is Invoked Package name, connection ID, thread name, date, time, Call, class name, method name When a Method Returns Package name, connection ID, thread name, date, time, Return, class name, method name, method execution time 5-44

117 Debugging Applications When an Error is Returned Package name, connection ID, thread name, date, time, Throw, class name, method name, method execution time, exception class name Exception details string Level 2 When a Method is Invoked Package name, connection ID, thread name, date, time, Call, class name, method name, parameter information When a Method Returns Package name, connection ID, thread name, date, time, Return, class name, method name, method execution time, return value information When an Error is Returned Package name, connection ID, thread name, date, time, Throw, class name, method name, method execution time, exception class name Exception details string Output Content The following table lists the items that are output and their content. Table 5-10 Content of the Java API Method Information Output Output item Content Output level Level 1 Level 2 Package name Connection ID Displays the package name of the application that invoked the API. Outputs the identifier of the connection object. Thread name Outputs the thread name. Date Time Call Return Throw Outputs the method invocation start/end date in the format yyyy/mm/dd. Outputs the method invocation start/end time in the format hhmmss.ms. Call Indicates that the information relates to when a method was invoked. Return Indicates that the information relates to when a method was returned. Throw Indicates that an exception occurred in the method. 5-45

118 Chapter 5 Developing Java Applications Output item Content Output level Level 1 Level 2 Class name Outputs the name of the Java API class that was invoked. Method name Outputs the name of the Java API method that was invoked. Method execution time Outputs the period (in seconds) between the time that a method is invoked and the time that the method returns. Exception class name Outputs the exception class name if an exception occurs when a method is invoked. If the exception contains a details string, that details string will also be output. Parameter information Outputs parameter information (parameter type and value) in the following format when a method is invoked x - (Parameter type) Value or - (Parameter type)<object> If there are no parameters, this item will not be displayed. Return value information Outputs method return value information (return value type and value) in the following format x - (Return value type) Value or - (Return value type)<object> This item will not be output if the return value is void. Item is output x Item is not output 5-46

119 Debugging Applications Output Examples Level 1 The information that is output to a snapshot is output in the character encoding of the platform where the Java API is operating. Output examples for the different output levels are shown below. Normal Termination "JavaAPISample2", ,"main","2004/10/22"," ","Call", "ShunConnection","ShunConnection" "JavaAPISample2", ,"main","2004/10/22"," ","Return", "ShunConnection","ShunConnection",0.41 Abnormal Termination "JavaAPISample2", ,"main","2004/10/22"," ","Call","ShunCo nnection","shunconnection" "JavaAPISample2", ,"main","2004/10/22"," ","Throw","ShunC onnection","shunconnection",2.143, "com.fujitsu.shun.common.shunexception shn30606ueither the director or the conductor has not been started, or the port number is incorrect. at com.fujitsu.shun.core.accessstreambasic.connect(accessstreambasic.java181 ) at com.fujitsu.shun.core.accessstream.connect(accessstream.java133) at com.fujitsu.shun.core.accessstream.<init>(accessstream.java124) at com.fujitsu.shun.shunconnection.openconnection(shunconnection.java1600) at com.fujitsu.shun.shunconnection.<init>(shunconnection.java391) at JavaAPISample2.main(JavaAPISample2.java33) " Level 2 Normal Termination "JavaAPISample2", ,"main","2004/10/22"," ","Call","ShunCo nnection","shunconnection",, " (String)localhost,(int)10007,(String)file1" "JavaAPISample2", ,"main","2004/10/22"," ","Return","Shun Connection","ShunConnection",0.42,"" 5-47

120 Chapter 5 Developing Java Applications Abnormal Termination "JavaAPISample2", ,"main","2004/10/22"," ","Call","ShunCo nnection","shunconnection",," (String)localhost,(int)10007,(String)file1" "JavaAPISample2", ,"main","2004/10/22"," ","Throw","ShunC onnection","shunconnection",2.143, "com.fujitsu.shun.common.shunexception shn30606ueither the director or the conductor has not been started, or the port number is incorrect. at com.fujitsu.shun.core.accessstreambasic.connect(accessstreambasic.java181 ) at com.fujitsu.shun.core.accessstream.connect(accessstream.java133) at com.fujitsu.shun.core.accessstream.<init>(accessstream.java124) at com.fujitsu.shun.shunconnection.openconnection(shunconnection.java1600) at com.fujitsu.shun.shunconnection.<init>(shunconnection.java391) at JavaAPISample2.main(JavaAPISample2.java33) " Note Enclose character string items in double quotes ("). Do not enclose numerical values in double quotes ("). The operation of each connection can be traced chronologically by filtering the collected log file with the connection identifier. 5-48

121 Character Encoding Used by Java APIs Character Encoding Used by Java APIs This section explains the character encoding used by Java APIs. Specify Unicode as the character encoding to be used in conditional expressions, return expressions, and sort expressions. Search results are returned using the Unicode encoding. The following diagram shows the overall relationships between character encodings. Figure 5-14 Relationships between the Character Encodings Used by Java APIs 5-49

122 Chapter 5 Developing Java Applications Error Messages that may be Output during API Use This section explains the error messages that may be output when the Java API is being used. The getmessage method can be used to obtain the messages shown in this section. Message Output Format Messages that occur during the use of the Java API are output in the following format. Format message codemessage text Meaning message code A unique message identifier that is assigned to each message message text A message that reports the system status or a system error Output Example shn30605uthe requested host could not be found. Response to Messages Refer to the Messages or use the shunprtmsg command to determine what action to take in response to a message. Example The following example shows how to display the action to take in response to message code shn30605u. shn30605u The requested host could not be found. [Description] There is an error with the host name or IP address. [System action] Stops processing this method. [User response] Specify the correct host name or IP address with the ShunConnection method, and then rerun the command. Refer to the manual for information on how to specify host names and IP addresses. Refer to the Command Reference for more information on the shunprtmsg command. 5-50

123 Chapter 6 Developing C Applications This chapter explains how to develop applications that use the C APIs provided by Shunsaku. C API Overview How to Use C APIs Debugging Applications Character Encoding Used by the C APIs Error Messages that may be Output during API Use 6-1

124 Chapter 6 Developing C Applications C API Overview The C APIs are interfaces used to manipulate Shunsaku data from applications written in C. Applications that use C APIs create a connection handle to connect to Shunsaku and then create a data manipulation handle to perform searches and updates. The following diagram provides an overview of the C APIs. Figure 6-1 Overview of C APIs As the above diagram indicates, there are two types of C API handle The connection handle and the data manipulation handle. 6-2

125 C API Overview Table 6-1 C API Handles Handle Overview Creation lifetime Connection handle Data manipulation handle Opens and closes connections. Performs data searches and updates and retains search results Created for each connection. Created for each data manipulation. The two types of handle are in a parent-child relationship. Data manipulation handles are allocated on the basis of a connection handle. When a connection handle is released, the data manipulation handle(s) will also be released. Figure 6-2 Relationship between Connection Handles and Data Manipulation Handles Connection Handles Connection handles maintain connection information. They can be used to open or close connections. For example, when a connection is established, the connection handle retains the host information of the connection destination (host name and port number). And because it is possible to create multiple connection handles with a single process, connection handles can also be used in multi-thread environments. Connection handles can be used to perform the following operations. Table 6-2 Connection Handles Function name ShunGetConnectAttr ShunConnect ShunDisconnect Overview Obtain connection attributes Establish a connection Close a connection 6-3

126 Chapter 6 Developing C Applications Data Manipulation Handles Data manipulation handles can be used to perform data search and update operations. They also retain the data resulting from a search. Data manipulation handles can be used to perform the following operations. Table 6-3 Data Manipulation Handles Function name ShunGetHitCount ShunSearch ShunSearchRecld ShunInsert ShunDeleteRecld ShunUpdateRecld Overview Obtains the number of hits generated by a search expression. Searches for data using a search expression. Searches for an XML document using a record ID. Adds XML documents. Deletes an XML document using a record ID. Updates an XML document using a record ID. Common Functions Some operations can be performed by both connection handles and data manipulation handles. The common functions can be used to perform the following operations. Table 6-4 Common Functions Function name ShunAllocHandle ShunFreeHandle ShunGetErrorMessage Overview Allocates handles. Releases handles. Obtains error information. 6-4

127 How to Use C APIs How to Use C APIs This section explains how to use the C APIs. Establishing a Connection To establish a connection, allocate a connection handle and specify the host information of the connection destination (host name and port number) in the ShunConnect function. The host information of the connection destination is retained by the specified connection handle. Specify the host name and port number of the connection destination using one of the following methods Configuring Settings in the API Environment File Specifying the Host Name and Port Number Directly Configuring Settings in the API Environment File Entry Example This section explains how to establish a connection by making settings in the API environment file SHUNHCON ConH; /* Allocate connection handle */ ShunAllocHandle(NULL, &ConH); /* Specify the host name and port number in the API environment file to establish the connection */ ShunConnect(ConH, NULL, 0, NULL); Refer to Setting up Environment Files in Chapter 2, Environment Setup or Appendix A, Execution Parameters in API Environment Files for more information on the API environment file. Specifying the Host Name and Port Number Directly Entry Example This section explains how to specify the host name and port number directly. When the host name is DirSvr1 and the port number is SHUNHCON ConH; /* Allocate connection handle */ ShunAllocHandle(NULL, &ConH); /* Specify the host name and port number to establish the connection */ ShunConnect(ConH, "DirSvr1", 33101, NULL); 6-5

128 Chapter 6 Developing C Applications Data Searches C APIs can be used to perform the following operations Obtain the number of XML documents that match search conditions Obtain the XML documents that match search conditions in a specified format Obtain all of a particular XML document Find XML documents that match search conditions and obtain the documents after they are sorted Obtain consecutive groups of XML documents that match search conditions Find XML documents that match search conditions and obtain the documents after their contents are aggregated. These operations can be combined to create a wide range of applications. Sample programs for searching data are provided in 'Searching Data' in Appendix D, Sample C Programs. The following sections explain how to create an application that will perform data searches. Obtaining the Number of XML Documents that Match Search Conditions Sometimes it is desirable to obtain the number of items that match specific criteria before extracting the actual data. In such cases, specify the conditional expression as the argument of the ShunGetHitCount function and obtain the number of matching items only. The following diagram shows the process for obtaining the number of XML documents that match specified conditions. Figure 6-3 Process for Obtaining the Number of XML Documents that Match Search Conditions 6-6

129 How to Use C APIs Entry Example SHUNHSTMT StmtH; /* Allocate data manipulation handle */ ShunAllocHandle(ConH, &StmtH); (1) /* Specify the search expression and obtain the number of hits */ ShunGetHitCount(StmtH, "/document/base/city == 'Sydney'", &Hit_Cnt); (2) /* Extract number of hits */ printf("number of hits = %d\n", Hit_Cnt); /* Release data manipulation handle */ ShunFreeHandle(StmtH); (3) (1) Allocate the Data Manipulation Handle Allocate the data manipulation handle in advance by specifying the connection handle to be used as the parent handle in the ShunAllocHandle function. (2) Execute the Search Specify the data manipulation handle and the search expression as parameters of the ShunGetHitCount function and execute the search. Only the number of hits will be returned. (3) Release the Data Manipulation Handle After the data search has been performed and the results have been extracted, use the ShunFreeHandle function to release the data manipulation handle. Obtaining Search Results with a Specified Number of Data Items In general, Web applications do not display all the search results on a single page, but limit the number of items shown on each page. In order to control the number of items of data that will be obtained, specify the reply start number and the number of items to return per request as arguments of the ShunSearch function. The following diagram shows the process for obtaining search results according to the number of data items. 6-7

130 Chapter 6 Developing C Applications Figure 6-4 Process for Obtaining Search Results in Specified Quantities of Data Items Entry Example SHUNHSTMT StmtH; /* Allocate data manipulation handle */ ShunAllocHandle(ConH, &StmtH); (1) /* Execute search */ ShunSearch(StmtH, 11, NULL, 0, 5, "/document/base/city == 'Sydney'", "/document/base/name, /document/base/price ", NULL, &Hit_Cnt, &Return_Cnt, &Returnable_Cnt, &Rec_Id_Out, &Data, &First_Pos, &Last_Pos); (2) 6-8

131 How to Use C APIs /* Extract search results */ printf("number of hits = %d\n", Hit_Cnt); (3) if(hit_cnt > 0) { for (i = 0; i < Return_Cnt; i++) { printf("[result] Item No. %d= %s\n", i+1, Data[i].Data); /* Release data manipulation handle */ ShunFreeHandle(StmtH); (4) (1) Allocate Data Manipulation Handle Allocate the data manipulation handle in advance by specifying the connection handle to be used as the parent handle in the ShunAllocHandle function. (2) Execute the Search Specify the data manipulation handle, the data acquisition location (acquisition start position or acquisition end position), the maximum number of data items, the search expression and the return expression as parameters of the ShunSearch function and then execute the search. Notes The ShunSearch function returns the number of XML documents that match the search conditions. This value can also be used to find the number of pages of search results and so on. For the number of items to return per request, specify the number of data items to display on each page. (3) Extract the Results of the Search The ShunSearch function returns the address of the search results. Search results consist of arrays of structures, so data is extracted from these arrays. Note Together with the search results, the ShunSearch function also returns a record ID (conductor control information and a reply record identifier) that uniquely identifies an XML document. The record ID is used to extract, delete, and update the entire XML document that corresponds to it. (4) Release Data Manipulation Handle After the data search has been performed and the results have been extracted, use the ShunFreeHandle function to release the data manipulation handle. Obtaining Search Results while Adding Search Conditions When a search produces a large number of hits, it is sometimes useful to be able to narrow down the scope of search by adding more search conditions. In such cases, add conditions to the search expression specified as the argument of the ShunSearch function to create a new search expression, and run the search process again. By repeating this operation, the user can narrow the scope of the search while referring to the search results displayed on the screen. The following diagram shows the process for obtaining search results while adding search conditions. 6-9

132 Chapter 6 Developing C Applications Figure 6-5 Process for Obtaining Search Results While Adding Search Conditions Entry Example Sample code to obtain search results while adding search conditions is provided in Obtaining Search Results with a Specified Number of Data Items. Note Together with the search results, the ShunSearch function also returns a record ID (conductor control information and a reply record identifier) that uniquely identifies an XML document. The record ID is used to extract, delete, and update the entire XML document that corresponds to it. Using Record IDs to Obtain Entire XML Documents When searching for a particular XML document, do not obtain the entire document immediately. Instead, start by obtaining the partial information that can effectively identify the document. The user can then use this partial information to pick out the desired XML document and obtain detailed information. To extract an entire XML document, use the record ID (conductor control information and reply record identifiers) that is returned when the partial information is extracted. The entire target XML document can be extracted by specifying this record ID with the ShunSearchRecId function argument. 6-10

133 How to Use C APIs The following diagram shows the process for using record IDs to obtain entire XML documents. Figure 6-6 Process for Using Record IDs to Obtain Entire XML Documents Entry Example SHUNHSTMT StmtH; /* Allocate data manipulation handle */ ShunAllocHandle(ConH, &StmtH); (1) /* Specify record ID and execute search */ ShunSearchRecId(StmtH, 1, Rec_Id_In, &Rec_Id_Out, &Data); (2) /* Extract search results */ printf("[result] = %s\n", Data[0].Data); (3) /* Release data manipulation handle */ ShunFreeHandle(StmtH); (4) (1) Allocate Data Manipulation Handle Allocate the data manipulation handle in advance. Allocate the data manipulation handle in advance by specifying the connection handle to be used as the parent handle in the ShunAllocHandle function. 6-11

134 Chapter 6 Developing C Applications (2) Execute the Search Specify the data manipulation handle, the number of requested records and, the requested record ID array as parameters of the ShunSearchRecId function, and then execute the search. Note By specifying multiple record IDs with the ShunSearchRecId function, multiple XML documents can be obtained at a time. (3) Extract Search Results The ShunSearchRecId function returns the address of the search results. Search results consist of arrays of structures, so data is extracted from these arrays. If no XML document exists, NULL will be set in the pointer to the element data in the array, and the data size will be set to zero. (4) Release Data Manipulation Handle After the data search has been performed and the results have been extracted, use the ShunFreeHandle function to release the data manipulation handle. Obtaining Sorted Data Sometimes it is useful to be able to sort the results of a search, using a particular element as a sort key. To obtain sorted partial information about the data, specify a sort expression in the ShunSearch function and execute the search. The following diagram shows the process for obtaining data after it has been sorted. 6-12

135 How to Use C APIs Figure 6-7 Process for Obtaining Data after Sorting Entry Example SHUNHSTMT StmtH; /* Data manipulation handle */ ShunAllocHandle(ConH, &StmtH); (1) /* Specify sort expression and execute search */ ShunSearch(StmtH, 1, NULL, 0, 30, "/document/base/city == 'Sydney'", "/document/base/name, /document/base/price ", "/document/base/price/text() DESC", &Hit_Cnt, &Return_Cnt, &Returnable_Cnt, &Rec_Id_Out, &Data, &First_Pos, &Last_Pos); (2) /* Extract search results */ printf("number of hits = %d\n", Hit_Cnt); (3) if(hit_cnt > 0) { for (i = 0; i < Return_Cnt; i++) { printf("[result] Item No. %d = %s\n", i+1, Data[i].Data); 6-13

136 Chapter 6 Developing C Applications /* Release data manipulation handle */ ShunFreeHandle(StmtH); (4) (1) Allocate Data Manipulation Handle Allocate the data manipulation handle in advance by specifying the connection handle to be used as the parent handle in the ShunAllocHandle function. (2) Execute the Search Specify the data manipulation handle, the data acquisition location (acquisition start position or acquisition end position), the maximum number of data items, the search expression, and the return expression as parameters of the ShunSearch function and then execute the search. Notes When a sort expression is specified in the ShunSearch function, the sorting process will reference all the XML documents that match the search conditions. To improve response performance, specify conditions in the search expression that produce an appropriate number of results, and narrow down the data to be sorted. Before executing a sort, use the ShunGetHitCount function to check how many XML documents match the search conditions. The total length of the sort keys specified in the sort expression determines the number of data items that can be returned. A maximum of 1,000 items can be returned. No more data can be returned even if a higher value is specified for the data acquisition position or the maximum number of data items. The maximum number of data items that can be returned is returned to the output parameter of the ShunSearch function. Appendix E, Allowable Values provides a guide to the key lengths and the number of data items that can be returned. Consecutive data can be extracted by specifying a data acquisition position. This makes it possible to extract more than 1,000 items of data. Refer to Obtaining Consecutive Groups of XML Documents that Match Conditions for details. (3) Extract the Results of the Search The ShunSearch function returns the address of the search results. Search results consist of structure arrays, so data is extracted from these arrays. Note Together with the search results, the ShunSearch function also returns a record ID (conductor control information and a reply record identifier) that uniquely identifies an XML document. The record ID is used to extract, delete, and update the entire XML document that corresponds to it. (4) Release Data Manipulation Handle After the data search has been performed and the results have been extracted, use the ShunFreeHandle function to release the data manipulation handle. Obtaining Consecutive Groups of XML Documents that Match Conditions It is often desirable for a Web application to be able to divide up search results into a fixed number of items and to obtain these as consecutive groups. XML documents can be obtained consecutively by specifying the last position information or the first position information obtained by the preceding search process as the acquisition start position or acquisition end position argument of the ShunSearch function. The following diagram shows the process for consecutively obtaining XML documents that match conditions. 6-14

137 How to Use C APIs Figure 6-8 Process for Obtaining XML Documents that Match Conditions Consecutively Entry Example SHUNHSTMT StmtH; SHUNPOS *First_Pos, *Last_Pos; int idirection, Direction; SHUNPOS *sfirst_pos, *slast_pos, Reply_Pos; /* Allocate data manipulation handle */ (1) ShunAllocHandle(ConH, &StmtH); // Change the settings for the third and fourth parameters of the ShunSearch function according to the page to be displayed // To display the next page, set idirection to "NEXT". To display the previous page, set idirection to "PREV" if(idirection == NEXT) { // Display the next page (3) Reply_Pos = slast_pos; Direction = SHUN_DIRECTION_FORWARD_EXCLUSIVE; else if(idirection == PREV) { // Display the previous page (4) 6-15

138 Chapter 6 Developing C Applications Reply_Pos = sfirst_pos; Direction = SHUN_DIRECTION_BACKWARD_EXCLUSIVE; else{ // Display the first page (2) Reply_Pos = NULL; Direction = 0; /* Execute the search */ (5) ShunSearch(StmtH, 1, Reply_Pos, Direction, 30, Search_Exp, Return_Exp, Sort_Exp, &Hit_Cnt, &Return_Cnt, &Returnable_Cnt, &Rec_Id_Out, &Data, &First_Pos, &Last_Pos); /* Extract search results */ (6) printf("number of hits = %d\n", Hit_Cnt); if(hit_cnt!= 0) { for (i = 0; i < Return_Cnt; i++) { printf("[result] %s\n", Data[i].Data); /* Store first position information and last position information */ (7) slast_pos = Last_Pos; sfirst_pos = First_Pos; /* Release data manipulation handle */ (8) ShunFreeHandle(StmtH); (1) Allocate Data Manipulation Handle Allocate the data manipulation handle in advance by specifying the connection handle to be used as the parent handle in the ShunAllocHandle function. (2) Display the First Page For search processing that displays the first page, specify NULL for the data acquisition position (acquisition start position or acquisition end position) in order to start extracting data from the first item. When NULL is specified as the acquisition position, data extraction will commence from the position specified by the reply start number. (3) Display the Next Page For search processing that displays the next page, specify the last position from the previous search as the acquisition start position. This makes it possible to obtain the data on the page that follows the previously acquired data. (4) Display the Previous Page For search processing that displays the previous page, specify the first position from the previous search as the acquisition end position. This makes it possible to obtain the data that precedes the previously acquired data. (5) Execute the Search Execute the search by specifying the data manipulation handle, the data acquisition position (acquisition start position or acquisition end position), the maximum number of data items, the search expression, the return expression, and the areas for receiving start and end position information as parameters of the ShunSearch function. 6-16

139 How to Use C APIs Note The area for receiving start or end position information can be the same as the area specified for the acquisition start position or the acquisition end position. In this case, the old position information will be destroyed after it is used to locate the acquisition start position, and new position information will be set in this area by the current search. (6) Extract Search Results The ShunSearch function returns the address of the search results. Search results consist of structure arrays, so data is extracted based on this structure form. (7) Store the First Position Information and Last Position Information Store the first position information and last position information. (8) Release Data Manipulation Handle After the data search has been performed and the results have been extracted, use the ShunFreeHandle function to release the data manipulation handle. Aggregating the Content of the Data that Matches Search Conditions Sometimes it is useful to be able to aggregate the results of a search, using the values of particular elements. Use the ShunSearch function to aggregate the content of the data. By specifying an aggregation function in the return expression used as an argument of the ShunSearch function, the results of the search will be aggregated before they are returned. The aggregation process can be used to calculate totals, averages, maximums, minimums, and the number of items. The following diagram shows the process for aggregating the content of the data that matches conditions. Figure 6-9 Process for Aggregating the Content of the Data that Matches Search Conditions Entry Example SHUNHSTMT StmtH; /* Allocate data manipulation handle*/ ShunAllocHandle(ConH, &StmtH); (1) /* Execute aggregation */ ShunSearch(StmtH, 1, NULL, 0, 30, "/document/base/city == 'Sydney'", "max(/document/base/price/text())", "/document/base/city/text() ", 6-17

140 Chapter 6 Developing C Applications &Hit_Cnt, &Return_Cnt, &Returnable_Cnt, &Rec_Id_Out, &Data, &First_Pos, &Last_Pos); (2) /* Extract aggregated results */ printf("number of hits = %d\n", Hit_Cnt); (3) if(hit_cnt > 0) { for (i = 0; i < Return_Cnt; i++) { printf("[result] Item No. %d = %s\n", i+1, Data[i].Data); /* Release data manipulation handle */ ShunFreeHandle(StmtH); (4) (1) Allocate Data Manipulation Handle Allocate the data manipulation handle in advance by specifying the connection handle to be used as the parent handle in the ShunAllocHandle function. (2) Execute Aggregation Specify the data manipulation handle, the data acquisition location (acquisition start position or acquisition end position), the maximum number of data items, the search expression, and the return expression as parameters of the ShunSearch function, and then execute the search. Specify the aggregation function in the return expression. Note The total length of the keys specified in the sort expression determines the number of groups that can be returned. A maximum of 1,000 items can be returned. No more data can be returned even if a higher value is specified for the data acquisition position or the maximum number of data items. The maximum number of data items that can be returned is returned to the output parameter of the ShunSearch function. Appendix E, Allowable Values provides a guide to the key lengths and the number of groups that can be returned. Consecutive data can be extracted by specifying a data acquisition position. This makes it possible to extract more than 1,000 items of data. Refer to Obtaining Consecutive Groups of XML Documents that Match Conditions for details. (3) Extract Aggregated Results The ShunSearch function returns the address of the aggregated results. Aggregated results consist of structure arrays, so data is extracted from these arrays. (4) Release Data Manipulation Handle After the data search has been performed and the results have been extracted, use the ShunFreeHandle function to release the data manipulation handle. Updating Data C APIs can be used to perform the following data updates Adding XML documents Deleting XML documents by specifying record IDs Updating XML documents by specifying record IDs A sample program to update data is provided in 'Updating Data' in Appendix D, Sample C Programs. 6-18

141 How to Use C APIs The following sections explain how to create an application to perform data updates. Adding Data Use the ShunInsert function to add data. The following diagram shows process for adding data. Figure 6-10 Process for Adding Data Entry Example SHUNHSTMT StmtH; /* Allocate data manipulation handle*/ ShunAllocHandle(ConH, &StmtH); (1) /* Add XML documents */ SHUNDATA Data[1]; Data[0].Data = "<document>" " <base>" " </base>" " <information>" " </information>" "</document>"; Data[0].Data_Len = strlen( Data[0].Data ); ShunInsert(StmtH, 1, Data); (2) /* Release data manipulation handle */ ShunFreeHandle(StmtH); (3) (1) Allocate Data Manipulation Handle Allocate the data manipulation handle in advance by specifying the connection handle to be used as the parent handle in the ShunAllocHandle function. (2) Add XML Documents To add XML documents, specify the data manipulation handle, the number of data items to be added, and the XML documents to be added in the ShunInsert function. 6-19

142 Chapter 6 Developing C Applications Note The ShunInsert function can be used to add multiple XML documents at a time. Either of the following specification methods can be used. - Specify multiple XML documents consecutively in a single additional data area. - Specify more than one additional data area. (3) Release Data Manipulation Handle After data addition is complete, use the ShunFreeHandle function to release the data manipulation handle. Deleting Data by Specifying Record IDs Use the ShunDeleteRecId function to delete data. The ShunDeleteRecId function uses record IDs (conductor control information and reply record identifiers) to delete data. Before executing the ShunDeleteRecId function, use the ShunSearch function to obtain the record IDs of the data to be deleted. The following diagram shows the process for deleting data by specifying record IDs. Figure 6-11 Process for Deleting Data by Specifying Record IDs 6-20

143 How to Use C APIs Entry Example SHUNHSTMT StmtH; /* Create data manipulation handle */ ShunAllocHandle(ConH, &StmtH); (1) /* Use record ID to perform deletion */ ShunDeleteRecId(StmtH, 1, Rec_Id_In); (2) /* Release data manipulation handle */ ShunFreeHandle(StmtH); (3) (1) Allocate Data Manipulation Handle Allocate the data manipulation handle in advance by specifying the connection handle to be used as the parent handle in the ShunAllocHandle function. (2) Delete XML Documents Perform the deletion process by specifying the data manipulation handle, the number of data items to be deleted, and the record IDs to be deleted in the ShunDeleteRecId function. Note By specifying multiple record IDs with the ShunDeleteRecId function, multiple XML documents can be deleted at a time. (3) Release Data Manipulation Handle After data deletion is complete, use the ShunFreeHandle function to release the data manipulation handle. Updating Data by Specifying Record IDs Use the ShunUpdateRecId function to update XML documents. The ShunUpdateRecId function uses record IDs (conductor control information and reply record identifiers) to update data. Before executing the ShunUpdateRecId function, use the ShunSearch function to obtain the record IDs of the data to be updated. The process of using a record ID to update an XML document refers to replacing an existing XML document with a new XML document. It is not possible to update part of the data contained in an existing XML document. The following diagram shows the process for updating data by specifying record IDs. 6-21

144 Chapter 6 Developing C Applications Figure 6-12 Process for Updating Data by Specifying Record IDs Entry Example SHUNHSTMT StmtH; /* Allocate data manipulation handle */ ShunAllocHandle(ConH, &StmtH); (1) /* Use record ID to perform update */ ShunUpdateRecId(StmtH, 1, Rec_Id_In, Data); (2) /* Release data manipulation handle */ ShunFreeHandle(StmtH); (3) (1) Allocate Data Manipulation Handle Allocate the data manipulation handle in advance by specifying the connection handle to be used as the parent handle in the ShunAllocHandle function. 6-22

145 How to Use C APIs (2) Update XML Documents Perform the update process by specifying the data manipulation handle, the number of data items to be updated, the record IDs to be updated, and the data to be updated in the ShunUpdateRecId function. Note By specifying multiple record IDs and their corresponding data with the ShunUpdateRecId function, multiple XML documents can be updated at a time. (3) Release Data Manipulation Handle After data updating is complete, use the ShunFreeHandle function to release the data manipulation handle. Closing Connections Entry Example After the data searches or data updates have finished, close the connection to Shunsaku. To close the connection, execute the ShunDisconnect function and then release the connection handle. /* Close connection */ ShunDisconnect(ConH); /* Release connection handle */ ShunFreeHandle(ConH); Error Handling Entry Example If a warning or error occurs while a C API is being used, a value other than that indicating normal completion will be returned when a function is executed. In such cases, the ShunGetErrorMessage function can be used to obtain the following information Error level Error message If(ret!= SHUN_SUCCESS) { /* Obtain error information */ ShunGetErrorMessage(StmtH, &Err_Level, &Err_Msg); (1) switch ( Err_Level ) { case SHUN_ERROR_CONNECTION printf("error level = SHUN_ERROR_CONNECTION\n"); break; case SHUN_ERROR_DATA printf("error level = SHUN_ERROR_DATA\n"); break; printf("error message = %s\n", Err_Msg); 6-23

146 Chapter 6 Developing C Applications Obtain Error Information Error Level Use the values returned when each function is executed to determine if an error has occurred. If an error has occurred, obtain the error information. By examining the error level, the user can ascertain the status of an application after an error has occurred. The following three error levels are returned Constant SHUN_INFORMATION SHUN_ERROR_DATA SHUN_ERROR_CONNECTION Meaning Indicates normal completion. Indicates that a warning level error (such as a parameter error) has occurred. Retry from the point where the error occurred. An error has occurred, causing the connection to Shunsaku to be forcibly closed. Restart from establishing the connection. Refer to Error Messages that may be Output during API Use for more information on error messages. 6-24

147 Debugging Applications Debugging Applications This section explains how to debug applications. The following debugging methods can be used when developing applications Debugging with the Debugger This method uses the debugger to examine or modify program variables while checking the behavior of an application. Debugging with Application Debugging Information This method checks debugging information that is output to the standard output or standard error output while an application is running. Debugging with the API Snapshot Function This method uses an API snapshot to check a variety of logged information. Each method is explained below. Debugging with the Debugger This debugging method uses a debugger. The debugger makes it possible to detect logical errors in a newly developed application while the application is running. Debugging is normally carried out by setting breakpoints within a program s source code and then examining or modifying program variables while the program is paused at each breakpoint. Debugging with Application Debugging Information This method involves coding the process for sending debugging information to standard output or standard error output into the application being developed, and then debugging the application based on the debugging information obtained. Debugging with the API Snapshot Function The API snapshot function logs a variety of I/O information relating to C APIs. The following information can be read from this log and used for debugging purposes when developing applications that use C APIs Function invocation sequences Return information, parameter information and any error information relating to functions Function execution times 6-25

148 Chapter 6 Developing C Applications Information Output by the API Snapshot Function The following table shows the information that is output by the API snapshot function. Table 6-5 Information Output by the API Snapshot Function Type Various C API I/O information Content Outputs the following information relating to a C API function that has been invoked by an application - Information relating to when the function was invoked - Information relating to when the function was returned - Information relating to when an error occurred in the function Detailed information about the output content and format, and output examples, etc., can be found in Section C API Function Information below. Environment Settings of the API Snapshot Function To output an API snapshot, set the following execution parameters in the API environment file SnapLevel LogFile LogFileSize LogFileBackup Refer to Setting up Environment Files in Chapter 2, Environment Setup or Appendix A, Execution Parameters in API Environment Files for more information on the API environment file. C API Function Information Output Format Level 1 Information about a function invoked from an application is output when the method is invoked by an application, when the method returns, and when a function execution error occurs. The API snapshot is output in CSV format. The output format for each output level is shown below. When a function is invoked Application name, connection handle ID, thread ID, date, time, Call, function name When a function returns Application name, connection handle ID, thread ID, date, time, Return, function name, function execution time, return value 6-26

149 Debugging Applications When an error is returned Application name, connection handle ID, thread ID, date, time, Error, function name, function execution time, return value, error details string Level 2 When a function is invoked Application name, connection handle ID, thread ID, date, time, Call, function name,,, input parameter information When a function returns Application name, connection handle ID, thread ID, date, time, Return, function name, function execution time, return value, output parameter information When an error is returned Application name, connection handle ID, thread ID, date, time, Error, function name, function execution time, return value, error details string Output Content The following table lists the items that are output and their content. Table 6-6 Content of the C API Function Information Output Output item Content Output level Level 1 Level 2 Application name Connection handle ID Displays the name of the invoking application. Outputs the connection handle identifier. This value is returned by the ShunAllocHandle function when connection handles are allocated. Thread ID Outputs the thread ID. Date Time Outputs the function invocation start/end date in the format yyyy/mm/dd. Outputs the function invocation start/end time in the format hhmmss.ms. 6-27

150 Chapter 6 Developing C Applications Output item Content Output level Level 1 Level 2 Call Return Error Call Indicates that the information relates to when a function was invoked. - Return Indicates that the information relates to when a function was returned. - Error Indicates that an error occurred when a function was executed. Function name Outputs the name of the C API function that was invoked. Function execution time Outputs the period (in seconds) between the time that a function was invoked and the time it returned. Return value Outputs the return value. - SHUN_SUCCESS Indicates that the function terminated normally. - SHUN_ERROR Indicates that a problem was detected while the function was running. Error details string Outputs a details string if an error occurs when a function is invoked. This item will not be output if no details string is included. Input parameter information Outputs input parameter information (parameter type and value) in the following format when a function is invoked x - (Parameter type) Value This item will not be output if there are no input parameters. Output parameter information Outputs output parameter information (parameter type and value) in the following format when a function returns x - (Parameter type) Value This item will not be output if there are no output parameters. Item is output x Item is not output 6-28

151 Debugging Applications Output Examples Level 1 The information that is output to a snapshot is output in the character encoding of the platform where the C API is operating. Output examples for the different output levels are provided below. Normal Termination "sample_hit_count", ,2820,"2004/10/22"," ","call","shunal lochandle" "sample_hit_count", ,2820,"2004/10/22"," ","return","shun AllocHandle",0.000,"SHUN_SUCCESS" Abnormal Termination "sample_hit_count", ,3540,"2004/10/22"," ","call","shunco nnect" "sample_hit_count", ,3540,"2004/10/22"," ","error","shunc onnect",1.016, "SHUN_ERROR","shn30654uEither the director or the conductor has not been started, or the port number is incorrect. <ShunConnect>" Level 2 Normal Termination "sample_hit_count", ,3116,"2004/10/22"," ","call","shunal lochandle",,," (SHUNHANDLE)0[ ] " "sample_hit_count", ,3116,"2004/10/22"," ","return","shun AllocHandle",0.000,"SHUN_SUCCESS"," (SHUNHANDLE) [009031B8] " Abnormal Termination "sample_hit_count", ,3540,"2004/10/22"," ","call","shunco nnect",,, "(SHUNHCON) [00344C70] (char*) localhost (int)10007 (char*)file1" "sample_hit_count", ,3540,"2004/10/22"," ","error","shunc onnect",1.016, "SHUN_ERROR","shn30654uEither the director or the conductor has not been started, or the port number is incorrect. <ShunConnect>" Note Enclose character string items in double quotes ("). Do not enclose numerical values in double quotes ("). The operation of each connection can be traced chronologically by filtering the collected log file with the connection handled. 6-29

152 Chapter 6 Developing C Applications Character Encoding Used by the C APIs For the C API search expressions, return expressions and sort expressions, use the same character encoding that is used to store the XML documents in Shunsaku. 6-30

153 Error Messages that may be Output during API Use Error Messages that may be Output during API Use This section explains the error messages that may be output when a C API is being used. The ShunGetErrorMessage function can be used to obtain the messages shown in this section. Message Output Format Messages that occur during C API use are output in the following format Format message code message text Meaning message code A unique message identifier that is assigned to each message message text A message that reports the system status or a system error The C API Function name that was executed will be appended at the end of a message. Output Example shn30653uthe requested host could not be found. <ShunConnect> Response to Messages Example Refer to the Messages or use the shunprtmsg command to determine what action to take in response to a message. The following example shows how to display the user action required in response to message code shn30653u. shn30653u The requested host could not be found. <s*> [Description] The requested host could not be found. [Parameters] s* C API function name [System action] Stops processing this function. [User response] Specify the correct host name or IP address with the ShunConnect function, and then rerun the command. Refer to the manual for information on how to specify host names and IP addresses. Refer to the Command Reference for more information on the shunprtmsg command. 6-31

154 Chapter 6 Developing C Applications 6-32

155 Appendix A Execution Parameters in API Environment Files This appendix explains the execution parameters that are specified in the API environment file. Format of Execution Parameters Execution Parameters and their Meanings Detailed Meaning of Execution Parameters Sample Execution Parameter Specifications A-1

156 Appendix A Execution Parameters in API Environment Files Format of Execution Parameters The format used to define execution parameters in the API environment file is as follows Parameter value Note The definition of a single execution parameter cannot extend over multiple lines. The definition of a single execution parameter must be no longer than 4,095 bytes (not including line feeds). The execution parameter and its specified value must be separated by a space character or a tab character. Lines that begin with # are treated as comments. If a # character appears in the middle of a line, all the text between it and the end of the line is treated as a comment. When an execution parameter that should be specified only once appears more than once, a syntax error is generated. Example In the following example, the text Updated 10 February 2005 is treated as a comment because it is preceded by the hash character #. Port 1 #Updated 2005/02/10 A-2

157 Execution Parameters and their Meanings Execution Parameters and their Meanings The following table lists the execution parameters used in the API environment file. Table A-1 List of Execution Parameters in API Environment File Execution parameter Meaning Can be omitted? Example Remarks Host Port The host name or the IP address of the connection destination The port number of the connection destination Yes DirSvr1 Default localhost Yes Default WaitTimer Maximum time to wait for a response from Shunsaku (seconds) Yes 300 Default 0 Allowable range 0 to 3600 SnapLevel Output level of API snap Yes 1 Default 0 LogFile Log file where API snap is output Yes "C\api\api.log" This parameter must be specified when the SnapLevel specification is 1 or 2. /api/api.log LogFileSize Changeover size of log file where API snap is output (MB) Yes 100 Default 100 Allowable range 1 to 500 LogFileBackup Number of backup copies to make of log file where API snap is output Yes 3 Default 1 Allowable range 0 to A-3

158 Appendix A Execution Parameters in API Environment Files Detailed Meaning of Execution Parameters Host Port Specifies the host name or the IP address of the connection destination. If this parameter is omitted, the specification defaults to localhost. Specifies the port number of the connection destination. If this parameter is omitted, the specification defaults to WaitTimer Specifies the maximum time (in seconds) to wait for a response from Shunsaku. Values between 0 and 3600 can be specified. If there is no response from Shunsaku after the specified waiting period has elapsed, a timeout will occur, an error will be notified to the application, and the connection will be closed automatically. If 0 is specified, no limit will be placed on the maximum response time and the system will continue to wait until a response is received. If this parameter is omitted, the specification defaults to 0. SnapLevel Specifies the API snap output level. Table A-2 List of API Snaps SnapLevel Output content 0 Does not output API snaps. 1 Outputs the API invocation sequence. 2 Outputs parameter information and data manipulation information when a method or function is executed, and level 1 information. If this parameter is omitted, the specification defaults to 0. Note When level 0 is specified, there is no need to specify the execution parameters LogFile, LogFileSize and LogFileBackup. LogFile Specifies the absolute path of the log file where the API snap is to be output. The log file will be recycled when it reaches the size specified by LogFileSize. This parameter must be specified when 1 or 2 is specified for SnapLevel. If this parameter is omitted, the API snap will not be output. The API snap is created for each application process. A process ID is added to the file name as shown in the following example. A-4

159 Detailed Meaning of Execution Parameters Example Absolute path specified in LogFile C\api\api.log Log file that is actually created C\api\api_2435.log Example Absolute path specified in LogFile /api/api.log Log file that is actually created /api/api_2435.log Note Specify a folder on the local disk for this parameter. If the folder name contains blank spaces or the hash character "#", enclose the entire folder name in double quotes. Directory names cannot include spaces or the hash character "#". LogFileSize Specifies the file size (in MB) that will trigger replacement of the log file where the API snap will be output. Values between 1 and 500 can be specified. If this parameter is omitted, the specification defaults to 100. For example, if 1 is specified, a backup file will be created automatically when the size of the file exceeds 1 MB. LogFileBackup Specifies the number of backup files to be created for the API snap output log file. Values between 0 and can be specified. When the value specified by this execution parameter is exceeded, the contents of the oldest backup file will be overwritten. For example, when 3 is specified for this parameter, three backup files named api_2435.log.1, api_2435.log.2 and api_2435.log.3 will be created. When a further backup becomes necessary, the contents of api_2435.log.3 will be lost. When this parameter is omitted, the specification defaults to 1. A-5

160 Appendix A Execution Parameters in API Environment Files Sample Execution Parameter Specifications #---Host name or IP address of connection destination---# Host DirSvr1 #---Port number of connection destination---# Port #---Maximum time to wait for response from Shunsaku (sec)---# WaitTimer 300 #---Output level of API snap ---# SnapLevel 1 #---Log file where API snap is output---# LogFile "C \api\api.log" #---Changeover size of log file where API snap is output (MB)---# LogFileSize 100 #---Number of backup copies of log file where API snap is output---# LogFileBackup 3 #--- Host name or IP address of connection destination---# Host DirSvr1 #--- Port number of connection destination---# Port #--- Maximum time to wait for response from Shunsaku (sec)---# WaitTimer 300 #--- Output level of API snap ---# SnapLevel 1 #--- Log file where API snap is output---# LogFile /api/api.log #--- Changeover size of log file where API snap is output (MB)---# LogFileSize 100 #--- Number of backup copies of log file where API snap is output---# LogFileBackup 3 A-6

161 Appendix B Format of Search, Return and Sort Expressions This appendix explains the format of search expressions, return expressions and sort expressions specified as arguments to Shunsaku API functions. Syntax Notation Method Common Format Search Expressions Return Expressions Sort Expressions B-1

162 Appendix B Format of Search, Return and Sort Expressions Syntax Notation Method This section shows how each of the elements that make up definition statements is arranged. The following table shows the symbols used with the entry format, and their meanings. Table B-1 Syntax Notation Method Symbol Meaning Parts that branch off under the line indicate elements that can be omitted. Example Parts that branch off in parallel above and below indicate that one of the two blocks should be selected. Example Lines with arrows that reach back above the line indicate blocks that can be repeated. Example Enclosure in a dotted rectangle represents a collection of multiple syntax diagram elements. Example Indicates the completion of the syntax diagram. B-2

163 Common Format Common Format This section details formatting common to the three types of expression (search expressions, return expressions, and sort expressions). Path Expressions The XML document structure is represented as a tree. Path expressions are used to describe the position of nodes within the XML tree structure. The format of path expressions is shown below. Figure B-1 Path Expression Definition Note Path expressions must include at least one element name. Path Element Path elements are used to identify individual element nodes in an XML document. Path elements are described in the following table Path element Description Element name Indicates the name of an element node. * Indicates all of the element nodes below the upper node. B-3

164 Appendix B Format of Search, Return and Sort Expressions Path Operator Path operators express the relationship between path elements. Path operators are described in the following table Path operator Description / The target will be the node below the upper node. // The target will be all descendent nodes below the upper node. Note Symbols // and * cannot be entered consecutively in path expressions. Example An example path expression is shown below. Document <company> <name>fujitsu</name> <employee> <name>smith</name> <id>2000</id> </employee> </company> Figure B-2 Path Expression Nodes /company/employee/name This path expression indicates the 'name' element node below the 'employee' element node below the 'company' element node below the root node. This node is indicated by (1) in the figure above. B-4

165 Common Format //name This path expression indicates all 'name' element nodes below the root node. These nodes are indicated by (1) and (2) in the figure above. /company/*/id This path expression indicates an 'id' element node below any element node ( name or employee in the example of the figure above) below the 'company' element node below the root node. This node is indicated by (3) in the figure above. Text Expressions A text expression specifies the (string) value of the text node below element nodes of an XML document specified using path expressions. The definition format for text expressions is shown below. Figure B-3 Text Expression Definition Format Path Expressions The path expression is used to identify the positions of particular nodes within the XML tree structure. Refer to Path Expressions for more information on path expression syntax. The "//" path operator cannot be specified at the end of path expressions. The '*' path element cannot be specified in the text expression. text() This function specifies the value of the text node below the element nodes specified by the path expression. Always specify text() in text expressions. Example An example text expression is shown below. Document <company> <name>fujitsu</name> <employee> <name>smith</name> <id>2000</id> </employee> </company> B-5

166 Appendix B Format of Search, Return and Sort Expressions Figure B-4 Example Text Expression /company/employee/name/text() This text expression indicates the value of the text node below the 'name' element node, below the 'employee' element node, below the 'company' element node, below the root node. This value is smith indicated by (1) in the above figure. Single-line Function Specification If single-line functions are specified, the value specified by the text expression is converted by the function and the results are returned. The definition format for single-line function specification is shown below. Figure B-5 Single-Line Function Specification Definition format The rlen Function The rlen function returns the specified number of characters starting with the first character of the string expressed by the text expression. A number of characters between 1 and inclusive can be specified. This number includes control characters (including the linefeed code). The string expressed by the text expression will be returned unchanged if it is shorter than the number of characters specified. The '//' path operator cannot be specified in the text expression. The '*' path element cannot be specified in the text expression. B-6

167 Common Format Example rlen(/company/name/text(),16) The val Function The val function extracts only numeric values from the string expressed by the text expression. The first numeric value that matches the format below is extracted from the string specified by the text expression. The following figure shows the definition for the val function. Figure B-6 val Function Definition The following apply to the val function Commas in the integer part are ignored. If a decimal point is specified, all digits immediately following the decimal point up to the first non-numeric character are used as the fractional part. Strings specified by the text expression that do not contain numbers are handled as 0. An error will occur if the integer part except for leading zeros has more than 18 digits. The first 18 digits of the decimal part are significant. Any subsequent digits are truncated. The '//' path operator cannot be specified in the text expression. The '*' path element cannot be specified in the text expression. Example val(/company/employee/id/text()) B-7

168 Appendix B Format of Search, Return and Sort Expressions Search Expressions Search expressions are used to specify search conditions that apply to XML documents to be retrieved A search expression consists of one or more conditional expressions and filter expressions. Refer to Conditional Expressions and Filter Expressions for more information on conditional expressions and filter expressions respectively. To specify multiple conditional expressions or filter expressions, use logical operators. Refer to Logical Operators below for more information. The format for search expressions is shown below. Figure B-7 Search Expression Definition Format Note Search expressions must have at least one conditional expression or filter expression. B-8

169 Search Expressions Logical Operators Logical operators indicate the logical relationship between two adjacent conditional expressions and filter expressions when multiple expressions are specified. Logical operators are briefly explained in the following table. Table B-2 Logical Operators Logical operator Type of logical operation Description AND AND operation Links pairs of conditional expressions with the AND operator. Evaluates to TRUE only if the results of both conditional expressions are TRUE. Evaluates to FALSE if either or both conditional expressions are FALSE. OR OR operation Links pairs of conditional expressions with the OR operator. Evaluates to TRUE if either or both conditional expressions are TRUE. Evaluates to FALSE only if both conditional expressions are FALSE. The following apply to logical operators The AND operator is evaluated first in search expressions that contain both AND and OR operators. Use parentheses '()' to change the order in which the logical operators are evaluated. In the following example, ([conditional expression 2] OR [conditional expression 3]) is evaluated first. [conditional expression 1] AND ([condition expression 2] OR [conditional expression 3])... Represents a space B-9

170 Appendix B Format of Search, Return and Sort Expressions Conditional Expressions Conditional expressions are used to compare the value of an element node specified by a path expression with a keyword. The following figure shows the definition for conditional expressions. Figure B-8 Conditional Expression Definition Conditional expressions are made up of path expressions, relational operators and keywords. Patterns and strings are enclosed by either double-quotes (") or single-quotes ('). Double-quotes and single-quotes cannot be mixed. Path Expressions The path expression is used to identify the position of an element node in the XML document. Specify an element node in the XML document to be compared. Refer to Path Expressions for more information on the format for path expressions. Note Keywords The "//" path operator can be specified at the end of path expressions only when a pattern is specified for the keyword. Specifying the "//" path operator at the end of a path expression selects all of the element nodes under the element node specified by the path expression. The "*" path element can be specified at the end of path expressions only when a pattern is specified for the keyword. Keywords are either patterns, strings, or numeric values that are compared with the values of element nodes in XML documents as specified by path expressions. B-10

171 Search Expressions Escape Characters To specify the following characters in patterns or strings, precede them with the escape character "\". For example, if the search target string is to be 'abc\', then specify 'abc\\', The following table shows the characters that require the escape character "\". Table B-3 Characters that must be preceded by the Escape Character Character Specification method Character Specification method " \". \. $ \$? \? & \& [ \[ ' \' \ \\ ( \( ] \] ) \) ^ \^ * \* { \{ + \+ \, \, \ - \- ~ \~ Entity References Entity references represent particular characters. If entity references are specified in XML documents, characters that they represent will be searched. For keywords, it is possible to specify either the character itself or the entity reference shown in the following table. Table B-4 List of Entity References Entity references Symbol represented < < > > & & &apos; ' " " Note When specifying entity references for keywords, the entity reference must be preceded by the escape character (eg. \>). To specify symbol represented for keywords, the ampersand (&), single-quotes (') and doublequotes (") must be preceded by the escape character. B-11

172 Appendix B Format of Search, Return and Sort Expressions Keywords and Relational Operators Patterns Various search conditions can be specified by combining keywords and relational operators. The following table shows the meaning of each combination. Table B-5 Patterns Combinations Relational operator Search type Description = Partial match TRUE if the value of the element node contains a string that matches the pattern specified by the keyword.!= Partial match TRUE if the value of the element node does not contain a string that matches the pattern specified by the keyword. Character String Table B-6 Character String Combinations Relational operator Search type Description == Complete match!== Complete match <,<=,>,>= Size comparison TRUE if the value of the element node and the string specified by the keyword match completely. TRUE if the value of the element node and the string specified by the keyword are even partially different. Compares the size of the value of the element node and the string specified by the keyword using the character encoding. Numeric Value Table B-7 Numeric Value Combinations Relational operators Search type Description = Match TRUE if the numeric value contained in the element node matches the numeric value specified by the keyword.!= Match TRUE if the numeric value contained in the element node does not match the numeric value specified by the keyword. <,<=,>,>= Size comparison Compares the size of the numeric value of the element node and the numeric value specified by the keyword. B-12

173 Search Expressions Patterns This method searches for documents where the value of the element node matches the various conditions represented by patterns. Searches can be made by specifying complex conditions, such as partial match searches and single-word searches. Patterns The following figure shows the definition for patterns. Figure B-9 Pattern Definition Patterns include the following operators Logical Conjunction Logical Disjunction Negation Character String Searches The following figure shows the definition for character string searches. Characters that are ignored during searches can be changed using the SkipChar execution parameter. Refer to Execution Parameters in the System Environment File and Execution Parameters in the Director Environment File in the Operator's Guide (Advanced) for more information on the SkipChar execution parameter. B-13

174 Appendix B Format of Search, Return and Sort Expressions Figure B-10 String Search Definition The following string search capabilities are provided String Match Specification Prefix Match Specification Suffix Match Specification Free Character Specification Character Interval Specification Partial Character Specification Character Range Specification Numeric Range Specification B-14

175 Search Expressions Word Searches The following figure shows the definition for word searches. The delimiter between individual words can be changed using the SeparateChar execution parameter. The characters that can be used in word searches are all ASCII characters except for control characters and the characters used to separate words. Refer to Execution Parameters in the System Environment File and Execution Parameters in the Director Environment File in the Operator's Guide (Advanced) for more information on the SkipChar execution parameter. Figure B-11 Word Search Definition The following word search types are provided Word Match Specification Word Interval Specification Logical Conjunction Finds out whether the value of the element node specified by the path expression includes all of the specified patterns. Example /root/text = 'fast&search' Evaluates to TRUE if the value of the element node represented by '/root/text' includes both the string "fast" and the string "search". Logical Disjunction Finds out whether the value of the element node specified by the path expression includes any of the specified patterns. B-15

176 Appendix B Format of Search, Return and Sort Expressions Example /root/text = 'fast search' Evaluates to TRUE if the value of the element node represented by /root/text includes either the string "fast" or the string "search". Negation Finds out whether the value of the element node includes none of the specified patterns. Example /root/text = '~(fast search)' Evaluates to TRUE if the value of the element node represented by /root/text includes neither the string "fast" nor the string "search". Note For pattern searches, logical conjunction, logical disjunction and negation can be used in combination. In this case, the order of evaluation is as follows 1) Negation 2) Logical conjunction 3) Logical disjunction Parentheses can also be used to specify the order of evaluation. Conditions in parentheses are evaluated preferentially. String Match Specification Finds out whether the value of the element node includes the specified keyword. Example /root/text = 'Fujitsu' Evaluates to TRUE if the value of the element node represented by /root/text includes the string "Fujitsu". Prefix Match Specification Finds out whether the specified keyword exists at the start of the value of the element node. Example /root/text = '^Fujitsu' Evaluates to TRUE if the value of the element node represented by '/root/text' starts with the string "Fujitsu". B-16

177 Search Expressions Suffix Match Specification Finds out whether the specified keyword exists at the end of the value of the element node. Example /root/text = 'Fujitsu$' Evaluates to TRUE if the value of the element node represented by '/root/text' ends with the string "Fujitsu". Free Character Specification Finds out whether the value of the element node includes a keyword that contains free characters. Free characters included in keywords can be specified in four ways, as shown in the following table. Table B-8 Free Characters Symbol Meaning Can be used consecutively. Any one arbitrary character.? Zero or one arbitrary character.+ One or more arbitrary characters.* Zero or more arbitrary characters x x Yes x No Example /root/text = 'Fujitsu.*company' Evaluates to TRUE if the value of the element node represented by /root/text includes the strings "Fujitsu" and "company" AND there are zero or more characters between these two strings. Note A syntax error will occur if a symbol that cannot be used consecutively is used consecutively. Free character specifications can be combined. The following table shows examples of how combinations of free character specifications evaluate to TRUE or FALSE for different data. These results assume that "=" has been specified as the relational operator. B-17

178 Appendix B Format of Search, Return and Sort Expressions Table B-9 Free Character Combinations Keyword example Data example AB AXB AYYB AZZZB 'A.' 'A.B' x x x 'A.?B' x x 'A.+B' x 'A.*B' 'A..?B' x x 'A..+B' x x 'A..*B' x 'A.?.+B' x 'A.?.*B' TRUE x FALSE Character Interval Specification Finds out whether the two keywords specified appear in succession in the value of the element node within an interval of the specified number of characters. Example The numeric value for character interval specifications must be between 0 and 1024 inclusive. /root/text = 'alcohol,10c,concentration' Evaluates to TRUE if the value of the element node represented by /root/text includes both "alcohol" and "concentration" in that order AND there are 10 or less characters between these two strings. Note Character interval specifications can only be specified once in string searches. Free character specifications cannot be entered immediately before or immediately after character interval specifications. Partial Character Specification Finds out whether the value of the element node contains the specified keyword. Part of the keyword consists of one of multiple strings. Example /root/text = 'Jo(n hn nathon)smith' Evaluates to TRUE if the value of the element node represented by /root/text includes any of the strings "Jon Smith", "John Smith" or "Jonathan Smith". B-18

179 Search Expressions Note When partial character specification, character range specification, or numeric range specification searches are executed, searchers may consume a lot of memory. If insufficient memory has been allocated to searchers, the search response performance of the entire Shunsaku system may decrease, and in some cases the application may detect a timeout error. The following formula can be used to calculate the maximum amount of memory used when partial character specification, character range specification, or numeric range specification searches are executed. Number of partial characters, character range, or numeric range x number of characters in the keyword x 1 KB If more than one partial character specification, character range specification, or numeric range specification is made, multiply the number of partial characters or the character ranges/numeric ranges together for the range factor. The following formula can be used to calculate the maximum amount of memory used when searches are executed by combining partial character specifications, character range specifications and numeric range specifications. Number of partial characters x character range x numeric range x number of characters in the keyword x 1 KB Character Range Specification Finds out whether the value of the element node includes the specified keyword, where part of the keyword consists of any character in a specified range. Example Both the start character (character 1) and the end character (character 2) must be single ASCII characters and must not be control characters. Do not add escape characters when making this specification. Also, the character encoding value of the start character must be smaller than the character encoding value of the end character. /root/text = 'class[a-c]' Evaluates to TRUE if the value of the element node represented by '/root/text' includes any of the strings "classa", "classb" or "classc". Note When character range specification searches are executed, searchers may consume a lot of memory. Refer to Partial Character Specification under Patterns, for more information on the amount of memory used. Numeric Range Specification Finds out whether the value of the element node includes the specified keyword, where part of the keyword consists of any numeric value in a specified range. The start numeric value (numeric value 1) and the end numeric value (numeric value 2) must be specified using single-byte numbers. The start and end numeric values must be between 0 and 999 inclusive. Also, the start numeric value must be smaller than the end numeric value. B-19

180 Appendix B Format of Search, Return and Sort Expressions Example /root/text = 'alcohol [9,11]%' Evaluates to TRUE if the value of the element node represented by '/root/text' includes any of the strings "alcohol 9%", "alcohol 10%", or "alcohol 11%". Note Correct search results can be obtained if characters are specified before and after the numeric value. When numeric range specification searches are executed, searchers may consume a lot of memory. Refer to Partial Character Specification, under Patterns, for more information on the amount of memory used. Word Match Specification Finds out whether the value of the element node contains any individual words that match the specified keyword. For word searches, strings separated by the delimiter are distinguished as individual words. Example /root/text = '\<the\>' Evaluates to TRUE if the value of the element node represented by '/root/text' includes the individual word "the". The string "the" in "mother", for example, will evaluate to FALSE because it occurs within a larger word. Word Interval Specification Finds out whether the two keywords specified appear in succession in the value of the element node within an interval of the specified number of words. Example Numeric values specified for word interval specifications must be between 0 and /root/text = '\<search\>,10w,\<shunsaku\>' Evaluates to TRUE if the value of the element node represented by '/root/text' includes both "search" and "shunsaku" in that order AND there are 10 or less words between these two words. Note Word interval specifications can be used only once in word searches. B-20

181 Search Expressions Character String This method searches for documents where the value of the element node completely matches the value specified by the string, or for documents where the specified size relationship holds. Size comparisons involving strings can be made and so this method can be used with searches for values that contain a mixture of numbers and characters, such as date searches. The following figure shows the definition for strings. Figure B-12 String Definition Complete Match Finds out if the value of the element node is equal to the string. Example /root/date == '2004/03/09' Note This expression will be TRUE if the value of the element node indicated by '/root/date' is equal to the string '2004/03/09'. Even if any element node in an XML document is a 0-byte-long empty string, it can be searched using complete match specification. Example /doc/detail/taxi == '' TRUE if the value of the element node represented by /doc/detail/taxi is an empty string. Size Comparison Compares the size of the value of the element node to the specified string, going from left to right using the character encoding value (the hexadecimal code value of a character). Dates and times must use the following formats Dates 'YYYY/MM/DD' Times 'hhmmss' Example /root/date > '2004/03/09' This expression compares the character encoding value of the element node indicated by '/root/date' to the character encoding value of the string '2004/03/09' one character at a time, starting from the leftmost character, and evaluates to TRUE if the character encoding value of the element node indicated by '/root/date' is larger. B-21

182 Appendix B Format of Search, Return and Sort Expressions Note For string comparisons, make sure that the string specified as the keyword is the same length as the value of the element node (within the XML document) to which it is being compared. Example In the following case, the document being searched does not match the conditional expression. Conditional Expression /root/date <= '2004/03/09' Document being searched <date>2004/3/1</date> Numeric Values This method searches for documents by extracting the numeric component from the value of the element node and finding documents where this value matches the specified numeric value or documents where the specified size relationship holds. The numeric component is automatically extracted from the value of the element node, and so this method can be used to search for numeric values that have been written in various ways. The following figure shows the definition for numeric values. Figure B-13 Number Definition Numbers For numbers, specify a digit between 0 and 9 inclusive. Numeric Comparisons Numeric comparisons extract the numeric component from the value of the element node specified by the path expression and compare this value to the numeric value specified in the keyword. The first string found in the value of the element node specified by the path expression that fits the format above is treated as a numeric value. Any commas that appear in the integer part are ignored. If a decimal point has been specified, the decimal part is regarded as being everything up until the first non-numeric character after the decimal point. B-22

183 Search Expressions Example /doc/money = 1000 Evaluates to TRUE if the numeric component extracted from the value of the element node represented by doc/money matches In the following example, the value of the element node specified by the path expression contains multiple numeric values. In such cases, only the first numeric value is extracted. Document A <money>abc123,456@789</money> is extracted. Document B <money> </money> is extracted. Document C <money>1,500 yen</money> 1500 is extracted. If the search data does not contain a valid numeric value string, the conditions will evaluate to FALSE. The following target search string does not contain a valid numeric value string. <money></money> Note Path operator // cannot be entered at the end of a path expression when performing numeric comparisons. Path element * cannot be entered at the end of a path expression when performing numeric comparisons. The number of digits in the numeric value specified as the keyword does not need to match that of the value of the element node specified with the path expression. Keyword /root/money > 1000 B-23

184 Appendix B Format of Search, Return and Sort Expressions In the following example, the element node specified with the path expression will be regarded as matching the search conditions. <money>1000.5</money> There is no need to make the number of digits in the integer part or decimal part of the values of element nodes consistent between multiple XML documents. Document A <money>1000.1</money> Document B <money> </money> Document C <money>10.5</money> Compatible Format If "1(use compatible format queries)" is specified for the ExtendedQuery execution parameter in the system environment file, the following differences will occur with conditional expressions. Escape Characters The characters in the following table must be preceded by the escape character '\' when they are specified in strings. For example, if 'abc\\' is specified, the search target string will be 'abc\'. The following characters must be preceded by '\'. Table B-10 Characters that must be preceded by the Escape Character Character Specification method. \. \ \\ " \" ' \' B-24

185 Search Expressions Patterns The following figure shows the format for patterns. Figure B-14 Pattern Format Ellipses Ellipses... are specified in order to search for strings that contain any number (including zero) of unknown characters. Filter Expressions Filter expressions are used to specify search conditions within the closed range of element nodes specified by the path expressions. The definition format for filter expressions is shown below. Figure B-15 Filter Expression Definition Note Filter expressions must have two or more conditional expressions. Filter expressions can be nested within other filter expressions with up to eight levels of nesting. Example An example search expression containing filter expressions is shown below. Search Expression /root/company/employee{/name = '^smith' AND /id = '1000' B-25

186 Appendix B Format of Search, Return and Sort Expressions Document A <root> <company> <employee> <name>smith</name> <id>1000</id> </employee> </company> <company> <employee> <name>jones</name> <id>2000</id> </employee> </company> </root> Document B <root> <company> <employee> <name>smith</name> <id>2000</id> </employee> </company> <company> <employee> <name>jones</name> <id>1000</id> </employee> </company> </root> In this example, Document A matches the search expression but Document B does not. Treat /root/company/employee as a single block. Document A contains data that matches the conditions in braces (/name = ^smith AND /id = 1000 ), while Document B does not. Note The '*' path element cannot be specified as the final element of the path expressions used in filter expressions. Always specify an element name. Example In the following example, an error will occur because '*' is specified as the final path element of the path expression. /root//company/*{/name = '^smith' AND /id = '1000' B-26

187 Return Expressions Return Expressions Return expressions are used to specify data extraction formats for either extracting only particular elements from the XML document that meets specified search conditions, or for aggregating that data. Return expressions use different formats, depending on whether aggregation is performed. Format Used when not Aggregating To return the entire record, specify '/' in the return expression. The entire record will also be returned if an empty string '' is specified in the return expression. Figure B-16 Format Used when not Aggregating To return only certain element nodes or element values, specify either a path expression or a text expression. Single-line functions can also be specified to convert element values. Path Expressions Example As shown in the following definition, multiple return items can be specified, separated by commas ','. The path expression specifies which element nodes to return. The values of element nodes specified by the path expression are returned in XML format. The '*' path element cannot be specified as the final path element. The "//" path operator cannot be specified at the end of path expressions. Refer to Path Expressions for more information on the format of path expressions. /root/company/name B-27

188 Appendix B Format of Search, Return and Sort Expressions Text Expressions Example The text expression is used to specify which text nodes to return. The (string) values of the text nodes specified by text expressions are returned in text format. Refer to Text Expressions for more information on the format of text expressions. /root/company/name/text() Single-line Function Specification Example The single-line function specification uses a function to convert the value indicated by the text expression passed as an argument. The results of single-line function specifications are returned in text format. Refer to Single-line Function Specification for more information on single-line function specifications. rlen(/root/company/name/text(),10) Example Return Expressions when not Aggregating Some example return expressions are shown below. Document <doc> <companyname>fujitsu</companyname> <employee> <name>smith</name> <id>2000</id> <age>30</age> </employee> </doc> Return Specification in XML Format If a path expression is specified in the return item, the corresponding element nodes will be returned in XML format. If multiple path expressions are specified in the return item, multiple elements are returned in the order specified. Results will be returned for each matching document, enclosed by the root tag. If there are no matching elements, no elements will be returned. Example 1 Return Expression / B-28

189 Return Expressions Result The Entire Record is Returned <doc> <companyname>fujitsu</companyname> <employee> <name>smith</name> <id>2000</id> <age>30</age> </employee> </doc> Example 2 Return Expression /doc/employee/name Result <doc><name>smith</name></doc> Example 3 Return Expression /doc/employee Result <doc><employee><name>smith</name><id>2000</id><age>30</age></employee> </doc> Example 4 Return Expression /doc/companyname,/doc/employee/id Result <doc><companyname>fujitsu</companyname><id>2000</id></doc> B-29

190 Appendix B Format of Search, Return and Sort Expressions Notes If the return expression includes a path expression, all return items must include a path expression. Return items cannot coexist with text expressions and single-line function specifications. If a return parameter that will match multiple elements is specified (that is, if more than one path expression is specified, or if "//" or "*" is specified), the application will not be able to determine the relationship between the elements that have been extracted, as shown below. In these situations, either extract the entire XML document, or extract data using a specification where the return parameter isolates a single element. Example 1 If some elements do not exist, the application will not be able to determine which elements do not exist. In this example, there is no /doc/president/name element, and so only /doc/employee/name will be returned, but the application will not be able to determine whether the element returned is /doc/president/name or /doc/employee/name. Return expression /doc/president/name,/doc/employee/name Result <doc><name>smith</name></doc> Example 2 The application will not be able to determine the path to the elements that have been extracted. In this example, the application cannot determine whether the path to the name element is /doc/president/name or /doc/employee/name. Document The explanations that follow assume that the following XML document has been found. <doc> <companyname>fujitsu</companyname> <president> <name>thompson</name> <id>1849</id> <age>61</age> </president> <employee> <name>smith</name> <id>2000</id> <age>30</age> </employee> </doc> Return expression //name B-30

191 Return Expressions Result <doc><name>thompson</name><name>smith</name></doc> Text Format Return Specification If a text expression or a single-line function specification is specified in the return item, the results of the text expression or single-line function specification will be returned as a string. If multiple path expressions are specified in the return item, multiple strings are returned in the order specified. If there are no matching elements, an empty element will be indicated by consecutive delimiters. Java APIs Extracting the Search Results Obtained by the getstring Method or the getstream Method The values returned by each return item are separated by commas ','. If the specified element occurs more than once in the same document, each occurrence will be separated by a vertical bar ' '. Extracting the Search Results Obtained by the getstringarray Method Results are returned as a two dimensional array for each return item. The number of elements in the high-order array is equal to the number of return expressions. The number of elements in the low-order array is equal to the number of data items in a single document that apply to the specified return expression. C APIs The values returned by each return item are separated by the character code '\001'. If the specified element occurs more than once in the same document, each element will be separated by the character code '\002'. The character code '\001' is always attached at the end of the results returned. In the following example, character codes '\001' and '\002' are expressed as '\1' and '\2' respectively. Example 1 Example Return Item Return Expression /doc/employee/name/text() Result For Java APIs smith For C APIs smith \1 B-31

192 Appendix B Format of Search, Return and Sort Expressions Example 2 Example where Multiple Return Items are Specified Return Expression /doc/employee/name/text(),val(/doc/employee/age/text()) Result For Java APIs smith,30 For the C APIs smith \1 30 \1 Note If a return parameter that will match multiple elements is specified (that is, if more than one path expression is specified, or if "//" or "*" is specified), the application will not be able to determine the relationship between the elements that have been extracted Example Because there is no age element node for jones in the document below, it is impossible to tell whether the 30 in the third result relates to smith or jones. Document <doc> <companyname>fujitsu</companyname> <employee> <name>smith</name> <id>2000</id> <age>30</age> </employee> <employee> <name>jones</name> <id>1000</id> </employee> </doc> Return expression /doc/companyname/text(),/doc/employee/name/text(),val(/doc/employee/ age/text()) Result For the Java APIs fujitsu,smith jones,30 B-32

193 Return Expressions For the C APIs fujitsu \1 smith \2 jones \1 30 \1 Format Used when Aggregating To aggregate data, specify text expressions, single-line function specifications, or aggregation function specifications in the return expression. Multiple specifications can be entered, each separated with commas. The return expression must include at least one aggregation function specification. A sort expression must be specified when aggregating. Refer to Sort Expressions for more information on sort expressions. Aggregation is performed as follows Data is first sorted according to the sort key specified by the text expressions or single-line functions specified in the sort expression Data with the same sort key is treated as a single group The result of the aggregation function specification is determined for each group. Figure B-17 Format Used when Aggregating Text Expressions Specify a text expression when extracting a key for aggregation. Refer to Text Expressions for more information on the format for text expressions. If a text expression is specified, it must be the same as the text expression used in the sort expression. The value used as the key for aggregation will be returned. Example /doc/company/employee/dept/text() B-33

194 Appendix B Format of Search, Return and Sort Expressions Single-line Function Specification Specify single-line functions and extract the value of them when using single-line function specifications as the key for aggregation. Refer to Single-line Function Specification for more information on the format for single-line function specifications. If a single-line function is specified, it must be the same as the single-line function specification used in the sort expression. The value used as the key for aggregation will be returned. Example rlen(/doc/company/employee/name/text(),3) Aggregation Function Specifications Aggregation function specifications aggregate the values specified by the text expression passed as an argument. The definition format for aggregation function specifications is shown below. Figure B-18 Aggregation Function Specification Definition Note If the element node specified by the text expression is not in the document, it will not be included in the aggregation target. If the value represented by the text expression specified as an argument to the aggregation function does not exist, it will not be included in the aggregation target. The avg, sum, max and min functions extract numeric values from the strings specified by the text expression and aggregate these values. The principles for extracting numeric values from text expressions are the same as for the val single-line function specification. An error will occur if an aggregation function produces result data whose integer part exceeds 18 digits. However, no error will occur even if intermediate result data for an aggregation exceeds 18 digits. The avg Function Extracts only numeric values from the strings expressed by the text expression and determines the average of these values. B-34

195 Return Expressions The sum Function Extracts only numeric values from the strings expressed by the text expression and determines the sum of these values. The max Function Extracts only numeric values from the strings expressed by the text expression and determines the maximum of these values. The min Function Extracts only numeric values from the strings expressed by the text expression and determines the minimum of these values. The count Function Determines the number of elements specified by the text expression. Notes The '//' path operator cannot be specified in the text expression. The '*' path element cannot be specified in the text expression. Example Return Expressions used when Aggregating Some example return expressions are shown below. Document A <doc> <companyname>fujitsu</companyname> <employee> <name>smith</name> <id>2000</id> <age>30</age> <comment></comment> </employee> </doc> Document B <doc> <companyname>fujitsu</companyname> <employee> <name>jones</name> <id>1000</id> <age>35</age> <comment>team leader</comment> </employee> </doc> B-35

196 Appendix B Format of Search, Return and Sort Expressions Example 1 Example of the avg Function Return Expression avg(/doc/employee/age/text()) Sort Expression /doc/companyname/text() Result 32.5 Example 2 Example of the count Function Return Expression count(/doc/employee/comment/text()) Sort Expression /doc/companyname/text() Result 1 If multiple return items are specified, the value of each return item contained in the result will be separated by the delimiter. For Java APIs Extracting the results of searches using the getstring or getstream method The values returned by each return item will be separated with commas ",". For C APIs Extracting the results of searches using the getstringarray method - For each return item, results will be returned as a two-dimensional String array. - The number of elements in the upper array will be the number of return expressions. There will be one element in the lower array. The values returned by each return item will be separated with the character code "\001". The character "\001" will always be appended to the end of the values returned. B-36

197 Return Expressions Example 3 Example of Specifying Multiple Return Items Return Expression avg(/doc/employee/age/text()),count(/doc/employee/name/text()) Sort Expression /doc/companyname/text() Result 32.5,2 Note If the element specified by the text expression occurs more than once in the same document, only the first element value is used. Example In the following example, the text expression '/student/subject/test/score/text()' is passed as an argument to the avg function. In this case, Document A will not be included in the aggregation target, the value of Document B will be treated as 80, and Document C will be 0. Document A <student> <name>smith</name> <subject> <subjectname>science</subjectname> </subject> <name>smith</name> </student> Document B <student> <name>jones</name> <subject> <subjectname>science</subjectname> <test> <date> 2004/01/12</date> <score>80</score> </test> <test> <date> 2003/12/08</date> <score>70</score> </test> </subject> </student> B-37

198 Appendix B Format of Search, Return and Sort Expressions Document C <student> <name>murphy</name> <subject> <subjectname>science</subjectname> <test> <date> 2004/01/12</date> <score>--</score> </test> </subject> </student> Return expression avg(/student/subject/test/score/text()) Sort expression /student/subject/subjectname/text() Result 40 B-38

199 Sort Expressions Sort Expressions Sort expressions are used to specify keys for either sorting or aggregating search results. Sort Expression Format Sort expressions can be specified using either text expressions or single-line function specifications. In each case, the sort order (ascending or descending) can be specified. Multiple specifications can be made, each separated by commas. The definition format for sort expressions is shown below. Figure B-19 Sort Expression Definition Note Sort expressions can include up to eight key specifications. Text Expressions For text expressions, specify a text node to use as the key for sorting the data. Refer to Text Expressions for more information on text expressions. Notes The '//' path operator cannot be specified in the text expression. The '*' path element cannot be specified in the text expression. Example /company/employee/dept/text() B-39

200 Appendix B Format of Search, Return and Sort Expressions Single-line Function Specification Single-line function specifications can be used to sort the results of single-line functions. Refer to Single-line Function Specification for more information on single-line function specifications. Example rlen(/company/name/text(),16) DESC Specify DESC to return results in descending order. If omitted, results will be returned in ascending order. Example /company/employee/dept/text() DESC Sorting The following rules apply to sorting If a text expression is specified, results will be sorted using the string held by the text node specified by the text expression. By default, only the leftmost 20 bytes of the string held by the text node specified with the text expression are valid. The number of valid characters can be changed using the 'rlen' function. The range of values that can be specified is 1 to 128. Any spaces, tabs, or linefeed characters in the string held by the text node specified with the text expression will be distinguished as valid values. If the text node specified with the text expression occurs more than once in the document, only the value of the first text node will be used. If the text node specified with the text expression is not in the document, the document will be placed last in the sorted results, regardless of the sort order. Specify the val function to sort numeric values. If the val function is specified, the data will be treated as numeric, and there is no need to line up digits. Example If the two document items below are sorted as strings, '20' will be larger than '100'. By specifying 'val(/value/text())' in the sort expression, these values will be treated as the numbers 100 and 20, and so 100 will be larger than 20. <value>100</value> <value>20</value> B-40

201 Sort Expressions Aggregation The following rules apply to aggregating If a text expression is specified, all documents where the text node specified by the text expression hold the same string are treated as a single group. By default, only the leftmost 20 bytes of the string held by the text node specified with the text expression are valid. The number of valid characters can be changed using the 'rlen' function. The range of values that can be specified is 1 to 128. Any spaces, tabs or linefeed characters in the string held by the text node specified with the text expression will be distinguished as valid values. If the text node specified with the text expression occurs more than once in the document, only the value of the first text node will be used. Documents where the text node specified with the text expression does not exist are treated as a single group where the group key has no value. Specify the val function to aggregate search results using a numeric key. If the val function is specified, the data will be treated as numeric, and so elements with the same numeric value will be treated as the same group even if some strings contain non-numeric values, or if the positioning of the decimal places below the decimal point is different. Example If the two documents below are aggregated using '/doc/key/text()' as the key, each will be placed in a separate group. If 'val(/doc/key/text())' is specified in the sort expression, both data items will be treated as the numeric value 1000, and so will be aggregated as the same group. <doc> <key>net g</key> <ship>2000</ship> </doc> <doc> <key>1,000g</key> <ship>1000</ship> </doc> B-41

202 Appendix B Format of Search, Return and Sort Expressions Example Sort Expressions Some example sort expressions that either sort or aggregate data are shown below. Document A <employee> <name>smith</name><age>33</age><dept>sales</dept> </employee> Document B <employee> <name>jones</name><age>30</age><dept>general affairs</dept> </employee> Document C <employee> <name>murphy</name><age>22</age><dept>sales</dept> </employee> Document D <employee> <name>fraser</name><age>54</age><dept>general affairs</dept> </employee> Document E <employee> <name>morrison</name><dept>general affairs</dept> </employee> Document F <employee> <name>mcdonald</name><age>42</age><dept>general affairs</dept> </employee> B-42

203 Sort Expressions Entry Example of Data Sorting Example 1 Return Expression /employee/name/text(),/employee/age/text() Sort Expression val(/employee/age/text()) Result For the Java APIs murphy,22 jones,30 smith,33 mcdonald,42 fraser,54 morrison, For the C APIs murphy \1 22 \1 jones \1 30 \1 smith \1 33 \1 mcdonald \1 42 \1 fraser \1 54 \1 morrison \1 \1 Example 2 Return Expression /employee/name,/employee/age Sort Expression val(/employee/age/text()) Result <employee><name>murphy</name><age>22</age></employee> <employee><name>jones</name><age>30</age></employee> <employee><name>smith</name><age>33</age></employee> <employee><name>mcdonald</name><age>42</age></employee> <employee><name>fraser</name><age>54</age></employee> <employee><name>morrison</name><age></age></employee> B-43

204 Appendix B Format of Search, Return and Sort Expressions Entry Example of Data Aggregation Example Return Expression avg(/employee/age/text()),count(/employee/age/text()),/employee/dept/ text() Sort Expression /employee/dept/text() Result For Java APIs 42,3,general affairs 27.5,2,sales For C APIs 42 \1 3 \1 general affairs \ \1 2 \1 sales \1 B-44

205 Appendix C Sample Java Programs This appendix provides sample programs that use Java APIs. Searching Data Updating Data C-1

206 Appendix C Sample Java Programs Searching Data Use the APIs provided by Shunsaku to obtain search results by specifying search conditions for the data to be retrieved. Java API can be used to perform the following operations Obtain the number of XML documents that match search conditions Obtain the XML documents that match search conditions in a specified format Obtain every instance of specific XML documents Sort and return XML documents that match search conditions Aggregate and return the values of XML documents that match search conditions Refer to the Java API Reference for more information on Java APIs. This section uses the example of a hotel reservation status search system to explain the search operation. For the purposes of this explanation, it is assumed that the following XML document exists. Refer also to Appendix G, Notes on XML Documents for more information on XML documents. Sample Document <document> <base> <name>hotel 1</name> <city>sydney</city> <address>bondi Beach</address> <detail>http//xxxxx.com.au</detail> <price>350</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, two minutes walk to train station XX</note> </document> <document> <base> <name>hotel 2</name> <city>sydney </city> <address>bondi Beach</address> <detail>http//xxxxx.com.au</detail> <price>150</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, five minutes walk to train station XX</note> </document> <document> <base> <name>hotel 3</name> <city>sydney</city> <address>bondi Beach</address> <detail>http//xxxxx.com.au</detail> C-2

207 Searching Data <price>250</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, ten minutes walk to train station XX</note> </document> <document> <base> <name>hotel 4</name> <city>sydney </city> <address>paddington</address> <detail>http//xxxxx.com.au</detail> <price>500</price> </base> <information> <date>2004/07/10</date> </information> <note>en-suite bathroom and toilet, three minutes walk to train station ZZ </note> </document> <document> <base> <name>hotel 5</name> <city>sydney </city> <address> Paddington</address> <detail>http//xxxxx.com.au</detail> <price>150</price> </base> <information> <date>2004/07/10</date> </information> <note>en-suite bathroom and toilet, two minutes walk to train station ZZ</note> </document> <document> <base> <name> Hotel 6</name> <city> Adelaide</city> <address> Clearview Adelaide</address> <detail>http//xxxxx.com.au</detail> <price>300</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, two minutes walk to train station XX</note> </document> <document> <base> <name>hotel 7</name> <city>adelaide </city> <address>clearview Adelaide</address> <detail>http//xxxxx.com.au</detail> <price>200</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, three minutes walk to train station XX</note> </document> <document> <base> <name>hotel 8</name> C-3

208 Appendix C Sample Java Programs <city>adelaide</city> <address>clearview Adelaide</address> <detail>http//xxxxx.com.au</detail> <price>150</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, five minutes walk to train station XX</note> </document> Obtaining the Number of XML Documents that Match Search Conditions If there is a large amount of data to be searched, a large number of items may match the search conditions. In this case, it is not practical to return all the data items for the user to view. In such cases, it is useful to find out first how many data items match the specified condition. The example below shows how to use the Java APIs to find out how many hotels match the date and location specified as the search condition. Search Conditions How many hotels in Sydney have a vacancy on 2004/07/18? Execute a search using the date (2004/07/18) and the location (Sydney) as search conditions. An Example of Using the APIs The following is a sample program using the Java APIs. import com.fujitsu.shun.shunconnection; import com.fujitsu.shun.shunpreparedstatement; import com.fujitsu.shun.shunresultset; import com.fujitsu.shun.common.shunexception; /*** Obtain the number of records that correspond to the specified search conditions ***/ public class JavaAPISample1 { public static void main(string[] args) { ShunConnection con = null; ShunPreparedStatement pstmt = null; ShunResultSet rs = null; try { // Search conditional expression String squery = "/document/base/city = = 'Sydney' AND /document/information/date = = 2004/07/18 "; // Return expression String sreturn = "/"; // Number of hits int ihitnum = 0; // Create ShunConnection object con = new ShunConnection("DirSvr1", 33101); C-4

209 Searching Data // Specify search expression and create ShunPreparedStatement object pstmt = con.preparesearch(squery, sreturn); // Specify number of items to return per request pstmt.setrequest(1, 0); // Execute search and create ShunResultSet object rs = pstmt.executesearch(); // Obtain number of hits ihitnum = rs.gethitcount(); System.out.println("Number of hits = " + ihitnum); rs.close(); pstmt.close(); con.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); catch (Exception ex) { System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); // Recovery procedure in the event of an error finally { try { if (rs!= null) rs.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (pstmt!= null) pstmt.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; C-5

210 Appendix C Sample Java Programs case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (con!= null) con.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); Execution Results Number of hits = 3 Obtaining XML Documents that Match Search Conditions in a Specified Format Part of the data obtained as search results is sometimes used as additional conditions to perform the next search operation. In this case, it is common to obtain only part of the data as search results instead of the entire data. The example below shows how to use the Java APIs to find out how many hotels match the date and location specified as the search condition, as well as to get partial information. Search Conditions I want to know the names and rates of up to 30 hotels that have a vacancy on 2004/07/18. Specify the date (2004/07/18) and the location (Sydney) as search conditions. Also specify the hotel name and rate for the search result, and execute the search. C-6

211 Searching Data An Example of Using the APIs The following is a sample program using the Java APIs. import com.fujitsu.shun.shunconnection; import com.fujitsu.shun.shunpreparedstatement; import com.fujitsu.shun.shunresultset; import com.fujitsu.shun.common.shunexception; /*** Obtain the number of records and the data that correspond to the specified search conditions ***/ public class JavaAPISample2 { public static void main(string[] args) { ShunConnection con = null; ShunPreparedStatement pstmt = null; ShunResultSet rs = null; try { // Search conditional expression String squery = "/document/base/city = = 'Sydney' AND /document/information/date = = 2004/07/18 "; // Return expression String sreturn = "/document/base/name, /document/base/price"; // Number of hits int ihitnum = 0; // Data counter int idatacounter = 1; // Create ShunConnection object con = new ShunConnection("DirSvr1", 33101); // Specify search expression and create ShunPreparedStatement object pstmt = con.preparesearch(squery, sreturn); //Specify number of items to return per request pstmt.setrequest(1, 30); // Execute search and create ShunResultSet object rs = pstmt.executesearch(); // Obtain number of hits ihitnum = rs.gethitcount(); System.out.println("Number of hits = " + ihitnum); // Obtain the data corresponding to the search conditions one item at a time while (rs.next()) { System.out.println( [Result]" + Item No. + idatacounter = " + rs.getstring()); idatacounter++; rs.close(); pstmt.close(); con.close(); C-7

212 Appendix C Sample Java Programs catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); catch (Exception ex) { System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); finally { try { if (rs!= null) rs.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (pstmt!= null) pstmt.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (con!= null) con.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; C-8

213 Searching Data case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); Execution Results Number of hits = 3 [Result] No. 1 = <document><name>hotel 1</name><price>350</price></document> [Result] No. 2 = <document><name>hotel 2</name><price>150</price></document> [Result] No. 3 = <document><name>hotel 3</name><price>250</price></document> Obtain Every Instance of Particular XML Documents The search process performs the operations stated in Obtaining the Number of XML Documents that Match Search Conditions and Obtaining XML Documents that Match Search Conditions in a Specified Format to obtain all the data based on the filtering conditions. The following example shows how the Java APIs are used. It shows how all the data of applicable hotels can be retrieved based on the hotel names obtained using the operations stated in Obtaining XML Documents that Match Search Conditions in a Specified Format. Search Conditions I want to obtain detailed information about a number of the hotels in Sydney that have a vacancy on 2004/07/18. Execute the search using the date (2004/07/18) and the location (Sydney) as search conditions. The record IDs that correspond to hotels are used to obtain detailed information. An Example of Using the APIs The following is a sample program using the Java APIs. import com.fujitsu.shun.shunconnection; import com.fujitsu.shun.shunpreparedrecordid; import com.fujitsu.shun.shunpreparedstatement; import com.fujitsu.shun.shunresultset; import com.fujitsu.shun.common.shunexception; /*** Obtain all the record information applicable to the specified record ID ***/ public class JavaAPISample3 { public static void main(string[] args) { ShunConnection con = null; ShunPreparedStatement pstmt = null; ShunPreparedRecordID rid = null; ShunResultSet rs = null; try { // Search conditional expression C-9

214 Appendix C Sample Java Programs String squery = "/document/base/city = = 'Sydney' AND /document/information/date = = 2004/07/18 "; // Return expression String sreturn = "/document/base/name/text()"; // Record information String srecordid = ""; // Number of hits int ihitnum = 0; // Create ShunConnection object con = new ShunConnection("DirSvr1", 33101); // Specify search expression and create ShunPreparedStatement object pstmt = con.preparesearch(squery, sreturn); //Specify number of items to return per request pstmt.setrequest(1, 30); // Execute search and create ShunResultSet object rs = pstmt.executesearch(); // Obtain number of hits ihitnum = rs.gethitcount(); System.out.println("Number of hits = " + ihitnum); // Create ShunPreparedRecordID object rid = con.preparesearchrecordid(); // Obtain one item of data that corresponds to search conditions while (rs.next()) { // Set record ID for Hotel 1 information if (rs.getstring().equals("hotel 1")) { rid.add(rs.getrecordid()); rs.close(); pstmt.close(); // View detailed information if acquisition of the corresponding record IDs is successful if (0 < rid.getcount()) { // Use specified record ID to create ShunResultSet object rs = rid.searchbyrecordid(); while (rs.next()) { // Obtain data by specifying record ID System.out.println("[Details] = " + rs.getstring()); rs.close(); rid.close(); con.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; C-10

215 Searching Data System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); catch (Exception ex) { System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); finally { try { if (rs!= null) rs.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (pstmt!= null) pstmt.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (rid!= null) rid.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (con!= null) con.close(); C-11

216 Appendix C Sample Java Programs catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); Execution Results Number of hits = 3 [Details] = <document> <base> <name>hotel 1</name> <city>sydney</city> <address>bondi Beach</address> <detail>http//xxxxx.com.au</detail> <price>350</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, two minutes walk to train station XX</note> </document> Obtaining XML Documents that Match Search Conditions after they have been Sorted When performing a search, the user sometimes prefers to obtain the search results after they have been sorted according to a specific element. Specify the date and location in the search conditional expression and obtain the number of hotels that match the conditions and partial information about those hotels. To show how the Java APIs are used, the following example sorts the extracted data in descending order according to the accommodation rate. Search Conditions I want to know the hotels in Sydney that have a vacancy on 2004/07/18, and I want to sort the hotels in descending order according to the accommodation rate. Specify the date (2004/07/18) and the location (Sydney) as search conditions. Also specify the accommodation rate in the sort condition and then execute the search. C-12

217 Searching Data An Example of Using the APIs The following is a sample program using the Java APIs. import com.fujitsu.shun.shunconnection; import com.fujitsu.shun.shunpreparedstatement; import com.fujitsu.shun.shunresultset; import com.fujitsu.shun.common.shunexception; /*** Obtain data that corresponds to specified search conditions after the data has been sorted ***/ public class JavaAPISample4 { public static void main(string[] args) { ShunConnection con = null; ShunPreparedStatement pstmt = null; ShunResultSet rs = null; try { // Search conditional expression String squery = "/document/base/city = = 'Sydney' AND /document/information/date = = 2004/07/18 "; // Return expression String sreturn = "/document/base/name, /document/base/price"; // Sort expression String ssort = "val(/document/base/price/text()) DESC"; // Number of hits int ihitnum = 0; // Data counter int idatacounter = 1; // Create ShunConnection object con = new ShunConnection("DirSvr1", 33101); // Specify search expression and create ShunPreparedStatement object pstmt = con.preparesearch(squery, sreturn); //Specify number of items to return per request pstmt.setrequest(1, 30); // Specify sort expression pstmt.setsort(ssort); // Execute search and create ShunResultSet object rs = pstmt.executesearch(); // Obtain the data corresponding to the search conditions one item at a time while (rs.next()) { System.out.println("[Result]" + Item No. + idatacounter = " + rs.getstring()); idatacounter++; rs.close(); pstmt.close(); con.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED C-13

218 Appendix C Sample Java Programs System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); catch (Exception ex) { System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); finally { try { if (rs!= null) rs.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (pstmt!= null) pstmt.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (con!= null) con.close(); C-14

219 Searching Data catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); Execution Results [Result] No. 1 = <document><name>hotel 1</name><price>350</price></document> [Result] No. 2 = <document><name>hotel 3</name><price>250</price></document> [Result] No. 3 = <document><name>hotel 2</name><price>150</price></document> Aggregating the Values of XML Documents that Match Search Conditions When performing a search, the user sometimes prefers to obtain the search results after the value of a specific element has been aggregated. To show how the Java APIs are used, the following example specifies the location in the search conditional expression and extracts the cheapest accommodation rate, the most expensive accommodation rate, and the average accommodation rate. Search Conditions Among the hotels with a vacancy on 2004/07/18, I want to use aggregation to obtain the cheapest hotel, the most expensive hotel and the average hotel rate according to district. Specify the date (2004/07/18) as the search condition and then apply aggregation expressions (min, max and avg) to the results to obtain aggregated results. An Example of Using the APIs The following is a sample program using the Java APIs. import com.fujitsu.shun.shunconnection; import com.fujitsu.shun.shunpreparedstatement; import com.fujitsu.shun.shunresultset; import com.fujitsu.shun.common.shunexception; /*** Obtain the data corresponding to the specified search conditions after it has been aggregated ***/ public class JavaAPISample5 { public static void main(string[] args) { ShunConnection con = null; ShunPreparedStatement pstmt = null; C-15

220 Appendix C Sample Java Programs ShunResultSet rs = null; try { // Search conditional expression String squery = "/document/information/date = = 2004/07/18 "; // Return expression String sreturn = "/document/base/city/text(), min(/document/base/price/text()), max(/document/base/price/text()), avg(/document/base/price/text())"; // Sort expression String ssort = "/document/base/city/text()"; // Create ShunConnection object con = new ShunConnection("DirSvr1", 33101); // Specify search expression and create ShunPreparedStatement object pstmt = con.preparesearch(squery, sreturn); // Specify sort expression pstmt.setsort(ssort); // Set maximum number of items to obtain pstmt.setrequest(1, 30); // Execute search and create ShunResultSet object rs = pstmt.executesearch(); // Obtain data that corresponds to search conditions int counter = 0; String[][] result; while (rs.next()) { counter++; System.out.println( [Result]" + counter + "Item No."); result = rs.getstringarray(); System.out.println(" District " + result[0][0]); System.out.println(" Cheapest rate" + result[1][0]); System.out.println(" Most expensive rate" + result[2][0]); System.out.println(" Average rate" + result[3][0]); rs.close(); pstmt.close(); con.close(); // Processing to perform if an error occurs while the application is running catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); catch (Exception ex) { System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); finally { try { C-16

221 Searching Data if (rs!= null) rs.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (pstmt!= null) pstmt.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (con!= null) con.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); C-17

222 Appendix C Sample Java Programs Execution Results [Result] 1st District Adelaide Cheapest rate 150 Most expensive rate 300 Average rate 200 [Result] 2nd District Sydney Cheapest rate 150 Most expensive rate 350 Average rate 250 C-18

223 Updating Data Updating Data The APIs provided by Shunsaku are used to add, delete, and update data. Java APIs can be used to perform the following operations Adding Data Deleting Data Updating Data Refer to the Java API Reference for more information on the Java APIs. This explanation uses the sample document shown in Searching Data for performing hotel reservation status searches to explain the updating process. Refer also to Appendix G, Notes on XML Documents for more information on XML documents. Adding Data Data to be added The following example shows how the Java APIs are used to add data. I want to add an item of information about an Adelaide hotel (Hotel 9). Assemble the data to be added then add the data. An Example of Using the APIs The following is a sample program using the Java APIs. import com.fujitsu.shun.shunconnection; import com.fujitsu.shun.shunpreparedstatement; import com.fujitsu.shun.common.shunexception; /*** Add specified data ***/ public class JavaAPISample6 { public static void main(string[] args) { ShunConnection con = null; ShunPreparedStatement pstmt = null; try { // Create ShunConnection object con = new ShunConnection("DirSvr1", 33101); // Create ShunPreparedStatement to add data pstmt = con.prepareinsert(); // Create data to be added String adddata = "<document>" + " <base>" + " <name>hotel 9</name>" + " <city>adelaide</city>" + " <address>belair, Adelaide</address>" + " <detail>http//xxxxx.com.au</detail>" C-19

224 Appendix C Sample Java Programs + " <price>150</price>" + " </base>" + " <information>" + " <date>2004/07/18</date>" + " </information>" + "<note>no-smoking room with en-suite bathroom and toilet available, 5 minutes walk to subway station XX</note>" + "</document>"; // Add data pstmt.add(adddata); // Execute data addition pstmt.executeinsert(); System.out.println("Addition complete"); pstmt.close(); con.close(); // Processing to perform if an error occurs while the application is running catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); catch (Exception ex) { System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); finally { try { if (pstmt!= null) pstmt.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (con!= null) con.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR C-20

225 Updating Data System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); Execution Results Addition complete Deleting Data The following example shows how the Java APIs are used to delete data. Search Conditions I want to delete the data relating to Hotel 9 from the hotels in Adelaide that have a vacancy on 2004/07/18. Perform a search using the date (2004/07/18) and location (Adelaide) as conditions, then delete data whose name matches Hotel 9. An Example of Using the APIs The following is a sample program using the Java APIs. import com.fujitsu.shun.shunconnection; import com.fujitsu.shun.shunpreparedrecordid; import com.fujitsu.shun.shunpreparedstatement; import com.fujitsu.shun.shunresultset; import com.fujitsu.shun.common.shunexception; /*** Delete specified data ***/ public class JavaAPISample7 { public static void main(string[] args) { ShunConnection con = null; ShunPreparedStatement pstmt = null; ShunPreparedRecordID rid = null; ShunResultSet rs = null; try { // Search expression String squery = "/document/base/city = = 'Adelaide' AND /document/information/date = = 2004/07/18 "; // Return expression String sreturn = "/document/base/name/text()"; C-21

226 Appendix C Sample Java Programs // Create ShunConnection object con = new ShunConnection("DirSvr1", 33101); // Specify search expression and create ShunPreparedStatement object pstmt = con.preparesearch(squery, sreturn); // Create ShunPreparedRecordID object rid = con.preparedeleterecordid(); //Set maximum number of items to obtain pstmt.setrequest(1, 30); // Execute search and create ShunResultSet object rs = pstmt.executesearch(); // Obtain record ID of Hotel 9 while (rs.next()) { if (rs.getstring().equals("hotel 9")) { rid.add(rs.getrecordid()); rs.close(); pstmt.close(); // If record ID was obtained successfully, delete the corresponding data if (0 < rid.getcount()) { rid.deletebyrecordid(); System.out.println("Deletion complete"); rid.close(); con.close(); // Processing to perform if an error occurs while the application is running catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); catch (Exception ex) { System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); finally { try { if (rs!= null) rs.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); C-22

227 Updating Data break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (pstmt!= null) pstmt.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (rid!= null) rid.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (con!= null) con.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); C-23

228 Appendix C Sample Java Programs Execution Results Deletion complete Updating Data The following example shows how the Java APIs are used to update data. Search Conditions Of the hotels in Sydney that have a vacancy on 2004/07/18, I want to update the information relating to Hotel 1. Perform a search using the date (2004/07/18) as the search condition, then update data whose name matches Hotel 1. An Example of Using the APIs The following is a sample program using the Java APIs. import com.fujitsu.shun.shunconnection; import com.fujitsu.shun.shunpreparedrecordid; import com.fujitsu.shun.shunpreparedstatement; import com.fujitsu.shun.shunresultset; import com.fujitsu.shun.common.shunexception; /*** Update specified data ***/ public class JavaAPISample8 { public static void main(string[] args) { ShunConnection con = null; ShunPreparedStatement pstmt = null; ShunPreparedRecordID rid = null; ShunResultSet rs = null; try { // Record ID of data to be updated String supdaterecordid = null; // Data to be updated String supdatedata = "<document>" + " <base>" + " <name>hotel 1</name>" + " <city>sydney</city>" + " <address>bondi Beach</address>" + " <detail>http//xxxxx.com.au</detail>" + " <price>300</price>" + " </base>" + " <information>" + " <date>2004/07/18</date>" + " </information>" + " <note>en-suite bathroom and toilet, two minutes walk to train station XX</note>" + "</document>"; // Search expression String squery = "/document/base/name = = 'Hotel 1'"; // Return expression String sreturn = "/document/base/name/text()"; // Create ShunConnection object C-24

229 Updating Data con = new ShunConnection("DirSvr1", 33101); // Specify search expression and create ShunPreparedStatement object pstmt = con.preparesearch(squery, sreturn); //Set maximum number of items to obtain pstmt.setrequest(1, 30); // Execute search and create ShunResultSet object rs = pstmt.executesearch(); // Create ShunPreparedRecordID object rid = con.prepareupdaterecordid(); //Set maximum number of items to obtain pstmt.setrequest(1, 30); // Execute search and create ShunResultSet object rs = pstmt.executesearch(); // Obtain one item of data that corresponds to search conditions while (rs.next()) { // Set the record ID and data to update for Hotel 1 information if (rs.getstring().equals("hotel 1")) { rid.add(rs.getrecordid(), supdatedata); // Update the data if the data was set successfully if (0 < rid.getcount()) { rid.updatebyrecordid(); System.out.println("Update complete"); // Processing to perform if an error occurs while the application is running catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); catch (Exception ex) { System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); finally { try { if (rs!= null) rs.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; C-25

230 Appendix C Sample Java Programs case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (pstmt!= null) pstmt.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (rid!= null) rid.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); try { if (con!= null) con.close(); catch (ShunException ex) { int errorlevel = ex.geterrlevel(); switch( errorlevel ) { case ShunException.SHUN_ERROR System.out.println("Error level SHUN_ERROR"); break; case ShunException.SHUN_ERROR_CONNECTION_TERMINATED System.out.println("Error level SHUN_ERROR_CONNECTION_TERMINATED"); break; System.out.println("Error message" + ex.getmessage()); ex.printstacktrace(); C-26

231 Updating Data Execution Results Update complete C-27

232 Appendix C Sample Java Programs C-28

233 Appendix D Sample C Programs This appendix provides examples of programs that use C APIs. Searching Data Updating Data D-1

234 Appendix D Sample C Programs Searching Data Use the APIs provided by Shunsaku to obtain search results by specifying search conditions for the data to be retrieved. C APIs can be used for performing the following operations Obtaining the Number of XML Documents that Match Search Conditions Obtaining XML Documents that Match Search Conditions in a Specified Format Obtain Every Instance of Particular XML Documents Obtaining XML Documents that Match Search Conditions after they have been Sorted Aggregating the Values of XML Documents that Match Search Conditions Refer to the C API Reference for more information on C APIs. This section uses the example of a hotel reservation status search system to explain the search operation. For the purposes of this explanation, it is assumed that the sample XML document below exists. Refer also to Appendix G, Notes on XML Documents for more information on XML documents. Sample Document <document> <base> <name>hotel 1</name> <city>sydney</city> <address>bondi Beach</address> <detail>http//xxxxx.com.au</detail> <price>220</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, two minutes walk to train station XX</note> </document> <document> <base> <name>hotel 2</name> <city>sydney</city> <address>bondi Beach</address> <detail>http//xxxxx.com.au</detail> <price>300</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, five minutes walk to train station XX</note> </document> <document> <base> <name>hotel 3</name> <city>sydney</city> <address>bondi Beach</address> D-2

235 Searching Data <detail>http//xxxxx.com.au</detail> <price>350</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, ten minutes walk to train station XX</note> </document> <document> <base> <name>hotel 4</name> <city>sydney</city> <address>paddington</address> <detail>http//xxxxx.com.au</detail> <price>400</price> </base> <information> <date>2004/07/10</date> </information> <note>en-suite bathroom and toilet, three minutes walk to train station ZZ</note> </document> <document> <base> <name>hotel 5</name> <city>sydney</city> <address>paddington</address> <detail>http//xxxxx.com.au</detail> <price>200</price> </base> <information> <date>2004/07/10</date> </information> <note>en-suite bathroom and toilet, two minutes walk to train station ZZ</note> </document> <document> <base> <name>hotel 6</name> <city>adelaide</city> <address>clearview</address> <detail>http//xxxxx.com.au</detail> <price>200</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, two minutes walk to train station XX</note> </document> <document> <base> <name>hotel 7</name> <city>adelaide</city> <address>belair</address> <detail>http//xxxxx.com.au</detail> <price>300</price> </base> <information> <date>2004/07/18</date> </information> D-3

236 Appendix D Sample C Programs <note>en-suite bathroom and toilet, three minutes walk to train station XX</note> </document> <document> <base> <name> Hotel 8</name> <city>adelaide</city> <address>bradbury</address> <detail>http//xxxxx.com.au</detail> <price>270</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, five minutes walk to train station XX</note> </document> Obtaining the Number of XML Documents that Match Search Conditions If there is a large amount of data to be searched, it is not practical to look up all the data items that match the conditional expression. In such cases, it is useful to find out how many data items match the specified condition. The example below shows how to use the APIs to find out how many hotels match the date and location specified as the search conditions. Search Conditions How many hotels in Sydney with vacancies on 2004/07/18? Perform a search using the date (2004/07/18) and the location (Sydney) as the search conditions. An Example of Using the APIs The following is a sample program using the C APIs. #include <stdio.h> #include "libshun.h" /* Obtain the number of XML documents that match specified search conditions */ int main() { /* Handle variables */ SHUNHCON connectionhandle; SHUNHSTMT statementhandle; /* Work variables */ int status; /* Input parameters */ char *hostname; int portno; char *ShunFileName; char *queryform; /* Output parameters */ D-4

237 Searching Data int hitcount; /* Error variables */ SHUNHANDLE errorhandle; int errorlevel; char *errormessage; /* Variable initialization */ connectionhandle = NULL; statementhandle = NULL; /* Connection handle allocation */ status = ShunAllocHandle( NULL, &connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify host name, port number and Shunsaku file name and establish connection */ hostname = "DirSvr1"; portno = 33101; ShunFileName = "shunsakufile1"; status = ShunConnect( connectionhandle, hostname, portno, ShunFileName ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify search expression */ queryform = "/document {/base/city == 'Sydney' " "AND /information/date == '2004/07/18'"; /* Call API then specify search expression and obtain number of hits */ status = ShunGetHitCount( statementhandle, queryform, &hitcount ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle; goto ErrorEnd; /* Extract number of hits */ printf( "Number of hits = %d\n", hitcount ); /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle; goto ErrorEnd; D-5

238 Appendix D Sample C Programs /* Disconnect */ status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Release connection handle */ status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; return 0; ErrorEnd /* Processing to perform in the event of an error */ /* Obtain error information */ status = ShunGetErrorMessage(errorHandle, &errorlevel, &errormessage); if ( status == SHUN_SUCCESS ) { switch ( errorlevel ) { case SHUN_ERROR_CONNECTION printf("error level break; case SHUN_ERROR_DATA printf("error level break; printf("error message = SHUN_ERROR_CONNECTION\n"); = SHUN_ERROR_DATA\n"); = %s\n", errormessage); else { printf("error message acquisition error %d\n", status); /* Release data manipulation handle */ if ( statementhandle!= NULL ) { status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Disconnect */ if ( connectionhandle!= NULL) { status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("disconnection error %d\n", status); /* Release connection handle */ if ( connectionhandle!= NULL) { status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("connection handle release error %d\n", status); D-6

239 Searching Data return 1; Execution Results Number of hits = 3 Obtaining XML Documents that Match Search Conditions in a Specified Format Part of the data obtained as search results is sometimes used as additional conditions to perform the next search operation. In this case, it is common to obtain only part of the data as search results instead of the entire data. The example below shows how to use the C APIs to find out how many hotels match the date and location specified as the search condition, as well as to get partial information. Search Conditions I would like to know the names and accommodation rates of up to 30 of the hotels in Sydney that are available on 2004/07/18. Perform a search using the date (2004/07/18) and the location (Sydney) as the search conditions, and then obtain the names and accommodation rates of 30 of the hotels from the results of this search. An Example of Using the APIs The following is a sample program using the C APIs. #include <stdio.h> #include "libshun.h" /* Obtain matching XML documents in a specified format */ int main() { /* Handle variables */ SHUNHCON connectionhandle; SHUNHSTMT statementhandle; /* Work variables */ int status; int i; /* Input parameters */ char *hostname; int portno; char *ShunFileName; int startno; int returnrequestcount; char *queryform; char *returnform; char *sortform; /* Output parameters */ int hitcount; int returncount; D-7

240 Appendix D Sample C Programs int returnablecount; SHUNRECID *recid; SHUNDATA *datainfo; SHUNPOS *firstposition, *lastposition; /* Error variables */ SHUNHANDLE errorhandle; int errorlevel; char *errormessage; /* Variable initialization */ connectionhandle = NULL; statementhandle = NULL; /* Connection handle allocation */ status = ShunAllocHandle( NULL, &connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify host name, port number and Shunsaku file name and establish connection */ hostname = "DirSvr1"; portno = 33101; ShunFileName = "shunsakufile1"; status = ShunConnect( connectionhandle, hostname, portno, ShunFileName ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify number of items to find, search expression, etc. */ startno = 1; returnrequestcount = 30; queryform = "/document {/base/city == 'Sydney' " "AND /information/date == '2004/07/18'"; returnform = "/document/base/name, /document/base/price "; sortform = NULL; /* Call API and perform data search */ status = ShunSearch( statementhandle, startno, NULL, 0, returnrequestcount, queryform, returnform, sortform, &hitcount, &returncount, &returnablecount, D-8

241 Searching Data &recid, &datainfo, &firstposition, &lastposition ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle; goto ErrorEnd; /* Extract number of hits */ printf( "Number of hits = %d\n", hitcount ); /* Display data that was found */ if ( hitcount > 0 ) { for (i = 0; i < returncount; ++i) { if ( datainfo[i].data_len > 0 ) { printf( "[Result] Item No. %d =%s\n", startno + i, datainfo[i].data); else { printf( "[Result]Item No. %d = No data\n", startno + i ); /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle; goto ErrorEnd; /* Disconnect */ status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Release connection handle */ status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; return 0; ErrorEnd /* Processing to perform in the event of an error */ /* Obtain error information */ status = ShunGetErrorMessage(errorHandle, &errorlevel, &errormessage); if ( status == SHUN_SUCCESS ) { switch ( errorlevel ) { case SHUN_ERROR_CONNECTION printf("error level break; case SHUN_ERROR_DATA = SHUN_ERROR_CONNECTION\n"); D-9

242 Appendix D Sample C Programs printf("error level = SHUN_ERROR_DATA\n"); break; printf("error message = %s\n", errormessage); else { printf("error message acquisition error %d\n", status); /* Release data manipulation handle */ if ( statementhandle!= NULL ) { status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Disconnect */ if ( connectionhandle!= NULL) { status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("disconnection error %d\n", status); /* Release connection handle */ if ( connectionhandle!= NULL) { status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("connection handle release error %d\n", status); return 1; Execution Results Number of hits = 3 [Result] Item No. 1 = <document><name>hotel 1</name><price>220</price></document> [Result] Item No. 2 = <document><name>hotel 2</name><price>300</price></document> [Result] Item No. 3 = <document><name>hotel 3</name><price>350</price></document> Obtain Every Instance of Particular XML Documents The search process performs the operations stated in Obtaining the Number of XML Documents that Match Search Conditions and Obtaining XML Documents that Match Search Conditions in a Specified Format to obtain all the data based on the filtering conditions. The following example shows how the C APIs are used. It shows how all the data of applicable hotels can be retrieved based on the hotel names obtained using the operations stated in Obtaining XML Documents that Match Search Conditions in a Specified Format. D-10

243 Searching Data Search Conditions Find the names of 30 hotels in Sydney with vacancies on 2004/07/18 Perform a search using the date (2004/07/18) and the location (Sydney) as the search conditions, then obtain detailed information on a particular hotel using the record identifier corresponding to that hotel name. An Example of Using the APIs The following is a sample program using the C APIs. #include <stdio.h> #include "libshun.h" /* Obtain all instances of specific XML documents */ int main() { /* Handle variables */ SHUNHCON connectionhandle; SHUNHSTMT statementhandle_serch; SHUNHSTMT statementhandle_rec_id; /* Work variables */ int status; int i; /* Input parameters */ char *hostname; int portno; char *ShunFileName; int startno; int returnrequestcount; char *queryform; char *returnform; char *sortform; /* Output parameters */ int hitcount; int returncount; int returnablecount; SHUNRECID *recid_search; SHUNRECID *recid_search_rec_id; SHUNDATA *datainfo_serch; SHUNDATA *datainfo_rec_id; SHUNPOS *firstposition, *lastposition; /* Error variables */ SHUNHANDLE errorhandle; int errorlevel; char *errormessage; /* Variable initialization */ connectionhandle = NULL; statementhandle_serch = NULL; statementhandle_rec_id = NULL; /* Connection handle allocation */ status = ShunAllocHandle( NULL, &connectionhandle ); if ( status!= SHUN_SUCCESS ) { D-11

244 Appendix D Sample C Programs errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify host name, port number and Shunsaku file name and establish connection */ hostname = "DirSvr1"; portno = 33101; ShunFileName = "shunsakufile1"; status = ShunConnect( connectionhandle, hostname, portno, ShunFileName ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle_serch ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify number of items to find, search expression, etc. */ startno = 1; returnrequestcount = 30; queryform = "/document {/base/city == 'Sydney' " "AND /information/date == '2004/07/18'"; returnform = "/document/base/name, /document/base/price "; sortform = NULL; /* Call API and perform data search */ status = ShunSearch( statementhandle_serch, startno, NULL, 0, returnrequestcount, queryform, returnform, sortform, &hitcount, &returncount, &returnablecount, &recid_search, &datainfo_serch, &firstposition, &lastposition ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_serch; goto ErrorEnd; /* Extract number of hits */ printf( "Number of hits = %d\n", hitcount ); printf( "Number of responses = %d\n", returncount ); /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle_rec_id ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; D-12

245 Searching Data goto ErrorEnd; /* Obtain all data based on ID */ if ( hitcount > 0 ) { status = ShunSearchRecId( statementhandle_rec_id, returncount, recid_search, &recid_search_rec_id, &datainfo_rec_id ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_rec_id; goto ErrorEnd; for (i = 0; i < returncount; ++i) { printf( "[Details]Item No. %d =%s\n", startno + i, datainfo_rec_id[i].data); /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle_rec_id ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_rec_id; goto ErrorEnd; /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle_serch ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_serch; goto ErrorEnd; /* Disconnect */ status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Release connection handle */ status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; return 0; ErrorEnd /* Processing to perform in the event of an error */ /* Obtain error information */ status = ShunGetErrorMessage(errorHandle, &errorlevel, &errormessage); if ( status == SHUN_SUCCESS ) { switch ( errorlevel ) { case SHUN_ERROR_CONNECTION printf("error level = SHUN_ERROR_CONNECTION\n"); break; D-13

246 Appendix D Sample C Programs case SHUN_ERROR_DATA printf("error level = SHUN_ERROR_DATA\n"); break; printf("error message = %s\n", errormessage); else { printf("error message acquisition error %d\n", status); /* Release data manipulation handle */ if ( statementhandle_rec_id!= NULL ) { status = ShunFreeHandle( statementhandle_rec_id ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Release data manipulation handle */ if ( statementhandle_serch!= NULL ) { status = ShunFreeHandle( statementhandle_serch ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Disconnect */ if ( connectionhandle!= NULL) { status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("disconnection error %d\n", status); /* Release connection handle */ if ( connectionhandle!= NULL) { status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("connection handle release error %d\n", status); return 1; D-14

247 Searching Data Execution Results Number of hits = 3 Number of responses = 3 [Details] Item No. 1 = <document> <base> <name>hotel 1</name> <city>sydney</city> <address>bondi Beach</address> <detail>http//xxxxx.com.au</detail> <price>220</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, two minutes walk to train station XX</note> </document> [Details] Item No. 2 = <document> <base> <name>hotel 2</name> <city>sydney</city> <address>bondi Beach</address> <detail>http//xxxxx.com.au</detail> <price>300</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, five minutes walk to train station XX</note> </document> [Details] Item No. 3 = <document> <base> <name>hotel 3</name> <city>sydney</city> <address>bondi Beach</address> <detail>http//xxxxx.com.au</detail> <price>350</price> </base> <information> <date>2004/07/18</date> </information> <note>en-suite bathroom and toilet, ten minutes walk to train station XX</note> </document> D-15

248 Appendix D Sample C Programs Obtaining XML Documents that Match Search Conditions after they have been Sorted When performing a search, the user sometimes prefers to obtain the search results after they have been sorted according to a specific element. To show how the C APIs are used, the following example specifies the date and location in the search conditional expression, obtains the number of hotels that match the conditions and partial information about those hotels, and then uses the accommodation rate as a key to sort the results. Search Conditions I would like to know 30 hotels in Sydney that are available on 2004/07/18, and I want to obtain the results sorted in descending order according to the accommodation rate. Specify the date (2004/07/18) and the location (Sydney) as search conditions and execute the search. Then, obtain the top 30 hotel names after they have been sorted in descending order according to the accommodation rate. An Example of Using the APIs The following is a sample program using the C APIs. #include <stdio.h> #include "libshun.h" /* Obtain XML documents that match specified search conditions after the documents have been sorted */ int main() { /* Handle variables */ SHUNHCON connectionhandle; SHUNHSTMT statementhandle; /* Work variables */ int status; int i; /* Input parameters */ char *hostname; int portno; char *ShunFileName; int startno; int returnrequestcount; char *queryform; char *returnform; char *sortform; /* Output parameters */ int hitcount; int returncount; int returnablecount; SHUNRECID *recid; SHUNDATA *datainfo; SHUNPOS *firstposition, *lastposition; /* Error variables */ SHUNHANDLE errorhandle; D-16

249 Searching Data int errorlevel; char *errormessage; /* Variable initialization */ connectionhandle = NULL; statementhandle = NULL; /* Connection handle allocation */ status = ShunAllocHandle( NULL, &connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify host name, port number and Shunsaku file name and establish connection */ hostname = "DirSvr1"; portno = 33101; ShunFileName = "shunsakufile1"; status = ShunConnect( connectionhandle, hostname, portno, ShunFileName ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify number of items to find, search expression, etc. */ startno = 1; returnrequestcount = 30; queryform = "/document {/base/city == 'Sydney' " "AND /information/date == '2004/07/18'"; returnform = "/document/base/name, /document/base/price "; sortform = "/document/base/price/text() DESC"; /* Call API and perform data search */ status = ShunSearch( statementhandle, startno, NULL, 0, returnrequestcount, queryform, returnform, sortform, &hitcount, &returncount, &returnablecount, &recid, &datainfo, &firstposition, &lastposition ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle; D-17

250 Appendix D Sample C Programs goto ErrorEnd; /* Extract number of hits */ printf( "Number of hits = %d\n", hitcount ); /* Display data that was found */ if ( hitcount > 0 ) { for (i = 0; i < returncount; ++i) { if ( datainfo[i].data_len > 0 ) { printf( "[Result] Item No. %d =%s\n", startno + i, datainfo[i].data); else { printf( "[Result]Item No. %d = No data\n", startno + i ); /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) {errorhandle = SHUNHANDLE)statementHandle; goto ErrorEnd; /* Disconnect */ status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Release connection handle */ status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; return 0; ErrorEnd /* Processing to perform in the event of an error */ /* Obtain error information */ status = ShunGetErrorMessage(errorHandle, &errorlevel, &errormessage); if ( status == SHUN_SUCCESS ) { switch ( errorlevel ) { case SHUN_ERROR_CONNECTION printf("error level break; case SHUN_ERROR_DATA printf("error level break; printf("error message = SHUN_ERROR_CONNECTION\n"); = SHUN_ERROR_DATA\n"); = %s\n", errormessage); else { printf("error message acquisition error %d\n", status); D-18

251 Searching Data /* Release data manipulation handle */ if ( statementhandle!= NULL ) { status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Disconnect */ if ( connectionhandle!= NULL) { status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("disconnection error %d\n", status); /* Release connection handle */ if ( connectionhandle!= NULL) { status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("connection handle release error %d\n", status); return 1; Execution Results Number of hits = 3 [Result]Item No. 1 = <document><name>hotel 3</name><price>350</price></document> [Result]Item No. 2 = <document><name>hotel 2</name><price>300</price></document> [Result]Item No. 3 = <document><name>hotel 1</name><price>220</price></document> Aggregating the Values of XML Documents that Match Search Conditions When performing a search, the user sometimes prefers to obtain the search results after the value of a specific element has been aggregated. To show how the C APIs are used, the following example specifies the date and location in the search conditional expression and extracts the number of hotels that match the conditions, the most expensive accommodation rate, the cheapest accommodation rate, and the average accommodation rate. Search Conditions Among the hotels with a vacancy on 2004/07/18, I want to find the most expensive hotel rate, the cheapest hotel rate, and the average hotel rate in each city. Perform the search using the date (2004/07/18) as the search condition. D-19

252 Appendix D Sample C Programs An Example of Using the APIs The following is a sample program using the C APIs. #include <stdio.h> #include "libshun.h" /* Obtain the XML documents that match the specified search conditions after the values have been aggregated */ int main() { /* Handle variables */ SHUNHCON connectionhandle; SHUNHSTMT statementhandle; /* Work variables */ int status; int i, k; /* Input parameters */ char *hostname; int portno; char *ShunFileName; int startno; int returnrequestcount; char *queryform; char *returnform; char *sortform; /* Output parameters */ int hitcount; int returncount; int returnablecount; SHUNRECID *recid; SHUNDATA *datainfo; SHUNPOS *firstposition, *lastposition; /* Error variables */ SHUNHANDLE errorhandle; int errorlevel; char *errormessage; /* Variable initialization */ connectionhandle = NULL; statementhandle = NULL; /* Connection handle allocation */ status = ShunAllocHandle( NULL, &connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify host name, port number and Shunsaku file name and establish connection */ hostname = "DirSvr1"; portno = 33101; ShunFileName = "shunsakufile1"; status = ShunConnect( connectionhandle, hostname, portno, ShunFileName ); D-20

253 Searching Data if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify number of items to find, search expression, etc. */ startno = 1; returnrequestcount = 30; queryform = "/document/information/date == '2004/07/18'"; returnform = "/document/base/city/text()," "count(/document/base/city/text())," "max(/document/base/price/text())," "min(/document/base/price/text())," "avg(/document/base/price/text())"; sortform = "/document/base/city/text()"; /* Call API and perform data search */ status = ShunSearch( statementhandle, startno, NULL, 0, returnrequestcount, queryform, returnform, sortform, &hitcount, &returncount, &returnablecount, &recid, &datainfo, &firstposition, &lastposition ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle; goto ErrorEnd; /* Extract number of hits */ printf( "Number of hits = %d\n", hitcount ); /* Display data that was found */ if ( hitcount > 0 ) { for (i = 0; i < returncount; ++i) { if ( datainfo[i].data_len > 0 ) { /* To make retrieved data well formed, convert \001 and \002 to spaces */ for (k = 0; k < datainfo[i].data_len; ++k) { switch ( datainfo[i].data[k] ) { case '\001' datainfo[i].data[k] = ' '; break; case '\002' datainfo[i].data[k] = ' '; break; default break; printf( "[Result] Item No. %d =%s\n", startno + i, D-21

254 Appendix D Sample C Programs datainfo[i].data) ; else { printf( "[Result]Item No. %d = No data\n", startno + i ); /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle; goto ErrorEnd; /* Disconnect */ status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Release connection handle */ status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; return 0; ErrorEnd /* Processing to perform in the event of an error */ /* Obtain error information */ status = ShunGetErrorMessage(errorHandle, &errorlevel, &errormessage); if ( status == SHUN_SUCCESS ) { switch ( errorlevel ) { case SHUN_ERROR_CONNECTION printf("error level = SHUN_ERROR_CONNECTION\n"); break; case SHUN_ERROR_DATA printf("error level = SHUN_ERROR_DATA\n"); break; printf("error message = %s\n", errormessage); else { printf("error message acquisition error %d\n", status); /* Release data manipulation handle */ if ( statementhandle!= NULL ) { status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Disconnect */ if ( connectionhandle!= NULL) { status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { D-22

255 Searching Data printf("disconnection error %d\n", status); /* Release connection handle */ if ( connectionhandle!= NULL) { status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("connection handle release error %d\n", status); return 1; Execution Results Number of hits = 6 [Result]Item No. 1 = Adelaide [Result]Item No. 2 = Sydney D-23

256 Appendix D Sample C Programs Updating Data The APIs provided by Shunsaku are used to add, delete, and update data. C APIs can be used to perform the following operations Adding Data Deleting Data Updating Data Refer to the C API Reference for more information on the C APIs. This explanation uses the sample document shown in Searching Data for performing hotel reservation status searches to explain the updating process. Refer also to Appendix G, Notes on XML Documents for more information on XML documents. Adding Data The following example shows how the C APIs are used to add data. An Example of Using the APIs The following is a sample program using the C APIs. #include <stdio.h> #include <string.h> #include "libshun.h" /* Add data */ int main() { /* Handle variables */ SHUNHCON connectionhandle; SHUNHSTMT statementhandle; /* Work variables */ int status; /* Input parameters */ char *hostname; int portno; char *ShunFileName; SHUNDATA inputdata[1]; /* Error variables */ SHUNHANDLE errorhandle; int errorlevel; char *errormessage; /* Variable initialization */ connectionhandle = NULL; statementhandle = NULL; D-24

257 Updating Data /* Connection handle allocation */ status = ShunAllocHandle( NULL, &connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify host name, port number and Shunsaku file name and establish connection */ hostname = "DirSvr1"; portno = 33101; ShunFileName = "shunsakufile1"; status = ShunConnect( connectionhandle, hostname, portno, ShunFileName ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Create data to be added */ inputdata[0].data = "<document>" " <base>" " <name>hotel 9</name>" " <city>adelaide</city>" " <address>clearview</address>" " <detail>http//xxxxx.com.au</detail>" " <price>300</price>" " </base>" " <information>" " <date>2004/07/18</date>" " </information>" " <note>en-suite bathroom and toilet, five minutes walk to train station XX</note>" "</document>"; inputdata[0].data_len = strlen( inputdata[0].data ); /* Call API and add data */ status = ShunInsert( statementhandle, 1, inputdata ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle; goto ErrorEnd; printf( "Addition successful\n" ); /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle; goto ErrorEnd; D-25

258 Appendix D Sample C Programs /* Disconnect */ status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Release connection handle */ status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; return 0; ErrorEnd /* Processing to perform in the event of an error */ /* Obtain error information */ status = ShunGetErrorMessage(errorHandle, &errorlevel, &errormessage); if ( status == SHUN_SUCCESS ) { switch ( errorlevel ) { case SHUN_ERROR_CONNECTION printf("error level = SHUN_ERROR_CONNECTION\n"); break; case SHUN_ERROR_DATA printf("error level = SHUN_ERROR_DATA\n"); break; printf("error message = %s\n", errormessage); else { printf("error message acquisition error %d\n", status); /* Release data manipulation handle */ if ( statementhandle!= NULL ) { status = ShunFreeHandle( statementhandle ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Disconnect */ if ( connectionhandle!= NULL) { status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("disconnection error %d\n", status); /* Release connection handle */ if ( connectionhandle!= NULL) { status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("connection handle release error %d\n", status); D-26

259 Updating Data return 1; Execution Results Addition successful Deleting Data The following example shows how the C APIs are used to delete data. Search Conditions 'I want to delete the data for Hotel 9 from all data relating to hotels in Adelaide that have a vacancy on 2004/07/18.' Perform a search using the date (2004/07/18) and location (Adelaide) as conditions, and then delete the data where the hotel name matches "Hotel 9". An Example of Using the APIs The following is a sample program using the C APIs. #include <stdio.h> #include "libshun.h" /* Delete data */ int main() { /* Handle variables */ SHUNHCON connectionhandle; SHUNHSTMT statementhandle_search; SHUNHSTMT statementhandle_del; /* Work variables */ int status; /* Input parameters */ char *hostname; int portno; char *ShunFileName; int startno; int returnrequestcount; char *queryform; char *returnform; char *sortform; /* Output parameters */ int hitcount; int returncount; int returnablecount; SHUNRECID *recid; SHUNDATA *datainfo; SHUNPOS *firstposition, *lastposition; /* Error variables */ D-27

260 Appendix D Sample C Programs SHUNHANDLE errorhandle; int errorlevel; char *errormessage; /* Variable initialization */ connectionhandle = NULL; statementhandle_search = NULL; statementhandle_del = NULL; /* Connection handle allocation */ status = ShunAllocHandle( NULL, &connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify host name, port number and Shunsaku file name and establish connection */ hostname = "DirSvr1"; portno = 33101; ShunFileName = "shunsakufile1"; status = ShunConnect( connectionhandle, hostname, portno, ShunFileName ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle_search ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify number of items to find, search expression, etc. */ startno = 1; returnrequestcount = 30; queryform = "/document/base/city == 'Adelaide' " "AND /document/information/date == '2004/07/18' " "AND /document/base/name == 'Hotel 9'"; returnform = "/document/base/name, /document/base/price "; sortform = NULL; /* Call API and perform data search */ status = ShunSearch( statementhandle_search, startno, NULL, 0, returnrequestcount, queryform, returnform, sortform, &hitcount, &returncount, &returnablecount, &recid, &datainfo, &firstposition, &lastposition ); D-28

261 Updating Data if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_search; goto ErrorEnd; /* Extract number of hits */ printf( "Number of hits = %d\n", hitcount ); printf( "Number of responses = %d\n", returncount ); /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle_del ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Delete all data based on ID */ if ( hitcount > 0 ) { status = ShunDeleteRecId( statementhandle_del, returncount, recid); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_del; goto ErrorEnd; printf( "Deletion successful\n" ); /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle_del ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_del; goto ErrorEnd; /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle_search ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_search; goto ErrorEnd; /* Disconnect */ status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Release connection handle */ status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; return 0; D-29

262 Appendix D Sample C Programs ErrorEnd /* Processing to perform in the event of an error */ /* Obtain error information */ status = ShunGetErrorMessage(errorHandle, &errorlevel, &errormessage); if ( status == SHUN_SUCCESS ) { switch ( errorlevel ) { case SHUN_ERROR_CONNECTION printf("error level = SHUN_ERROR_CONNECTION\n"); break; case SHUN_ERROR_DATA printf("error level = SHUN_ERROR_DATA\n"); break; printf("error message = %s\n", errormessage); else { printf("error message acquisition error %d\n", status); /* Release data manipulation handle */ if ( statementhandle_del!= NULL ) { status = ShunFreeHandle( statementhandle_del ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Release data manipulation handle */ if ( statementhandle_search!= NULL ) { status = ShunFreeHandle( statementhandle_search ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Disconnect */ if ( connectionhandle!= NULL) { status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("disconnection error %d\n", status); /* Release connection handle */ if ( connectionhandle!= NULL) { status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("connection handle release error %d\n", status); return 1; D-30

263 Updating Data Execution Results Number of hits = 1 Number of responses = 1 Deletion successful Updating Data The following example shows how the C APIs are used to update data. An Example of Using the APIs The following is a sample program using the C APIs. #include <stdio.h> #include "libshun.h" /* Obtain the records that correspond to the specified search conditions * then edit the records and overwrite the data. */ int main() { /* Handle variables */ SHUNHCON connectionhandle; SHUNHSTMT statementhandle_search; SHUNHSTMT statementhandle_update; /* Work variables */ int status; /* Input parameters */ char *hostname; int portno; char *ShunFileName; int startno; int returnrequestcount; char *queryform; char *returnform; char *sortform; /* Output parameters */ int hitcount; int returncount; int returnablecount; SHUNRECID *recid; SHUNDATA *datainfo; SHUNPOS *firstposition, *lastposition; /* Error variables */ SHUNHANDLE errorhandle; int errorlevel; char *errormessage; /* Variable initialization */ connectionhandle = NULL; statementhandle_search = NULL; statementhandle_update = NULL; D-31

264 Appendix D Sample C Programs /* Connection handle allocation */ status = ShunAllocHandle( NULL, &connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify host name, port number and Shunsaku file name and establish connection */ hostname = "DirSvr1"; portno = 33101; ShunFileName = "shunsakufile1"; status = ShunConnect( connectionhandle, hostname, portno, ShunFileName ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle_search ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Specify number of items to find, search expression, etc. */ startno = 1; returnrequestcount = 30; queryform = "/document {/base/city == 'Sydney' " "AND /information/date == '2004/07/18'"; returnform = "/"; sortform = NULL; /* Call API and perform data search */ status = ShunSearch( statementhandle_search, startno, NULL, 0, returnrequestcount, queryform, returnform, sortform, &hitcount, &returncount, &returnablecount, &recid, &datainfo, &firstposition, &lastposition ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_search; goto ErrorEnd; /* Extract number of hits */ printf( "Number of hits = %d\n", hitcount ); printf( "Number of responses = %d\n", returncount ); /* Display data that was found */ if ( hitcount > 0 ) { D-32

265 Updating Data /* Allocation of data manipulation handles */ status = ShunAllocHandle( connectionhandle, &statementhandle_update ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Here, data processing is performed on datainfo */ status = ShunUpdateRecId( statementhandle_update, returncount, recid, datainfo ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_update; goto ErrorEnd; printf( "Update successful\n" ); /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle_update ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_update; goto ErrorEnd; /* Release data manipulation handle */ status = ShunFreeHandle( statementhandle_search ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)statementHandle_search; goto ErrorEnd; /* Disconnect */ status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) {errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; /* Release connection handle */ status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { errorhandle = (SHUNHANDLE)connectionHandle; goto ErrorEnd; return 0; ErrorEnd /* Processing to perform in the event of an error */ /* Obtain error information */ status = ShunGetErrorMessage(errorHandle, &errorlevel, &errormessage); D-33

266 Appendix D Sample C Programs if ( status == SHUN_SUCCESS ) { switch ( errorlevel ) { case SHUN_ERROR_CONNECTION printf("error level = SHUN_ERROR_CONNECTION\n"); break; case SHUN_ERROR_DATA printf("error level = SHUN_ERROR_DATA\n"); break; printf("error message = %s\n", errormessage); else { printf("error message acquisition error %d\n", status); /* Release data manipulation handle */ if ( statementhandle_update!= NULL ) { status = ShunFreeHandle( statementhandle_update ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Release data manipulation handle */ if ( statementhandle_search!= NULL ) { status = ShunFreeHandle( statementhandle_search ); if ( status!= SHUN_SUCCESS ) { printf("data manipulation handle release error %d\n", status); /* Disconnect */ if ( connectionhandle!= NULL) { status = ShunDisconnect( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("disconnection error %d\n", status); /* Release connection handle */ if ( connectionhandle!= NULL) { status = ShunFreeHandle( connectionhandle ); if ( status!= SHUN_SUCCESS ) { printf("connection handle release error %d\n", status); return 1; Execution Results Number of hits = 3 Number of responses = 3 Update successful D-34

267 Appendix E Allowable Values This appendix explains the allowable values associated with the development of Shunsaku applications. Allowable Values for Search Expressions and Return Expressions Allowable Values for Sort Requests Allowable Values for Aggregation Requests E-1

268 Appendix E Allowable Values Allowable Values for Search Expressions and Return Expressions The following table lists the allowable values associated with search expressions and return expressions. Table E-1 Allowable Values Relating to Search Expressions and Return Expressions Item Allowable value Length of search expression From 1 to 65, 535 bytes (excluding \0) Length of return expression From 1 to 65, 535 bytes (excluding \0) E-2

269 Allowable Values for Sort Requests Allowable Values for Sort Requests The following table lists the allowable values associated with sort requests. Table E-2 Allowable Values Relating to Sort Requests Item Allowable value Remarks Maximum number of keys that can be specified Sort expression Total sort key length Number of characters when the rlen function is specified as the key Number of items that can be returned 8 - From 1 to 65, 535 bytes (excluding \0) - 1 to 2,000 bytes The total sort key length is the total length of all the sort keys in key specifications. Refer to Relationship between the Total Sort Key Length and the Total Number of Items that Can be Returned for more information on how the total sort key length affects the number of items that can be returned. 1 to 128 The length of the character string resulting from the rlen function is shown in the table entitled Relationship between character encoding and the length of the string resulting from the rlen function. 100 to 1,000 records When the total length of sort keys is 200 bytes or less, the records corresponding to the top 1,000 items can be returned. If the total length of sort keys exceeds 200 bytes, the number of records that can be returned is indicated in Relationship between the Total Sort Key Length and the Total Number of Items that Can be Returned. Relationship between the Total Sort Key Length and the Total Number of Items that Can be Returned The total sort key length is the total length of all the sort keys in key specifications. The length of each key is determined by the key specification format, as shown in the following table. Table E-3 Determining Key Length Key specification format Length of sort key Remarks val function 16 bytes - Text format 20 bytes The first 20 bytes are used as the sort key. To sort using a string that is longer than 20 bytes, specify the rlen function as the key specification of the sort expression. By specifying the rlen function, it becomes possible to perform a sort using up to 128 characters as a sort key. E-3

270 Appendix E Allowable Values Key specification format rlen function Length of sort key The length of the character string resulting from the rlen function is shown in the table entitled Relationship between character encoding and the length of the string resulting from the rlen function. Remarks - The character encoding of the director data determines the byte length of each character of the character string produced by the rlen function, as shown below. Table E-4 Relationship between Character Encoding and the Length of the String Resulting from the rlen Function Character encoding No. of bytes per character Example UTF-8 4 bytes rlen(/root/name/text(),50) would be treated as 200 bytes. SHIFT-JIS GB2312 big5 KSC bytes rlen(/root/name/text(),50) would be treated as 100 bytes. EUC 3 bytes rlen(/root/name/text(),50) would be treated as 150 bytes. The following table shows how the total sort key length affects the number of records that Shunsaku can return. Table E-5 Relationship between Total Sort Key Length and the Number of Items that can be Returned by Shunsaku Total sort key length (bytes) Number of items that can be returned 1 to 200 1, to to to to to 1, ,001 to 2, E-4

271 Allowable Values for Aggregation Requests Allowable Values for Aggregation Requests The following table lists the allowable values associated with aggregation requests. Table E-6 Allowable Values for Aggregation Requests Item Allowable value Remarks Maximum number of keys that can be specified 8 - Sort expression From 1 to 65, 535 bytes (excluding \0) Total length of group keys Number of characters returned when the rlen function is used in key specifications Number of items that can be returned - 1 to 2,000 bytes The total group key length is the total length of all the group keys in key specifications. Refer to Relationship between the Total Group Key Length and the Total Number of Items that Can be Returned for more information on how the total group key length affects the number of items that can be returned. 1 to 128 The length of the character string resulting from the rlen function is shown in the table entitled Relationship between character encoding and the length of the string resulting from the rlen function. 100 to 1,000 records When the total length of group keys is 200 bytes or less, the records corresponding to the top 1,000 groups can be returned. If the total length of group keys exceeds 200 bytes, the number of groups that can be returned is indicated in Relationship between the Total Group Key Length and the Total Number of Items that Can be Returned. Relationship between the Total Group Key Length and the Total Number of Items that Can be Returned The total group key length is the total length of all the group keys in key specifications. The length of each key is determined by the key specification format, as shown in the following table. Table E-7 Relationship between Total Group Key Length and the Number of Returnable Items Key specification format Length of group key Remarks val function 16 bytes - Text format 20 bytes The first 20 bytes are grouped as the key. To group using a string that is longer than 20 bytes, specify the rlen function as the key specification of the sort expression. By specifying the rlen function, it becomes possible to perform grouping using up to 128 characters as a key. E-5

272 Appendix E Allowable Values Key specification format rlen function Length of group key The length of the character string resulting from the rlen function is shown in the table entitled Relationship between character encoding and the length of the string resulting from the rlen function'. Remarks - The character encoding of the director data determines the byte length of each character of the character string produced by the rlen function, as shown below. Table E-8 Relationship between Character Encoding and the Length of the String Resulting from the rlen Function Character encoding No. of bytes per character Example UTF-8 4 bytes rlen(/root/name/text(),50) would be treated as 200 bytes. SHIFT-JIS GB2312 big5 KSC bytes rlen(/root/name/text(),50) would be treated as 100 bytes. EUC 3 bytes rlen(/root/name/text(),50) would be treated as 150 bytes. The following table shows how the total group key length affects the number of groups that Shunsaku can return. Table E-9 Group Key length and the Number of Groups that can be Returned by Shunsaku Group key length (bytes) Number of groups that can be returned 1 to 200 1, to to to to to 1, ,001 to 2, E-6

273 Appendix F Estimating Resources This appendix explains how to estimate the amount of resources required to search or update data using applications. Estimating Local Memory Requirements when Java APIs are Used Estimating Local Memory Requirements when C APIs are Used F-1

274 Appendix F Estimating Resources Estimating Local Memory Requirements when Java APIs are Used Use the following procedure to obtain an approximate estimate of the amount of memory used by the Shunsaku APIs when an application runs. The following table shows the formulas for estimating the memory requirements when Java APIs are used. Table F-1 List of Formulas for Estimating the Memory Requirements when Java APIs are Used Application usage Variable elements Looking up data - Maximum data length of a single XML or text format record to be obtained - Number of data items displayed on a single screen - Number of concurrent processes Updating data - Maximum data length of a single XML format record to be added - Number of data items added with a single executeinsert call - Number of concurrent processes Estimation formula (kilobytes) 2.1 x maximum data length of a single XML or text format record to be obtained (kilobytes) x number of data items displayed on a single screen x number of concurrent processes. (See the Note below.) 4.8 x maximum data length of a single XML format record to be added (kilobytes) x number of data items added with a single executeinsert call x number of concurrent processes Note This is the amount of memory used to execute a search and obtain results. If the ResultSet object is held after the search has completed, and then the next data lookup is executed, additional memory space is required (equal to the length of the data being held x the number of data items). F-2

275 Estimating Local Memory Requirements when Java APIs are Used An estimation example of the local memory requirements when Java APIs are used is as follows If the variable elements are as follows Maximum data length of a single XML or text format record to be obtained 1 KB Maximum data length of a single XML format record to be added 1 KB Number of data items displayed on a single screen 100 Number of data items added with a single executeinsert call 100 Number of concurrent processes 100 Searching data 2.1 x 1 x 100 x 100 = 21,000 KB (approx. 20 MB) Updating data 4.8 x 1 x 100 x 100 = 48,000 KB (approx. 50 MB) The Java APIs use only an area of memory called the "heap area" that is managed by the Java Virtual Machine. Change the size of the Java heap according to the calculation results of memory requirements. Refer to the following for details on how to change the heap size. How to Change the Heap Size The initial size of Java heap is set in advance (for J2SDK 1.3 or later, the initial size is 2 MB and the maximum size is 64 MB). The heap size can be changed by specifying Java command options. These options are explained in the following table. Table F-2 List of Options for the Java Command Item Option Explanation Initial size -Xms Specifies the initial size of the Java heap in bytes. The value specified must be a multiple of 1024, greater than 1 MB. To specify a value in kilobytes, add a "k" or "K" character. To specify a value in megabytes, add an "m" or "M" character. The default value is 2 MB. Maximum size -Xmx Specifies the maximum size of the Java heap in bytes. The value specified must be a multiple of 1024, greater than 2 MB. To specify a value in kilobytes, add a "k" or "K" character. To specify a value in megabytes, add an "m" or "M" character. The default value is 64 MB. An execution example for the Java command is shown below. Example To set the maximum size of the Java heap for the "AppClass" Java application to 128 MB Java Xmx128m AppClass F-3

276 Appendix F Estimating Resources Estimating Local Memory Requirements when C APIs are Used Use the following procedure to obtain an approximate estimate of the amount of memory used by the Shunsaku APIs when an application runs. The following table shows the formulas for estimating the memory requirements when C APIs are used. Table F-3 List of Memory Requirements when C APIs are Used Application usage Variable elements Estimation formula (kilobytes) Looking up data - Maximum data length of a single XML or text format record to be obtained - Number of data items displayed on a single screen - Number of concurrent processes Updating data - Maximum data length of a single XML format record to be added - Number of data items added with a single ShunInsert call - Number of concurrent processes Maximum data length of a single XML or text format record to be obtained (kilobytes) x number of data items displayed on a single screen x number of concurrent processes Maximum data length of a single XML format record to be added (kilobytes) x number of data items added with a single ShunInsert call x number of concurrent processes Example Calculation An estimation example of the local memory requirements when C APIs are used is as follows If the variable elements are as follows Maximum data length of a single XML or text format record to be obtained 1 KB Maximum data length of a single XML format record to be added 1 KB Number of data items displayed on a single screen 100 Number of data items added with a single ShunInsert call 100 Number of concurrent processes 100 F-4

277 Estimating Local Memory Requirements when C APIs are Used Looking up data 1 x 100 x 100 = 10,000 KB (approx. 10 MB) Updating data 1 x 100 x 100 = 10,000 KB (approx. 10 MB) Note Local memory allocated by applications is required in addition to the above. F-5

278 Appendix F Estimating Resources F-6

279 Appendix G Notes on XML Documents This appendix provides notes on the following for XML documents in Shunsaku The Format of XML Documents XML Document in Text Files Notes on the XML Format G-1

280 Appendix G Notes on XML Documents The Format of XML Documents XML documents stored in Shunsaku must be well-formed. A "well-formed XML document" is a document that meets the following standards based on the specification for XML documents. It is also possible to store XML documents that consist of only body text without preface sections (such as XML declarations and DTDs). There must be exactly one root element. There must be an end tag for each start tag. Tags must be nested correctly. Shunsaku regards the first string starting with "<" as the start tag for the root element, and regards XML documents as being everything between the start tag and the corresponding end tag. Any white space (such as blanks, tabs or linefeed characters) in the XML document are left unchanged. Figure G-1 Example XML Document In the example above, everything from the "<!-" comment through to the "</doc>" end tag for the root element is regarded as an XML document. Any comments after the end tag are not included in the XML document. Any linefeed characters after the end tag are not included in the XML document either. G-2