Using Java Wrapper for Natural

This document describes how to generate a client interface object, using Java Wrapper for Natural. It covers the following topics:

Prerequisites

To use Java Wrapper for Natural you need Software AG Designer with the NaturalONE and EntireX plug-ins installed.

Step 1: Start the Java Wrapper for Natural

To start the Java Wrapper for Natural, select a Natural subprogram (file extension .NSN) located in a library of a NaturalONE project, and from the context menu choose Generate Java Client.... Alternatively you can start the Java Wrapper for Natural from the context menu of the Natural source folder or any parent folder in the project, including the Natural library and the Project folder.

graphics/using_start.png

Step 2: Select the Natural Library (Optional)

If you have started the wizard from a folder containing multiple Natural libraries, the wizard displays a page showing all available libraries from which you can select one.

graphics/selectLib.png

Select the Natural library from the list and continue with Step 3: Select the Natural Subprograms.

Step 3: Select the Natural Subprograms

The following wizard page provides a list of available Natural subprograms.

graphics/selectNatSubprogs.png

In the Source pane, select at least one program from the list of Natural subprograms (CALLNATs). You can also choose Select All or Deselect All.

In the Extraction Settings pane, check Redesign the interfaces if you want to design the extracted interfaces to the Natural subprograms. The Next button will be enabled. See Step 4: Redesign the Interface for Natural Subprograms (Optional). If you do not check Redesign the interfaces, see Natural to IDL Mapping in the IDL Extractor for Natural documentation for default mappings.

Check Replace special characters in parameter names by underscore to substitute the special characters '$', '#', '&', '@', '/' by underscores. See also Extracting IDL Parameter Names.

Press Next to continue.

Step 4: Redesign the Interface for Natural Subprograms (Optional)

In this step, you can redesign the interface. This includes:

graphics/mapNat_subprog.png

Use this page for the following tasks:

  • Define the direction of parameters in the extracted interface. Choose Map to In, Map to Out or Map to InOut for each parameter on level 1.

  • Define which parameters redefined in the Natural PDA are part of the extracted interface. Choose Map to In, Map to Out or Map to InOut for the REDEFINE base parameter or any REDEFINE path.

  • Hide or suppress unneeded parameters in the extracted interface. Choose Suppress.

  • Set parameters to constants and hide or suppress them in the extracted interface. Choose Set Constant.

This page consists of the following main parts:

  • Top line
    The top line contains the current Natural subprogram and the IDL library name. The combo box can be used as quick navigation if more than one Natural subprogram is selected.

  • Middle
    The middle part contains a tab item for each interface ( IDL program) extracted from the Natural subprogram.

    Note:
    It is possible to extract more than one interface (IDL program) from a Natural subprogram. To create, rename and remove interfaces, use the toolbar on the right side of tab folder.

    Icon Function Description

    graphics/nat_redesignInterface_create.gif

    		 Create Creates a new interface (IDL program) based on the original parameters of the Natural subprogram.

    graphics/nat_redesignInterface_duplicate.gif

    		 Duplicate Creates a new interface (IDL program) based on the current interface (active tab). All modifications of the current interface are copied.

    graphics/nat_redesignInterface_rename.gif

    		 Rename Change the name of the current interface (active tab). The name must be unique.

    graphics/nat_redesignInterface_remove.gif

    		 Remove Removes the current interface (active tab). At least one interface must exist.

    graphics/nat_redesignInterface_expandAll.gif

    		 Expand All Expands the Natural and IDL tree.

    graphics/nat_redesignInterface_collapseAll.gif

    		 Collapse All Collapse the Natural and IDL tree.

  • Middle left
    Input pane. The parameters of the Natural subprogram to extract from. For each Natural subprogram parameter you can choose one of the operations Map to In, Map to Out, Map to InOut, Suppress and Set Constant. Additionally for REDEFINEs, a quick fix is available (icons on the left side of the pane) to choose which parameters redefined in the Natural PDA are part of the extracted interface.

    Notes:

    1. The mapping operations Map to In, Map to Out, Map to InOut, Suppress and Set Constant are also available in the context menu of the Natural parameter tree.
    2. Natural parameters that are suppressed or set to constant in the interface are rendered in italic type. For example, in the screen above, FUNCTION (A3) is set to constant; FILLER1(A4) and FILLER2(A60) are suppressed; FUNCTION-DATA(A161) and its first REDEFINE path are implicitly suppressed because the second REDEFINE path with prefix MOD-DATA-2-R2 is selected.
    3. The value for Natural parameters set to constant are displayed behind the parameter in the Natural parameter tree (e.g. in the screen above, FUNCTION (A3) [MOD]).
    4. Natural parameters mapped in the interface are displayed with a green tick (graphics/cw_decorator.png).

  • Middle right
    Output pane. The extracted interface (IDL).

  • Bottom
    Reference. The Natural subprogram source and its PDA sources, each displayed in a separate tab.

Tips:

  • The panes can be resized.

  • To enlarge parameter lists, use the vertical bars on the side.

  • You can close the bottom pane if it is not needed by clicking on the triangle next to Natural Subprogram Source. In this way, you have more space for viewing the upper panes.

Use the quick navigation or choose Next to continue. If multiple Natural subprograms have been selected in the Natural subprogram selection step, redesign the next interface. The amount of subprograms extracted so far is indicated by the fraction next to the title (current/total).

If multiple Natural subprograms have been selected in the Natural subprogram selection step, redesign the next interface. The amount of subprograms extracted so far is indicated by the fraction next to the title (current/total).

If only one Natural subprogram has been selected or no further one has to be redesigned, continue with Step 5: Configure the Class to be Generated.

Step 5: Configure the Class to be Generated

The next wizard page asks for the name of the target folder of the generated Java classes, and for a Java package name. By default, the Java sources are generated into a folder Java/src. If this does not already exist, it will be created.

graphics/configClass.png

Generation Result

The Java interface object is generated and placed into the target folder.

graphics/result.png

For more information see the NaturalONE documentation.

Preferences

Use the preference page for the IDL Extractor for Natural to manage the default values relevant for Step 3: Select the Natural Subprograms. See Preferences under Using the Software AG IDL Extractor for Natural.