Version 9.6
 —  EntireX Natural Wrapper  —

Using the Natural Wrapper


Starting the Natural Wrapper

Start the Natural Wrapper from the context menu of an IDL file: Generate Natural from Software AG IDL.

graphics/using_start.png

Top of page

Using the Natural Wrapper for the Client Side

Using the Natural Wrapper for the Client Side within NaturalONE

Step 1: Specify the RPC Environment

The first wizard page prompts you to select an existing RPC environment or define a new one. When running with NaturalONE, a default RPC environment is available. This is typically named "localhost:1971@NATSRV2800" and refers to a running EntireX broker and Natural RPC server on the local machine.

graphics/using_natOne_specifyEnv.png

Check Use existing RPC environment, select the default RPC environment for NaturalONE and press Next. Continue with Step 2: Customize Natural Client Names.

Changing the default RPC environment for NaturalONE is not required and not recommended, so it is best to uncheck Modify the selected RPC environment. More information on changing an RPC environment can be found in Step 2: Edit the RPC Environment (Optional) under Using the Natural Wrapper for the Client Side with a Remote RPC Environment.

To use a different Natural RPC server for generation, create a new RPC environment. See Step 1: Specify the RPC Environment under Using the Natural Wrapper for the Client Side with a Remote RPC Environment.

Step 2: Customize Natural Client Names

On this page, adapt the names for the Natural client interface objects (subprograms (NSNs) with their parameter data areas (PDAs)), names of the client test programs and specify the location to which all Natural sources are to be written. The generation of client test programs can be disabled.

graphics/using_natOne_customize.png

Note:
If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.

Check Generate Test Programs if client test programs for client interface objects are to be generated. Uncheck if no test programs are to be generated. Use the link Customize the generation of Natural Test programs to specify for each IDL program whether a test program is generated or not. See Generate Test Programs for more information.

For Natural ONE, the Location for the generated Natural sources should be in a Natural project. If the target container is a source folder of a Natural project, the Natural builder will automatically compile and build the source.

These features require support from the Natural RPC server used for generation. If you are using an older version:

See Prerequisites for Natural Wrapper under UNIX | Windows for version number required.

Press Next to start generation.

Generate Test Programs

On this page, specify for each IDL program whether a client test program is generated or not.

graphics/using_common_test.png

Check the IDL programs for which a client test program is to be generated. If a box is unchecked, no client test program is generated for that IDL program. Press OK to save the settings.

Using the Natural Wrapper for the Client Side with a Remote RPC Environment

Step 1: Specify the RPC Environment

The first wizard page prompts you to use an existing RPC environment or create a new one.

graphics/using_remote_specifyEnv.png

Start of instruction setTo use an existing RPC environment

  1. Check Use existing RPC environment, select the desired RPC environment and press Next. If your previously defined filter (see Step 2: Edit the RPC Environment (Optional)) matches more than one Natural library, continue with Step 3: Select a Library (Optional). If the filter matches exactly one Natural library, continue with Step 4a: Customize Natural Client Names and Save Remotely (Optional).

  2. Check Modify the selected RPC environment if you want to change settings prior to generation. Press Next and continue with Step 2: Edit the RPC Environment (Optional).

Start of instruction setTo create a new RPC environment

Step 2: Edit the RPC Environment (Optional)

On this page, connection and authentication settings for the EntireX Broker and Natural RPC server are managed, and you define if the Natural client interface objects are saved remotely on the Natural RPC Server or locally within Software AG Designer.

graphics/using_remote_editEnv.png

Define a new RPC environment or modify an existing one 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 is operating under Natural Security:

You can save the generated Natural sources locally or remotely:

Step 3: Select a Library (Optional)

All Natural libraries that reside in the FUSER system file of the Natural RPC server and that match the filter defined in Step 2: Edit the RPC Environment (Optional) are listed here. This step is skipped if exactly one Natural library matches the filter specification defined in Step 2: Edit the RPC Environment (Optional). In this case, continue with Step 4a: Customize Natural Client Names and Save Remotely (Optional).

