Version 9.6
 —  Software AG IDL Extractor for Natural  —

Using the Software AG IDL Extractor for Natural

This document describes how to use the Software AG IDL Extractor for Natural. It covers the following topics:


Extracting IDL from Natural Subprogram Sources in NaturalONE

In a NaturalONE project in Software AG Designer, IDL can be extracted directly from Natural subprogram sources (CALLNATs), using the following steps:

Step 1: Start the IDL Extractor for Natural Wizard

There are various ways of starting the IDL Extractor for Natural Wizard:

Select a NaturalONE Project

To extract the IDL, select the NaturalONE project in the Software AG Designer.

graphics/natOne_selectProject.png

From the context menu, choose Extract IDL... and continue with Step 2: Select the Natural Library from NaturalONE Project (Optional).

Select a Natural Library in a NaturalONE Project

To extract the IDL, select the NaturalONE project in the Software AG Designer.

graphics/natOne_selectNatLibInProject.png

From the context menu, choose Extract IDL... and continue with Step 3: Select the Natural Subprograms from NaturalONE Project.

Select Natural Subprograms in a NaturalONE Project

To extract the IDL, select one or multiple Natural subprogram sources (.NSN) in the Software AG Designer.

graphics/natOne_selectNatSubprogInProject.png

From the context menu, choose Extract IDL... and continue with Step 3: Select the Natural Subprograms from NaturalONE Project.

Alternatively, you can start the IDL Extractor 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.

Step 2: Select the Natural Library from NaturalONE Project (Optional)

graphics/natOne_selectNatLib.png

Select the Natural library from the list and choose Next to continue with Step 3: Select the Natural Subprograms from NaturalONE Project.

Step 3: Select the Natural Subprograms from NaturalONE Project

graphics/natOne_selectNatSources.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 Setting pane, check Redesign the interfaces if you want to design the extracted interfaces to the Natural subprograms. The Next button will be enabled. See Redesigning the Extracted Interface. If you do not check Redesign the interfaces, see Natural to IDL Mapping for default mappings.

By checking Replace special characters in parameter names with underscore under Extraction Setting, the special characters ("$", "#", "&", "@", "/") allowed in Natural parameters can be replaced by underscores, see also Extracting IDL Parameter Names.

In the Target pane, select the container where the IDL file will be stored. Enter the file name of the new IDL file. If the IDL file exists, it will be overwritten. Preserving the Software AG IDL File and optional CVM file allows you to customize the IDL (alias names, in/out/inout modifiers) for subsequent optimized client generation steps. See CVM File.

Choose Next to redesign the interfaces. See Step 6: Redesign the Interface for Natural Subprograms (Optional). To enable the Next button, check Redesign the interfaces.

Choose Finish to start extraction with a default mapping. For more information see Extraction Result.

Top of page

Extracting Software AG IDL File from a New Natural RPC Environment

This section covers the following topics:

Step 1: Start the IDL Extractor for Natural Wizard

graphics/using-common_start.png

Press Next and continue with Step 3: Edit RPC Environment.

Step 2: Create a New RPC Environment

If no RPC environments are defined, you only have the option to Create a New RPC Environment. The RPC environments are managed in the Preferences.

graphics/nat_createNewEnv.png

Choose Create a new RPC Environment and press Next to create a new RPC environment. Continue with Step 3: Edit RPC Environment.

Note:
The folder File and the RPC environment localhost@NATSRV2800 (default RPC server for NaturalONE) are available only if NaturalONE plugins are installed.

Step 3: Edit RPC Environment

graphics/nat_editEnv.png

Define the new RPC environment on this page. Required fields are Broker ID, Server Address and the Environment Name. The timeout value must be in the range 1-9999 seconds (default: 60).

The EntireX Authentication fields apply to the broker.

The RPC Server Authentication fields apply to the RPC server. If the Natural RPC Server operates under Natural Security,

Note:
Users who do not have access rights to the Natural system library SYSIDL are not allowed to extract IDL from your Natural environment.

