This document provides the following examples on how to redesign the extracted interface:
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.
To redesign the interface and to set a constant for the parameter operation
Make sure to check Redesign the interfaces in Step 5: Select Natural Subprograms from RPC Environment.
In Step 6: Redesign the Interface for Natural Subprograms (Optional), proceed as follows:
Choose
for parameter Operation and enter "+" as value.Choose
from the toolbar and change the name to "ADD".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.
To Redesign the interface and extract multiple interfaces
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).
In Step 6: Redesign the Interface for Natural Subprograms (Optional), proceed as follows:
Choose Set Constant for parameter Operation and enter '+' as value.
Choose Rename from the toolbar and change
the name to ADD
Choose Set Constant for parameter Operation and enter '-' as value.
Choose Rename from the toolbar and change the name to 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
.
REDEFINE
s 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.
To redesign the interface and extract a REDEFINE
path
Choose
, or either forthe REDEFINE
base parameter, here parameter
#BASE-FIELD (A161) /* first parameter
, or
any REDEFINE
path, here
REDEFINE#BASE-FIELD /* second parameter
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.
To extract a Natural server with a user-defined mapping
EMPLOYEE
, check Redesign the interfaces and press .
Model the extracted interface to suit your needs by creating a function getListOfEmployees
.
Mark the parameter OPERATION
in the Natural Subprogram Source view or the Natural Parameters pane
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.
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.
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).
Specify a readable name getListOfEmployees
for the IDL Parameters,
using the toolbar button .
The new name appears on the tab.
Create a getListOfEmployees
function for the DETAILS
operation.
A new interface is needed for this. Use the toolbar button 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.
Specify a readable name getDetailsOfEmployee
for the IDL Parameters,
using the toolbar button . The name is displayed on the tab.
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.
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.
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.
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 .
The IDL parameter DETAILS
is turned into a group containing parameters that match the Natural redefinition.
Press Server Mapping Files for Natural (Workbench 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.
to retrieve the extraction result in the form of a Software AG IDL file. At the same time, aTo 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:
The Natural server and the redesigned interfaces no longer match. 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.