graphics/using_remote_selectLib.png

Select the Natural library where you want to save the generated Natural sources and press Next. Continue with Step 4a: Customize Natural Client Names and Save Remotely (Optional).

Press Finish to skip all preceding steps and start generation immediately. If the generated Natural objects already exist from a previous generation, check Overwrite existing Natural objects.

Step 4a: Customize Natural Client Names and Save Remotely (Optional)

On this page, adapt the names for the Natural client interface objects (subprograms (NSNs) with their parameter data areas (PDAs)), and the names of the client test programs. The generation of client test programs can be disabled.

graphics/using_remote_customize-remote.png

Note:
If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.

Check Generate Test Programs if client test programs for client interface objects are to be generated. Uncheck if no test programs are to be generated. Use the link Customize the generation of Natural Test programs to specify for each IDL program whether a test program is generated or not. See Generate Test Programs for more information.

If the generated Natural objects already exist from a previous generation, check Overwrite existing Natural objects.

These features require support from the Natural RPC server used for generation. If you are using an older version:

See Prerequisites for Natural Wrapper under z/OS | UNIX | Windows | BS2000/OSD for version number required.

Press Next to start generation.

Step 4b: Customize Natural Client Names and Save Locally (Optional)

On this page, adapt the names for the Natural client interface objects (subprograms (NSNs) with their parameter data areas (PDAs)), names of the client test programs, and specify the location to which all Natural sources are to be written. The generation of client test programs can be disabled.

graphics/using_remote_customize-local.png

Note:
If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.

Check Generate Test Programs if client test programs for client interface objects are to be generated. Uncheck if no test programs are to be generated. Use the link Customize the generation of Natural Test programs to specify for each IDL program whether a test program is generated or not. See Generate Test Programs for more information.

Specify the Location for the generated Natural sources. Select a container (folder or project) in Software AG Designer.

These features require support from the Natural RPC server used for generation. If you are using an older version:

See Prerequisites for Natural Wrapper under z/OS | UNIX | Windows | BS2000/OSD for version number required.

Press Next to start generation. Continue with Sample Generation Result for the Client Side.

Generate Test Programs

On this page, specify for each IDL program whether a client test program is generated or not.

graphics/using_common_test.png

Check the IDL programs for which a client test program is to be generated. If a box is unchecked, no client test program is generated for that IDL program. Press OK to save the settings.

Sample Generation Result for the Client Side

The following screen shows the successful generation of .NSN, .NSA, .NSP and .NSL objects. The Wrapper Settings included Save locally in a NaturalONE environment.

graphics/using_client_result.png

Using the Generated Sample Natural Program

Before you use the generated sample Natural program (extension .NSP), make sure the Natural library SYSEXT is defined as a steplib for the Natural environment. Use one of the following methods, depending on your environment:

The generated sample Natural program (extension .NSP) demonstrates standard RPC usage and cannot be used for reliable RPC. For reliable RPC, see Reliable RPC Client Example - SENDMAIL.

See also the readme files of the Client and Server Examples for Natural for more information on working with Natural RPC clients.

Top of page

Using the Natural Wrapper for the Server Side

Using the Natural Wrapper for the Server Side within NaturalONE

Step 1: Specify the RPC Environment

The first wizard page prompts you to select an existing RPC environment or define a new one. When running with NaturalONE, a default RPC environment is available. This is typically named "localhost:1971@NATSRV2800" and refers to a running EntireX broker and Natural RPC server on the local machine.

graphics/using_server_natOne_specifyEnv.png

Check Use existing RPC environment, select the default RPC environment for NaturalONE and press Next. Continue with Step 2: Customize Natural Server Names.

Changing the default RPC environment for NaturalONE is not required and not recommended, so it is best to uncheck Modify the selected RPC environment. More information on changing an RPC environment can be found in Step 2: Edit the RPC Environment (Optional) under Using the Natural Wrapper for the Server Side with a Remote RPC Environment.

