Example using Page Service

The following excerpt of the CIPBSTMP.xml file will motivate the discussion.

<?xml version="1.0"?>
<!-- Service CIPBSTMP -->

<page service="CILBSTMP">

The root element of the document has the tag "page" to reflect that this is a page service, and describes the service name as an attribute.

   <pageHeader>
      <string name="STM_ID" size="12"/>
   </pageHeader>

The <page> element contains exactly one <pageHeader> and one <pageBody>. The <pageHeader> contains any number of "singleton" fields. This one is a string field named "STM_​ID" in the browser, and with the same name in the original Java source. The field contains up to 12 characters (this is the "business rule" length, not physical storage).

Other types of singleton fields include <bigInteger>, <bigDecimal>, <money>, <date>, <time>, <dateTime>, and <boolean>.

The number-related fields (<bigInteger>, <bigDecimal>, and <money>) have a "precision" attribute, which describes the maximum number of digits that can be represented. Further, <bigDecimal> and <money> include the "scale" attribute, describing the number of decimal digits appearing after the decimal point. Thus, an element like this <bigDecimal precision="4" scale="2"/> can represent numbers in the range +/-99.99.

Continuing with the page service example, we have this section:

<pageBody>
  <row actionFlag="ROW_ACTION_FLG">
     <string name="BATCH_CD"
             size="8"/>
     <bigInteger name="BATCH_NBR"
                 precision="10"/>

The <pageBody> element contains <row> elements, singleton fields, and <list> elements, in any order. Here we have another <string> field, as well as a <bigInteger> (an integer value with no decimal fraction), this one holding (up to) 10 digits. This means numbers in the range +/-9,999,999,999 can be represented.

The <row> element reflect the java entity (row). In terms of the infoset and browser the fields in the <row> element are effectively merged into the containing <pageBody>, along with fields from any sibling <row> elements.

The "actionFlag" attribute names the field that contains a flag that determines the server action that should occur against the row.

     <string name="STM_CNST_ID"
             size="10"/>
     <date name="STM_DT" />
     <string name="STM_ID"
             size="12"
             isPK="true"/>
     <string name="STM_STAT_FLG"
             size="2"/>
     <bigInteger name="VERSION"
              precision="5"/>
  </row>

The "isPK" attribute marks fields that are part of the logical prime key of the "main" object/table for this page service.

We then see a <list> element:

      <list name="STM_DTL" size="30" service="CILBSTDL" userGetMore="false">

The <list> element describes an elaborately structured array of objects. The element contains exactly one <listHeader> and <listBody>. Every list within a service buffer has a unique name attribute. The number of possible list body objects is given by the "size" attribute. In the event a list service exists independently for the list, it is named by the "service" attribute. Finally the "userGetMore" attribute switches the system into one of two modes:

userGetMore="false" means the system does not require the consent of the user in order to fetch more elements, in the event that the physical list buffer is filled to capacity with more elements available in the database. The system will autonomously call the corresponding list service (if it exists) in order to fetch the missing elements. In this way clients making one logical page service call may result in one physical page and several list service invocations.

userGetMore="true" means the system requires the affirmative consent of the user (e.g. via a "get more" button in the browser) to continue fetching available data. The list buffer is truncated.

<listHeader lastIndex="STM_DTL_COLL_CNT"
            actionFlag="LIST_ACTION_FLG"
            moreRows="MORE_ROWS_SW"
            alertRowIndex="ALERT_ROW">
     <string name="STM_ID"
        size="12"/>
     <string name="LAST_STM_DTL_ID"
        size="12"/>
</listHeader>

The <listHeader> element has a "lastIndex" attribute giving the field name that holds the number of elements actually returned, an "actionFlag" describing the operation to be performed on the list (e.g. change, delete), the "moreRows" attribute naming the field that holds the boolean that indicates whether more data remains un-retrieved in the database for the current list, and the "alertRowIndex" attribute, naming the field that holds an index into the list to describe the location of a validation error, used to select the correct item in a browser when presenting the error to the user.

In addition, a <listHeader> can contain any number of singleton fields. These are typically keys describing how to access this list, and logical "cursor" fields describing how to continue fetching more items.

  <listBody>
    <row actionFlag="ROW_ACTION_FLG2">
      <bigInteger name="VERSION"
                  precision="5"/>
      <string name="STM_DTL_ID"
              size="12"
              isPK="true"/>
      <string name="STM_CNST_DTL_ID"
              size="10"/>
      <string name="STM_ID"
              size="12"/>
    </row>
    <string name="STM_CNST_DTL_DESCR"
            size="50"/>
  </listBody>
</list>

This finishes the <list> element. Some more singleton elements appear before finishing the <pageBody> and <page>:

      <string name="STM_CNST_DESCR"
              size="50"/>
      <boolean name="ACTION_GENERATE_SW" />
   </pageBody>
</page>