This document describes how to use the Adapter Services Wrapper for Natural. It covers the following topics:
Generating an Adapter Service from a New Natural RPC Environment
Generating an Adapter Service from an Existing Natural RPC Environment
webMethods Integration Server with connections and services generated.
The Service Development feature in Software AG Designer. This is installed with Software AG Installer into Software AG Designer.
The Natural subprograms in source or object form available through a Natural RPC server or as local files.
This section covers the following topics:
Step 1: Start the Adapter Services Wrapper for Natural Wizard
Step 4: Select Natural Library from RPC Environment (Optional)
Step 6: Redesign the Interface for Natural Subprograms (Optional)
Usually, the wizard is started from the context menu of a folder in the Package Navigator. This view opens when the Service Development perspective opens:
As an alternative, you can start the wizard with one of the following options:
Choose .
Choose the "New" icon from the toolbar.
Choose New from a context menu in another view.
Press Ctrl-N.
Choose Next and continue with Step 2: Create a New RPC Environment.
If no RPC environments are defined, you only have the option to . The RPC environments are managed in the Preferences.
Choose Create a new RPC Environment and press 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.
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,
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
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:
wildcard asterisk "*" (any position) to list libraries or program names matching any sequence of characters.
wildcard question mark "?" (any position) to list libraries or program names matching any single character.
wildcard greater than ">" (final character only) to list libraries or program names after.
wildcard lower than "<" (final character only) to list libraries or program names before.
no wildcard to extract from the given library or program. If the library or program does not exist, an error message will be displayed.
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 to continue.
If Library Name (using any wildcards) matches one Natural library only, continue with Step 5: Select Natural Subprogram from RPC Environment.
If Library Name matches more than one Natural library, continue with 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 under Extracting Software AG IDL File from a New Natural RPC Environment in the IDL Extractor for Natural documentation.
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 to continue with Step 5: Select Natural Subprogram from RPC Environment.
All Natural subprograms that match the specification in the Extractor Settings are listed here. See Step 3: Edit RPC Environment.
In the Source pane select at least one program from the list of Natural subprograms (CALLNATs). You can also choose or .
In the Extraction Settings pane, specify whether the IDL is to be extracted from Natural subprogram sources or compiled objects. The following restrictions apply:
Extract from Natural sources (recommended)
Extracting from a source is only possible if the compiled object and
source are in sync. For example, in the screen above, source extraction is not
possible for
SENDMAIL, because there is no source, only an object
SENDPOST, because the source is modified after last compilation
Extract from Natural objects
Extracting from an object is always possible.
Check Redesign the interfaces if you want to design the extracted interfaces to the Natural subprograms. The button will be enabled. See Redesigning the Extracted Interface in the IDL Extractor for Natural documentation. If you do not check Redesign the interfaces, refer to Natural to IDL Mapping in the IDL Extractor for Natural documentation 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 the IDL Extractor for Natural documentation in Natural to IDL Mapping in the IDL Extractor for Natural documentation.
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 7: Create New Adapter Services.
In this step, you can redesign the interface. This includes:
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 |
|---|---|---|
|
|
Create | Creates a new interface (IDL program) based on the original parameters of the Natural subprogram. |
|
|
Duplicate | Creates a new interface (IDL program) based on the current interface (active tab). All modifications of the current interface are copied. |
|
|
Rename | Change the name of the current interface (active tab). The name must be unique. |
|
|
Remove | Removes the current interface (active tab). At least one interface must exist. |
|
|
Expand All | Expands the Natural and IDL tree. |
|
|
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:
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.
FUNCTION (A3) [MOD]).
).
Middle right
Output pane. The extracted interface (IDL).
Bottom
Reference. The Natural subprogram source and its PDA sources, each
displayed in a separate tab.
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 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 7: Create New Adapter Services.
After you have defined the interfaces for the selected Natural subprograms, the wizard asks for the webMethods ESB, the package and the namespace (folder) for the new connection and the services.
The Connection Name default is
<library name>Connection. Adapter
services have the same name as the corresponding Natural subprograms. You
cannot change the services names within this wizard.
The default Connection Type RPC Connection. If there are inbound parameters only, you can also specify connection type Reliable RPC Connection.
If the connection or adapter services already exist in this webMethods ESB, you can overwrite them by checking Overwrite existing Objects in Integration Server.
The result of the generation step is visible in the Package Navigator:
Usually, the wizard is started from the context menu of a folder in the Package Navigator. This view opens when the Service Development perspective opens:
As an alternative, you can start the wizard with one of the following options:
Choose .
Choose the "New" icon from the toolbar.
Choose New from a context menu in another view.
Press Ctrl-N.
Choose Next and continue with Step 2: Select an RPC Environment.
If RPC environments are defined, you can select an existing one. RPC environments are managed in the Preferences.
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 to continue.
If Modify the selected RPC environment is checked, continue with Step 3: Edit RPC Environment above.
If Modify the selected RPC environment is not checked and the Natural library name matches one Natural library only (using any wildcard defined in Step 3: Edit RPC Environment), continue with Step 5: Select Natural Subprogram from RPC Environment above.
If Modify the selected RPC environment is not checked and the Natural library name matches more than one Natural library, continue with Step 4: Select Natural Library from RPC Environment (Optional) above.
Note:
The folder File and the RPC environment
localhost@NATSRV2800 (default RPC server for NaturalONE)
are available only if NaturalONE plugins are installed.
Use the RPC Environment Manager in the IDL Extractor for Natural documentation to manage RPC environments.
Use the preference page for the IDL Extractor for Natural to manage the default values relevant for Step 5: Select Natural Subprogram from RPC Environment. See Preferences under Using the Software AG IDL Extractor for Natural.