Interstage Shunsaku Data Manager Application Development Guide - Microsoft(R) Windows(R) 2000/ Microsoft(R) Windows Server(TM) 2003 - - UNIX -

B.4.2 Example Return Expressions when not Aggregating

Some example return expressions are shown below.

Document

<doc>
  <companyname>fujitsu</companyname>
  <employee position="manager">
    <name>smith</name>
    <id>2000</id>
    <age>30</age>
  </employee>
</doc>

The examples of the return specification formats are shown below.

• Return Specification in XML Format
• Text Format Return Specification

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

/

Result: The Entire Record is Returned

<doc>
  <companyname>fujitsu</companyname>
  <employee position="manager">
    <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 position="manager"><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>

• If the return expression includes a path expression, all return items must include a path expression. Return items cannot coexist with text expressions or attribute 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

Result

<doc><name>thompson</name><name>smith</name></doc>

Text Format Return Specification

If a text expression, attribute expression or a single-line function specification is specified in the return item, the results of the text expression, attribute 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 will be returned as a two dimensional array for each return item. The number of elements in the upper array is equal to the number of return expressions. The number of elements in the lower array is equal to the number of data items in a single document that apply to the specified return expression.
• .NET APIs
  • Extracting the Search Results Obtained by the Data Properties or the getStream Method
    • The values returned by each return item are separated by 0x0001 of the hexadecimal number
    • If the specified element occurs more than once in the same document, each occurrence will be separated by 0x0002 of the hexadecimal number.
  • Extracting the Search Results Obtained by the getDividedData Method
    • Results will be returned as a jagged string array for each return item. The number of elements in the upper array is equal to the number of return expressions. The number of elements in the lower 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 .NET APIs

smith

For C APIs

smith \1

Example 2: Example return item that attribute expression is specified

Return Expression

/doc/employee/@position

Result

For Java APIs

manager

For .NET APIs

manager

For C APIs

manager \1

Example 3: Example return item that contains a mixture of text expression, single-line function specification, and attribute expression

Return Expression

/doc/employee/name/text(),val(/doc/employee/age/text()),/doc/employee/@position

Result

For Java APIs

smith,30,manager

For .NET APIs

smith \1 30 \1 manager

For C APIs

smith \1 30 \1 manager \1

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 Java APIs

fujitsu,smith|jones,30

For .NET APIs

fujitsu \1 smith \2 jones \1 30

For C APIs

fujitsu \1 smith \2 jones \1 30 \1