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.
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.
To redesign the interface and extract a REDEFINE path
Choose , or either for
the 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).
Also suppress Natural parameter ID, similar as already done for Natural group EMPLOYEE in the previous step.
Specify a readable name getListOfEmployees for the IDL Parameters,
using the toolbar button 
.
The new name appears on the tab.
Create a getDetailsOfEmployees 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 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.
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.
