Examples for Redesigning the Extracted Interfaces

This document provides the following examples on how to redesign the extracted interface:


Set Constant

This example turns the CALC server into an ADD server. The CALC server used here can be found in Basic RPC Server Examples - CALC, SQUARE.

****************************************************************
*
*  CALC RPC Server Example for Natural
*
****************************************************************
DEFINE DATA
PARAMETER
  1 #OPERATION        (A1)
  1 #OPERAND1         (I4)
  1 #OPERAND2         (I4)
  1 #FUNCTION-RESULT  (I4)
LOCAL
  1 #TMP              (I4)
END-DEFINE
*
MOVE 0 TO #FUNCTION-RESULT
DECIDE ON FIRST VALUE OF #OPERATION
  VALUE '+'
    COMPUTE #FUNCTION-RESULT = #OPERAND1 + #OPERAND2
  VALUE '-'
    COMPUTE #FUNCTION-RESULT = #OPERAND1 - #OPERAND2
  VALUE '*'
    COMPUTE #FUNCTION-RESULT = #OPERAND1 * #OPERAND2
  VALUE '/'
    IF #OPERAND2 NE 0 THEN
      COMPUTE #FUNCTION-RESULT = #OPERAND1 / #OPERAND2
    END-IF
  VALUE '%'
    IF #OPERAND2 NE 0 THEN
      DIVIDE    #OPERAND2 INTO #OPERAND1 GIVING #TMP
      REMAINDER #FUNCTION-RESULT
    END-IF
  NONE VALUE
    IGNORE
END-DECIDE
END

Extraction without a redesign leads to an interface (IDL program) in which extracted parameters and Natural subprogram parameters are identical:

Library 'EXAMPLE' Is
   Program 'CALC' Is
      Define Data Parameter
         1 Operation        (A1) In
         1 Operand1         (I4) In
         1 Operand2         (I4) In
         1 Function_Result  (I4) Out
      End-Define

Calling such an interface with an RPC client means providing the ADD function as a value on the operation parameter in the same way legacy callers do.

After the redesign, the IDL looks as follows:

Library 'EXAMPLE' Is
   Program 'ADD' Is
      Define Data Parameter
         1 Operand1         (I4) In
         1 Operand2         (I4) In
         1 Function_Result  (I4) Out
      End-Define

This process is called "Redesigning the interface", which can be seen as manual step in the overall extraction process. See Step 6: Redesign the Interface for Natural Subprograms (Optional).

Setting parameters to constant values and suppressing them in the IDL is often done together with multiple interfaces, where the function code or operation-code field has to be set to a constant. See Extracting Multiple Interfaces for a more advanced example.

Start of instruction setTo redesign the interface and to set a constant for the parameter operation

  1. Make sure to check Redesign the interfaces in Step 5: Select Natural Subprograms from RPC Environment.

  2. In Step 6: Redesign the Interface for Natural Subprograms (Optional), proceed as follows:

    Design interface for ADD Server

    • Choose Set Constant for parameter Operation and enter "+" as value.

    • Choose Rename from the toolbar and change the name to "ADD".

Extracting Multiple Interfaces

Multiple functions are often implemented in a single Natural subprogram, for example in Set Constant. The CALC server implements the functions ADD, SUBTRACT, MULTIPLY, DIVIDE and MODULO in one source.

Extraction without a redesign leads to an interface (IDL program) in which extracted parameters and Natural subprogram parameters are identical:

Library 'EXAMPLE' Is
   Program 'CALC' Is
      Define Data Parameter
         1 Operation        (A1) In
         1 Operand1         (I4) In
         1 Operand2         (I4) In
         1 Function_Result  (I4) Out
      End-Define

Calling such an interface with an RPC client means providing the function (ADD, SUBTRACT, MULTIPLY, DIVIDE or MODULO) as a value on the operation parameter in the same way legacy callers do.

The interface above would

  • result in a class with a single method if it was wrapped with an object-oriented wrapper (Java Wrapper, .NET Wrapper, DCOM Wrapper).

  • offer CALC as only operation if it was used as web service.

A modern design of the same interface would provide more specialized interfaces. Each interface may have fewer parameters compared to the original Natural subprogram. Parameters that are obsolete for a function are not offered in the corresponding interface, for example the parameter Operation in our example. This keeps the interface lean and clear and makes it easier to use from the perspective of an RPC client.

This process is called "Redesigning the interface", which can be seen as manual step in the overall extraction process. See Step 6: Redesign the Interface for Natural Subprograms (Optional).

After the redesign, the IDL looks as follows:

