Rational Developer for System z, Version 7.6

Using source annotations to specify service interface

This topic describes how Enterprise Service Tools users can annotate data definitions to provide service interface information and customization.
This describes how users of the Enterprise Service Tools can annotate COBOL data definitions to provide service interface information and customization similar to information and customization in the Batch Processor options files. This function is available to the Batch Processor tools for the "bottom-up" scenario of developing new service interfaces from COBOL applications utilizing Compiled XML conversion.
Note: This capability is available through the Batch processor configuration files only and only for COBOL sources.

More specifically, the annotations function provides the capability currently provided by ItemExclusionArray, ItemSelectionArray, and XMLNameArray elements of the batch processor options files, they allow the user to explicitly exclude (ItemExclusionArray), include (ItemSelectionArray) and rename (XMLNameArray) the desired items in the generated service interface.

Using the example in Figure 1. The service creator may want to exclude the "salary" item and rename the "first-name" to "FirstName" in the service reply. In order to achieve this using the batch processor option files (ItemExclusionArray, ItemSelectionArray, and XMLNameArray elements) , the service creator needs to input the fragment shown in Figure 2 in the ServiceSpecification.xml.
Figure 1. Example of COBOL Data Structure for Excluding and Changing Information
LINKAGE SECTION.
1 department.
 2 member-count  pic 9(9) binary.
 2 member-details occurs 5 times.
   3 first-name           pic x(35).
   3 last-name            pic x(45).
   3 contact-phone        pic x(25).
   3 contact-address      pic x(75).
   3 promotion-level      pic x(20).
   3 last-promotion-date  pic x(10).
   3 salary               pic x(3).
Figure 2. Example of Excluding and Changing Information with Option File Elements
  <OutputMessage importFile="samp.cpy" importDirectory="C:/Source" nativeTypeName="department">
        <ItemExclusionArray>
          <ExcludeItem itemName="department.member-details.salary"/>
        </ItemExclusionArray>
        <XMLNameArray>
          <XMLNameSelection itemName="first-name" XmlName="FirstName"/>
        </XMLNameArray>
  </OutputMessage>

Annotating the data structure source allows the users to specify similar type of information directly in the source of the data declaration rather than in an Batch processor option configuration file. This method keeps the service interface specification and the actual interface in a single source file.

Using the example in Figure 1 as a reference, the user can obtain the same results by including the sample annotations in the source file with the data description, as shown in Figure 3.
Figure 3. Example of COBOL Data Structure with Source Annotation Information
   @ANN  *OMIT salary
   @ANN  *OLDNAME first-name
   @ANN  *NEWAME FirstName


        LINKAGE SECTION.
        1 department.
         2 member-count  pic 9(9) binary.
         2 member-details occurs 5 times.
           3 first-name           pic x(35).
           3 last-name            pic x(45).
           3 contact-phone        pic x(25).
           3 contact-address      pic x(75).
           3 promotion-level      pic x(20).
           3 last-promotion-date  pic x(10).
           3 salary               pic x(3).
Note: The annotations @ANN *OMIT, @ANN *OLDNAME and @ANN *NEWNAME are samples, both the annotation indicator (@ANN) and annotation actions (OMIT, OLDNAME, and NEWNAME) are examples for this description. The annotation indicator and annotation action can be customized to support local/individual requirements.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)