To use a different Natural RPC server for generation, create a new RPC environment. See Step 1: Specify the RPC Environment under Using the Natural Wrapper for the Server Side with a Remote RPC Environment.

This feature requires support from the Natural RPC server used for generation. See Prerequisites for Natural Wrapper under UNIX | Windows for version number required.

Step 2: Customize Natural Server Names

On this page, adapt the names for the Natural RPC server (subprograms (NSNs) with their parameter data areas (PDAs)) and specify the location to which all Natural sources are to be written.

graphics/using_server_natOne_customize.png

Note:
If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.

For NaturalONE, the location for the generated Natural sources should be in a Natural project. If the target container is a source folder of a Natural project, the Natural builder will automatically compile and build the source.

Press Next to start generation. Continue with Sample Generation Result for the Server Side.

Using the Natural Wrapper for the Server Side with a Remote RPC Environment

Step 1: Specify the RPC Environment

The first wizard page prompts you to use an existing RPC environment or create a new one.

graphics/using_server_remote_specifyEnv.png

Start of instruction setTo use an existing RPC environment

  1. Check Use existing RPC environment, select the desired RPC environment and press Next. If your previously defined filter (see Step 2: Edit the RPC Environment (Optional)) matches more than one Natural library, continue with Step 3: Select a Library (Optional). If the filter matches exactly one Natural library, continue with Step 4a: Customize Natural Server Names and Save Remotely (Optional).

  2. Check Modify the selected RPC environment if you want to change settings prior to generation. Press Next and continue with Step 2: Edit the RPC Environment (Optional).

Start of instruction setTo create a new RPC environment

This feature requires support from the Natural RPC server used for generation. See Prerequisites for Natural Wrapper under z/OS | UNIX | Windows | BS2000/OSD for version number required.

Step 2: Edit the RPC Environment (Optional)

On this page, connection and authentication settings for the EntireX Broker and Natural RPC server are managed, and you define whether the Natural sources are saved remotely on the Natural RPC Server or locally within Software AG Designer.

graphics/using_remote_editEnv.png

Define a new RPC environment or modify an existing one 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 is operating under Natural Security:

You can save the generated Natural sources locally or remotely:

Step 3: Select a Library (Optional)

All Natural libraries that reside in the FUSER system file of the Natural RPC server and that match the filter defined in Step 2: Edit the RPC Environment (Optional) are listed here. This step is skipped if exactly one Natural library matches the filter specification defined in Step 2: Edit the RPC Environment (Optional) In this case, continue with Step 4a: Customize Natural Server Names and Save Remotely (Optional).

graphics/using_remote_selectLib.png

Select the Natural library where you want to save the generated Natural sources and press Next. Continue with Step 4a: Customize Natural Server Names and Save Remotely (Optional).

The Finish is enabled if no related XMM file exists. If you press Finish and the generated Natural objects already exist from a previous generation, check Overwrite existing Natural objects.

Step 4a: Customize Natural Server Names and Save Remotely (Optional)

On this page, adapt the names for the Natural server (subprograms (NSNs) with their parameter data areas (PDAs)).

graphics/using_server_remote_customize-remote.png

Note:
If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.

If the generated Natural objects already exist from a previous generation, check Overwrite existing Natural objects.

Press Next to start generation.

Step 4b: Customize Natural Server Names and Save Locally (Optional)

On this page, adapt the names for the Natural server (subprograms (NSNs) with their parameter data areas (PDAs)) and specify the location to which all Natural sources are to be written.

graphics/using_server_remote_customize-local.png

Note:
If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.

Specify the Location for the generated Natural sources. Select a container (folder or project) in Software AG Designer.

Press Next to start generation. Continue with Sample Generation Result for the Server Side.

Sample Generation Result for the Server Side

The following screen shows the successful generation of .NSN and .NSA objects. The Wrapper Settings included Save locally in a NaturalONE environment.

graphics/using_server_result.png

See also the readme files of the Client and Server Examples for Natural for more information on working with Natural RPC clients.

Top of page