Library 'EXAMPLE' Is
   Program 'ADD' Is
      Define Data Parameter
         1 Operand1         (I4) In
         1 Operand2         (I4) In
         1 Function_Result  (I4) Out
      End-Define
   Program 'SUBTRACT'
      Define Data Parameter
         1 Operand1         (I4) In
         1 Operand2         (I4) In
         1 Function_Result  (I4) Out
      End-Define
   Program 'MULTIPLY'
      Define Data Parameter
         1 Operand1         (I4) In
         1 Operand2         (I4) In
         1 Function_Result  (I4) Out
      End-Define
   Program 'DIVIDE'
      Define Data Parameter
         1 Operand1         (I4) In
         1 Operand2         (I4) In
         1 Function_Result  (I4) Out
      End-Define
   Program 'MODULO'
      Define Data Parameter
         1 Operand1         (I4) In
         1 Operand2         (I4) In
         1 Function_Result  (I4) Out
      End-Define

By redesigning the interface you can turn the legacy interface of the CALC server into a more modern, object-oriented interface. In case the redesigned interface above is wrapped

  • with an object-oriented wrapper (Java Wrapper, .NET Wrapper, DCOM Wrapper), this results in a class with five methods - ADD, SUBTRACT, MULTIPLY, DIVDE and MODULO, a real class/method design.

  • as web service, also five operations are offered.

Start of instruction setTo Redesign the interface and extract multiple interfaces

  1. Make sure to check Redesign the interfaces in Step 5: Select Natural Subprograms from RPC Environment in the extractor wizard (see Extracting Software AG IDL File from an Existing Natural RPC Environment).

  2. In Step 6: Redesign the Interface for Natural Subprograms (Optional), proceed as follows:

    • Design interface for ADD
      • Choose Set Constant for parameter Operation and enter '+' as value.

      • Choose Rename from the toolbar and change the name to ADD

    • Design interface for SUBTRACT
      • Choose Set Constant for parameter Operation and enter '-' as value.

      • Choose Rename from the toolbar and change the name to SUBTRACT

    • To design MULTIPLY, DIVIDE or MODULO, proceed as for SUBTRACT
      • Enter '*' as value for Operation and rename it to MULTIPLY.

      • Enter '/' as value for Operation and rename it to DIVIDE.

      • Enter '%' as value for Operation and rename it to MODULO.

Extracting Natural REDEFINES

REDEFINEs are often used in Natural. The example below illustrates a simple redefinition where the parameter #BASE-FIELD is redefined by the fields FILLER-1 thru R-P3-01.

DEFINE DATA PARAMETER
1 #BASE-FIELD            (A161) /* first parameter
1 REDEFINE #BASE-FIELD		  /* second parameter
  2 FILLER-1             (A4)
  2 FILLER-2             (A60)
  2 R-P1-01              (A1)
  2 R-P2-01              (A10)
  2 R-P3-01              (I4)
END-DEFINE

You can select a single REDEFINE path of the same base field for one interface only. If you require more than one REDEFINE path of the same base field, extract multiple interfaces - for each REDEFINE path a separate interface, see Extracting Multiple Interfaces.

Start of instruction setTo redesign the interface and extract a REDEFINE path

  • Choose Map to In, Map to Out or Map to InOut either for

    • the REDEFINE base parameter, here parameter #BASE-FIELD (A161) /* first parameter, or

    • any REDEFINE path, here REDEFINE#BASE-FIELD /* second parameter

Extracting a Natural Server with User-defined Mapping

Imagine an existing Natural server called EMPLOYEE. It implements the access logic for a LIST and DETAILS function to a database view EMPLOYEE. Its parameter data area is shown below:

