Using the Natural Wrapper


Starting the Natural Wrapper

Start the Natural Wrapper from the context menu of an IDL file: Natural > Generate RPC Client.

graphics/using_start.png

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 clear 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. Clear this box 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.

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 not checked, 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 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:

  • Your user ID and password must be defined in Natural Security. If the Natural Security user ID or password differs from the broker user ID and password, use RPC Server Authentication - otherwise use EntireX Authentication for both.

  • Access to the Natural system library SYSIDL is required.

You can save the generated Natural sources locally or remotely:

  • Locally
    Sources are saved locally in the Software AG Designer. This setting is preferred if you develop with NaturalONE and will additionally create a helper LDA, NATRPCL for correct local compilation in a NaturalONE project in Software AG Designer. If you select this option, continue with Step 4b: Customize Natural Client Names and Save Locally (Optional) and save locally.

  • Remotely
    Sources are saved remotely on the Natural RPC server. If you save the Natural sources remotely, you have to specify a target Natural library. Enter either an exact name or use a filter for range of values. The following wildcards are available:

    • asterisk "*" (any position) to list names matching any sequence of characters

    • question mark "?" (any position) to list names matching any single character

    • greater than ">" (final character only) to list names after

    • lower than "<" (final character only) to list names before

    Only Natural libraries that reside in the FUSER system file of the Natural RPC server can be specified. The Natural library specified is not created from the Designer, it must exist in the FUSER system file (at least one Natural object stored here).

    Press Next. If your filter 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) and save 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. Clear this box 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.

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. Clear this box 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.

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 not checked, 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 Natural client interface objects (subprograms (NSNn) with their parameter data areas (PDAs (extension NSA)), client test program (NSPs) and the common data area NATRPCL.NSL). 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:

  • for NaturalONE, use the context menu of the NaturalONE project and choose Properties > Natural > Environment, add SYSEXT

  • for Natural Security environments, use SYSSEC

  • for any other Natural environment, use NATPARM

The generated sample Natural program (extension .NSP) demonstrates standard RPC usage.

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

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

Step 2: Customize Natural Server Names

On this page, adapt the names for the Natural RPC server skeletons (subprograms (NSNs) with their parameter data areas (PDAs)) and specify the location to which all Natural objects 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

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:

  • Your user ID and password must be defined in Natural Security. If the Natural Security user ID or password differs from the broker user ID and password, use RPC Server Authentication - otherwise use EntireX Authentication for both.

  • Access to the Natural system library SYSIDL is required.

You can save the generated Natural sources locally or remotely:

  • Locally
    Sources are saved locally in the Software AG Designer. This setting is preferred if you develop with NaturalONE. If you select this option, continue with Step 4b: Customize Natural Server Names and Save Locally (Optional) and save locally.

  • Remotely
    Sources are saved remotely on the Natural RPC server. If you save the Natural sources remotely, you have to specify a target Natural library. Enter either an exact name or use a filter for range of values. The following wildcards are available:

    • asterisk "*" (any position) to list names matching any sequence of characters

    • question mark "?" (any position) to list names matching any single character

    • greater than ">" (final character only) to list names after

    • lower than "<" (final character only) to list names before

    Only Natural libraries that reside in the FUSER system file of the Natural RPC server can be specified. The Natural library specified is not created from the Designer, it must exist in the FUSER system file (at least one Natural object stored here).

    Press Next. If your filter 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) and save 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 RPC server skeletons (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 RPC server skeletons (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 the Natural RPC server skeletons (subprograms (NSNs) with their parameter data areas (PDAs (extension NSA))). 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 servers.