Natural subprograms can be exposed as "web services" thru the SOA Gateway, a DataView (XRD) maps the parameters passed to the called subprogram.
The following steps are required:
Define a driver and prepare the environment, described in separate sections for Mainframe, Unix / Linux and Windows platforms.
For prerequisites and compatibility information please read here
Create the mapping PDA -> DataView, the following sections outline the required steps.
The preferred way for creating DataView(s), the mapping from a Natural Paramaeter Data Area (PDA) to the SOA Gateway structures exposing the WebService via a WSDL, is through an automatic "discovery" process as described here.
The WebService creation process can either be started from the server's context menu:
or by clicking the 'Create new WebServices' action button in the title area of the Configuration View:
It may be required to provide login credentials, in an environment protected by Natural Security:
Specify the credentials - User ID and Password - in the SOAP Security section, click Set
Once the WebService Creation Wizard has been activated, the first step is to select the driver to be used as the source:
Select a defined driver of type 'natural' from the dropdown box
Click the 'Next >' button
Specify the name of the Library to be scanned, select if it is a Natural "User" or a "System" library. Click the 'Next >' button:
Alternatively, if the library name is unknown, specify a generic library name, or a from-to range and click the button. For example, the following input
will result in this additional selection dialog to pop up
Select a library with a double-click, or select a library name and click , or stop the wizard by clicking the button.
Note:
Library SYSSOAEX contains sample subprograms to demonstrate SOA
Gateway features.
Select the name(s) of the object(s) to be turned into WebServices, click the button. Again, this can be a specific object name, a generic object name, or a range of objects. When a specific object name is enteren in the Object field, but the "to" Object name field is left empty, this will result in all objects starting from the specified name will be listed
You may return to Library selection mode by clicking the button.
A list of objects matching the selection criteria is displayed
Either select all, or only the one(s) you are specifically interested in, click the button.
In this case we select (check the box left to the WebService name) all objects of type subprogram.
The generation report indicates what has been created:
The requested WebServices and WebService definition files (DataView(s) and XSD(s)) have been added to your server configuration
The Wizard is still active and ready for further discovery, click 'Next >' to start the process again, or 'Done' to dismiss the wizard.
In addition to the automatic generation process outlined above, Webservices can be created / defined as follows.
Add a new SOA Gateway WebService, specifying the following:
A WebService name
Select a driver of type "natural" from the dropdown list
select a DataView from the "File" dropdown list, if no DataView exists yet, specify the anticipated name of the DataView (XRD) to be created later
For "WebService Identification and Options":
The Natural Library name in the "Library" field
The Natural subprogram name in the "Program" field
Note:
For Mainframe Natural only the Program name is to be entered,
because the library is specified on the driver, not the individual
WebService
In addition to the manual approach described in detail in the Data Views section, WebServices and DataView(s) for the SOA Gateway can be generated/imported from SYSOBJH extracts or directly from Natural sources.
For a detailed description of the process refer to the Webservice Creation section
Certain steps are required to enable the SOA Gateway server to call Natural subprograms, this section describes them.
Specify a valid LOGON <library>,<userid>,<password> in the STACK parameter of the parameter module used with the SOA Gateway Natural driver.
Library SYSEXT must be defined as a STEPLIB to library SYSSOA.
Important:
The SOA Gateway interface to Natural requires the interface
library libnatural.so in the LD_LIBRARY_PATH (LIBPATH on AIX).
However, this shared library is contained in $NATDIR/$NATVERS/bin, and
not in the Natural /lib directory. Due to this, either the Natural /bin
directory must be added to search path variable, or libnatural.so copied /
moved to a directory contained in the search path variable.
In the SOA Gateway Servers View, select the server you want to define a Natural driver for, in the Properties View select the Drivers tab, click the Add... button.
From the Driver Configuration Dialog select "Natural_Driver"
Important:
When defining a Natural driver for the first time, make sure to
check the "Show (post-setup) Driver Information" box because only this will
allow you to extract the INPL file containing the SOA Gateway Natural
interface- and example programs.
The following values are preset, change as required:
Only the Driver DLL parameter is to be entered asis, you are free to choose any Driver Name you wish, set the SBCS codepage and MBCS codepage parameters according to your local or internationalization requirements.
Click the Save button, you will now be asked to (optionally) enter Natural initialization parameters, for example PARM=MYPARM to use a Natural parameter module other than NATPARM.
Click the Save button again, the newly defined driver will appear in the Driver Properties section:
When "Show (post-setup) Driver Information" has been selected, the following information box will be shown, and allow the extraction of the SYSOBJH file containing the SOA Gateway Natural interface- and example programs.
The following steps are required to load the SOA Gateway WebService creation and demo programs in a Linux / Unix environment
Start the Natural Configuration Utility (natparm)
For the specific Natural Parameter file to be used when accessing Natural from the SOA Gateway (default: “NATPARM”), select "Edit" -> “Natural Execution Configuration”
Select “Steplibs”
Define library “SYSEXT” as a “Steplib Extension”
Press the “return” key to save the Steplib modification(s), then use the “Esc” key to close all windows.
Select “File” -> “Save” to preserve the adjusted Steplib setting
Quit the Natural Configuration Utility with “File” -> “Exit”.
Before entering Natural to load the SOA Gateway system- and demo-programs the environment variable WRKF3 needs to be set to allocate work file 3 for the “Natural Object Handler”
Here, as an example, the work file name is defined as “natwork3.sag” in the current working directory.
Start Natural, tab to the “Direct” entry on the main menu, enter “SYSOBJH” to start the Natural Object Handler:
Select the Object Handler “Load” function
Select “Load objects from Natural work file(s)”
Enter the SOA Gateway OBJH “Work file” name and select “Portable work file” and “Set additional options”
Either enter a “Report file” name, or deselect the “Write report” option
Hit the “return” key a number of times, the following screen will finally indicate what Object handler operation will be carried out:
Hit the “return” key once again, the SOA Gateway Natural system- and demonstration objects will be loaded, the following message indicates the completion of the load operation.
Press the Enter ( = return ) key again, and one more time to quit the load function, followed by the “Esc” key to terminate the Natural Object Handler.
The SOA Gateway interface to Natural requires the interface library natni.dll.
Important:
Make sure the %NATDIR%/%NATVERS/bin directory, which
contains natni.dll, is in the path.
Specify a valid LOGON <library>,<userid>,<password> in the STACK parameter of the parameter module used with the SOA Gateway Natural driver.
Library SYSEXT must be defined as a STEPLIB to library SYSSOA.
In the SOA Gateway Servers View, select the server you want to define a Natural driver for, in the Properties View select the Drivers tab, click the Add... button.
From the Driver Configuration Dialog select "Natural_Driver"
Important:
When defining a Natural driver for the first time, make sure to
check the "Show (post-setup) Driver Information" box because only this will
allow you to extract the INPL file containing the SOA Gateway Natural
interface- and example programs.
The following values are preset, change as required:
Only the Driver DLL parameter is to be entered asis, you are free to choose any Driver Name you wish, set the SBCS codepage and MBCS codepage parameters according to your local or internationalization requirements.
Click the Save button, you will now be asked to (optionally) enter Natural initialization parameters, for example PARM=MYPARM to use a Natural parameter module other than NATPARM.
Click the Save button again, the newly defined driver will appear in the Driver Properties section:
When "Show (post-setup) Driver Information" has been selected, the following information box will be shown, and allow the extraction of the SYSOBJH file containing the SOA Gateway Natural interface- and example programs.
The following steps are required to load the SOA Gateway WebService creation and demo programs in a Windows environment
Start the Natural Configuration utility
For the specific Natural Parameter file to be used when accessing Natural from the SOA Gateway (default: “NATPARM”), under “Natural Execution Configuration” -> “Steplibs”, add library “SYSEXT” as a “Steplib Extension"
Klick the “Save” button, or select File -> Save
Start Natural Studio, the initial display will be something like this
Import the SOA Gateway Natural interface and the demo programs. For this, start the Natural Object Handler – enter the command “SYSOBJH” in Natural Studio's Command line
Select the Load function
Select “Load objects from Natural work file(s)”
Specify (or browse for) the SOA Gateway OBJH unload file, check “Portable work file”, select “Use additional options”, click “Next”
click “Next”
Click “Next” to “Load all objects from work file”
Click “Next” again to start the actual load process.
The SOA Gateway System- and Demo-programs have been loaded. Click “Next”.
Click “Cancel” to terminate the Object Handler load function
Confirm termination of the Object Handler load function by klicking “Yes”
Dismiss the Object Handler “the Windows way” by clicking the “close” icon in the upper right hand corner.
In the SOA Gateway Servers View, select the server you want to define a Natural driver for, in the Properties View click the Driver Definition Wizard button.
Select the Natural Driver, click the button
Important:
When defining a Natural driver for the first time, make sure to
check the "Show (post-setup) Driver Information" box because only this will
allow you to extract the INPL file containing the SOA Gateway Natural
interface- and example programs.
The Driver Defintion Dialog will be pre-set with the following values, change according to your needs and preferences, click the button
As the Natural driver requires a number of additional parameters, the dialog will expand and prompt for more input. Again, fill these parameters as required, you are free to choose any Driver Name you wish, set the SBCS codepage and MBCS codepage parameters according to your local or internationalization requirements. Click again.
The parameters are as follows
| Parameter | Value |
|---|---|
| NaturalBatchPgm | The name of the Natural Batch nucleus load module. A standard
Batch-Natural is used, no modifications or additions to the Natural nucleus are
required.
Important: |
| InitParms | Natural initialization parameters. Specify any required parameters overriding the Natural parameter module settings, all Natural profile parameters are allowed here. |
| PreInitSessions | The number of sessions in the session pool to be pre-initialized. |
| MaxSessions | The overall size of the session pool, this parameter should be set to a value high enough to accomodate the peak number of parallel sessions expected. |
| NaturalLibrary | The Natural Library to log on. |
| NaturalSteplibs | Specify up to 7 Natural library names, in a comma-separated
list, to be set as STEPLIB(s). When the NaturalLibrary parameter is not
specified as "SYSSOA", include it in the list of Steplibs if you
intend to use the "WebService creation" feature to import PDA structures and
expose them as SOA Gateway WebService(s).
Note: |
| NaturalSecurity | Specify Yes or No, depending on if your
environment is protected by Natural Security or not.
Important: |
| naturalUserId | Specify a Natural userid defined to Natural Security |
| naturalPassword | Specify the password valid for the user defined on the naturalUserid parameter |
Once saved, the newly defined driver will appear in the Driver Properties section:
When "Show (post-setup) Driver Information" has been selected, the following information box will be shown, and allow the extraction of the INPL file containing the SOA Gateway Natural interface- and example programs.
Add the Natural load library, or more specifically the load library containing the Natural batch nucleus specified in the driver's NaturalBatchPgm parameter and the modules NATXCAL and NATXCAL4 (contained in the Natural distribution load library), to the SOA Gateway server Job's / STC's STEPLIB.
You may want to add a CMPRINT DD statement to your server JCL, in case of an error during Natural session initialization or execution Natural will write its error messages to this dataset.
Ensure the SOA Gateway server region is sufficiently sized to cope for Natural's storage requirements, including the local bufferpool(s) if it is used.
Any standard Natural INPL job can be used to load the SOA Gateway system- and demo-programs from the supplied dataset ASGvrm.INPL, for example (as usual, replace the library names, database parameters etc. to match your environment):
//SMAI061 JOB SAG,MSGLEVEL=1, // CLASS=O,MSGCLASS=X,REGION=8M //*JOBPARM LINES=9999 //* //* LOAD NATURAL PROGRAMS INTO ADABAS SYSTEMFILE //* INPL SOA Gateway 411 SYSTEM FILE //* FROM FILE ASGvrm.INPL //* //NATB0100 EXEC PGM=NAT423BA, // TIME=1400,COND=(0,LT) //STEPLIB DD DSN=SAGLIB.SMALOAD,DISP=SHR // DD DSN=SAGLIB.ADA813.LOAD,DISP=SHR //* //CMPRMIN DD * STACK=INPL IM=D,INTENS=1,XML=OFF,CFICU=OFF NAFSIZE=0,DLISIZE=0,DB2SIZE=0,MADIO=0,MAXCL=0,MT=0 AUTO=ON FUSER=(,8) //* //DDPRINT DD SYSOUT=* //DDDRUCK DD SYSOUT=* //MPMDUMP DD DUMMY //SYSUDUMP DD DUMMY //DDKARTE DD DUMMY //DDCARD DD * ADARUN DB=001,DE=3390,SVC=249,MODE=MULTI //CMPRINT DD SYSOUT=* //CMWKF01 DD DSN=ASGvrm.INPL,DISP=OLD B FIN /* //
The WebService Creation ("Discovery") process generates a DataView (XRD) and optionally a XML Schema (XSD) from either a Natural PDA (Parameter Data Area) or a parameter data definition (either an inline DEFINE DATA PARAMETER and/or referenced external PDA(s)) within a Natural subprogram.
These bits of mapping information are assembled into a WSDL in real time by the SOA Gateway server when a WSDL is requested through the
http://<server>:<port>/<webservice>?WSDL URI for a specific WebService.
When the signature (parameters) of a subprogram change, only the DataView needs to be recreated (via "discovery") and the WebService "refreshed" (the DataView cleared out of the cache), with the next access to the WSDL it will automatically reflect the changed parameters.
| Natural Type | DataView | WSDL / XML Schema | Notes |
|---|---|---|---|
| A | sbcs (space padded) | xs:string | Dynamic variables allowed |
| W | mbcs (space padded) | xs:string | |
| B | hex.Binary | xs:hexBinary | Dynamic variables allowed |
| F4 | float | xs:float | |
| F8 | double | xs:double | |
| I1 | byte | xs:byte | |
| I2 | short | xs:short | |
| I4 | int | xs:int | |
| L | Natural logical | xs:boolean | 0, false / 1, true |
| N | zoned decimal | xs:decimal | |
| P | packed decimal | xs:decimal | |
| D | date | xs:date | YYYY-MM-DD |
| T | date + time | xs:dateTime | YYYY-MM-DDTHH:MM:SS(.s) |