DEFINE DATA PARAMETER
1 OPERATION        (A1)    /* 'L' => List; 'D' => Details
1 ID               (A10)   /* Input
1 EMPLOYEE                 /* Output
  2 FIRSTNAME      (A20)   /* First name
  2 SURNAME        (A20)   /* Surname
  2 DATE-BIRTH     (D)     /* Date of birth
  2 DETAILS        (A100)
  2 REDEFINE DETAILS
    3 ANNUAL-SALARY(P9)    /* Annual salary
    3 VACATION     (N2)    /* Vacation days per year
    3 LANGUAGE     (A3)    /* Language
1 EMPLOYEES        (1:*)   /* Out
  2 IDENT          (A10)   /* Identification number
  2 FIRSTNAME      (A20)   /* First name
  2 SURNAME        (A20)   /* Surname
  2 DATE-BIRTH     (D)     /* Date of birth             
END-DEFINE

EntireX allows you to extract all implemented interfaces of the Natural server separately. Instead of a large EMPLOYEE interface, separate interfaces getListOfEmployees and getDetailsOfEmployee are extracted. Each interface contains required parameters; obsolete parameters for an interface are suppressed, improving its usability.

Start of instruction setTo extract a Natural server with a user-defined mapping

  1. Call the IDL Extractor for Natural, select the Natural server EMPLOYEE, check Redesign the interfaces and press Next.

    graphics/natExtractor_examples_userMap-1.png

  2. Model the extracted interface to suit your needs by creating a function getListOfEmployees.

    1. Mark the parameter OPERATION in the Natural Subprogram Source view or the Natural Parameters pane

    2. Set Constant 'L' for the parameter OPERATION.

    In the Natural Parameters pane, constant [L] is shown in brackets after the Natural parameter. OPERATION is removed from the IDL Parameters pane.

    At runtime, EntireX passes L as the value for the OPERATION parameter. This forces the EMPLOYEE LIST function to be executed.

    graphics/natExtractor_examples_userMap-2.png

  3. Suppress the Natural group EMPLOYEE, which is unused in the LIST function. This removes the IDL group EMPLOYEE from the IDL Parameters pane. The Natural parameter EMPLOYEE remains. Parameters that are suppressed in the IDL Parameters pane are displayed in italic font in the Natural Parameters pane.

    graphics/natExtractor_examples_userMap-3.png

    Note:
    Parameters set to constant are also displayed in italic font, because Set Constant suppresses them in the IDL Parameters pane too (see Step 2).

  4. Also suppress Natural parameter ID, similar as already done for Natural group EMPLOYEE in the previous step.

  5. Specify a readable name getListOfEmployees for the IDL Parameters, using the toolbar button graphics/icon_rename.png. The new name appears on the tab.

    graphics/natExtractor_examples_userMap-4.png

  6. Create a getDetailsOfEmployees function for the DETAILS operation. A new interface is needed for this. Use the toolbar button graphics/icon_add.png and open a new tab. The IDL parameters are reset to defaults. The previously extracted getListOfEmployees interface still exists in the first tab. Once you reactivate the first tab, you will see the interface of getListOfEmployees again.

    graphics/natExtractor_examples_userMap-5.png

  7. Specify a readable name getDetailsOfEmployee for the IDL Parameters, using the toolbar button graphics/icon_rename.png. The name is displayed on the tab.

    graphics/natExtractor_examples_userMap-6.png

  8. Set constant 'D' for Natural parameter OPERATION to execute the EMPLOYEE DETAILS operation at runtime. The IDL parameter OPERATION is removed from the IDL Parameters pane and displayed in the Natural Parameters pane. The italic font indicates suppression.

    graphics/natExtractor_examples_userMap-7.png

  9. Suppress the Natural X-array EMPLOYEES, which is not needed in the DETAILS interface. The IDL parameter EMPLOYEES is removed from the IDL Parameters pane and displayed in italic font in the Natural Parameters pane.

    graphics/natExtractor_examples_userMap-8.png

  10. By default, the Natural parameter DETAILS is mapped. In this case, the redefinition of DETAILS in the Natural Subprogram Source pane contains information of more value.

    graphics/natExtractor_examples_userMap-9.png

  11. You can map the redefinition of DETAILS in the Natural Subprogram pane if you prefer to use this rather than the DETAILS parameter. Select REDEFINE DETAILS in the Natural Subprogram pane and press Map to Out. The IDL parameter DETAILS is turned into a group containing parameters that match the Natural redefinition.

    graphics/natExtractor_examples_userMap-10.png

  12. Press Finish to retrieve the extraction result in the form of a Software AG IDL file. At the same time, a Server Mapping Files for Natural (Designer file with extension .cvm) is created. The Software AG IDL File describes the interfaces from the RPC client view, while the server mapping file contains the mapping to the real Natural server. Both of these files must be kept together and in sync, otherwise a call to the Natural server may fail.

    graphics/natExtractor_examples_userMap-11.png

    To summarize: We created two IDL interfaces. In the IDL file, these resulted in two IDL programs: getListOfEmployees and getDetailsOfEmployee. Both IDL programs were given readable names (Steps 4 and 6). Meaningful fields were kept, while superfluous fields were suppressed (Steps 3 and 8). The program getDetailsOfEmployee contains the redefined fields of parameter DETAILS (see below) mapped during extraction (step 9).

    Note:
    At runtime the RPC client generated with the extracted interface will send data for the redesigned interfaces, while your Natural server still expects EMPLOYEE data. The EntireX runtime transforms the incoming data stream from the RPC client, using the server mapping file.

    graphics/natExtractor_examples_userMap-12.png