With Extractor Settings, specify the Natural library and program name from which you want to extract. You have the following options to select a range of Natural libraries and programs:

Any Natural RPC Server can be used. Only Natural libraries that reside in the FUSER system file of the Natural RPC Server can be accessed. Special configuration is required only for operating system IBM i; see Natural RPC Server Configuration for the IDL Extractor for Natural.

Press Next to continue.

Step 4: Select Natural Library from RPC Environment (Optional)

All Natural libraries that reside in the FUSER system file of the Natural RPC Server and that match the specification in the Extractor Settings are listed here. See Step 3: Edit RPC Environment. This step is skipped if exactly one Natural library matches the specification. In this case continue with Step 5: Select Natural Subprograms from RPC Environment.

graphics/nat_selectLib.png

Only Natural libraries from the Natural User System file (FUSER) are displayed. If the Natural RPC server operates under Natural Security, Natural libraries are displayed only if you are allowed to access the library. This means that if a library is people-protected and you do not have access rights, it is not displayed. See also RPC Server Authentication under Step 3: Edit RPC Environment.

Select the Natural library from the list and choose Next to continue with Step 5: Select Natural Subprograms from RPC Environment.

Step 5: Select Natural Subprograms from RPC Environment

All Natural subprograms that match the specification in the Extractor Settings are listed here. See Step 3: Edit RPC Environment.

graphics/nat_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, specify whether the IDL is to be extracted from Natural subprogram sources or compiled objects. The following restrictions apply:

Check Redesign the interfaces if you want to design the extracted interfaces to the Natural subprograms. The Next button will be enabled. See Redesigning the Extracted Interface. If you do not check Redesign the interfaces, refer to Natural to IDL Mapping for default mappings.

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

Choose Next to continue. If multiple Natural subprograms have been selected in the Natural subprogram selection step, redesign the next interface. You can see the current and total number of the subprogram you are extracting from in the title (n/m).

Choose Finish to extract the interface. For further subprograms that have been selected, a default mapping is created, see Extraction Result.

Step 6: 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:

This page consists of the following main parts:

Tips:

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).

Choose Next to continue. If multiple Natural subprograms have been selected in the Natural subprogram selection step, redesign the next interface. You can see the current and total number of the subprogram you are extracting from in the title (n/m).

Choose Finish to extract the interface. For further subprograms that have been selected, a default mapping is created, see Extraction Result.

Top of page

Extracting Software AG IDL File from an Existing Natural RPC Environment

Step 1: Start the IDL Extractor for Natural Wizard

graphics/using-common_start.png

Choose Next and continue with Step 6: Redesign the Interface for Natural Subprograms (Optional).

Step 2: Select an RPC Environment

If RPC environments are defined, you can select an existing one. RPC environments are managed in the Preferences.

graphics/nat_selectRpcEnv.png

Select Use existing RPC environment and select the appropriate RPC environment from the list below.

If Modify the selected RPC environment is checked, the selected RPC environment can be modified before extraction starts.

Press Next to continue.

Note:
The folder File and the RPC environment localhost@NATSRV2800 (default RPC server for NaturalONE) are available only if NaturalONE plugins are installed.

Top of page

Extraction Result

When the wizzard has finished successfully, you can see two additional files in your Eclipse project:

For more information on how Natural programs are extracted, refer to Natural to IDL Mapping.

Top of page

Preferences

Use the preference page for IDL Extractor for Natural to manage the default values for the IDL Extractor for Natural wizard.

graphics/preferences.png

The option IDL Extraction from Source or from Object determines from which code type the IDL file is to be extracted.

With the check box Replace special characters in parameter names with underscore, the special characters ("$", "#", "&", "@" , "/") allowed in Natural parameters can be replaced by underscores. See also Rules for Coding Group and Parameter Names.

For more information on object and source extraction and character replacing, see Step 5: Select Natural Subprograms from RPC Environment.

RPC environments are managed with the RPC Environment Manager.

Top of page