
Portus	Version 2012-12-17	PDF BOOKS \| HOME UP PREV NEXT

— Administration —

Using Portus with Natural

Natural subprograms can be exposed as (Web) Services through , 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.

Natural Service generation
Other ways of defining a Service
Preparing the Natural environment
Type mapping

Natural Service generation

The preferred way for creating DataView(s), the mapping from a Natural Paramaeter Data Area (PDA) to the Portus structures exposing the Service via a WSDL, is through an automatic "discovery" process as described here

Other ways of defining a Service

In addition to the automatic generation process outlined above, Services can be created / defined as follows.

Define a Natural Service manually

Add a new Portus Service, specifying the following:
- A Service name
- Select a driver of type "Natural" from the dropdown list
- For "Service 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 Service

Create Service(s) and DataView(s) from Natural sources or a SYSOBJH unload file

In addition to the manual approach described in detail in the Data Views section, Services and DataView(s) for Portus can be generated/imported from SYSOBJH extracts or directly from Natural sources.

For a detailed description of the process refer to the Service Creation section

Preparing the Natural environment

Certain steps are required to enable the Portus server to call Natural subprograms, this section describes them.

Prepare the Natural environment on Linux / UNIX
Prepare the Natural environment on Windows
Prepare the Natural environment on the Mainframe

Prepare the Natural environment on Linux / UNIX

Using Portus in an environment protected by Natural Security (NSC)

Specify a valid LOGON <library>,<userid>,<password> in the STACK parameter of the parameter module used with the Portus Natural driver.
Library SYSEXT must be defined as a STEPLIB to library SYSSOA.

Defining the driver

Important:
The Portus 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 Portus 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 Portus Natural interface- and example programs.

The following values are preset, change as required:

graphics/natsuo01.png

Only the Driver DLL parameter is to be entered as is, 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.

graphics/natsuo01b.png

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 Portus Natural interface- and example programs.

graphics/natsuo03.png

Loading the Portus Natural system- and demo programs on Linux / UNIX

The following steps are required to load the Portus Service 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 Portus (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 Portus 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 Portus 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 Portus 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.

Prepare the Natural environment on Windows

The Portus 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.

Using the Portus in an environment protected by Natural Security (NSC)

Specify a valid LOGON <library>,<userid>,<password> in the STACK parameter of the parameter module used with the Portus Natural driver.
Library SYSEXT must be defined as a STEPLIB to library SYSSOA.

Defining the driver

In the Portus 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"

The following values are preset, change as required:

graphics/natsuo01.png

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.

graphics/natsuo01b.png

Click the Save button again, the newly defined driver will appear in the Driver Properties section:

graphics/natsuo03.png

Loading the Portus Natural system- and demo programs on Windows

The following steps are required to load the Portus Service 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 Portus (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 Portus 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 Portus 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 Portus 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.

Prepare the Natural environment on the Mainframe

Defining the driver

In the Portus 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.

Select the Natural Driver, click the Configure button

The Driver Defintion Dialog will be pre-set with the following values, change according to your needs and preferences, click the Save button

graphics/natsum01c.png

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 Save again.

graphics/natsum02.png

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: This MUST refer to a Natural batch nucleus with NATOS compiled with LE370=NO.
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 "Service creation" feature to import PDA structures and expose them as Portus Service(s). Note: When running with Natural Security, the Steplib(s) specified here are ignored, they are set by Natural Security based on the logon library and logon user id.
NaturalSecurity	Specify Yes or No, depending on if your environment is protected by Natural Security or not. Important: A logon will be made to the specified NaturalLibrary, with the specified naturalUserId and naturalPassword. It is essential that library SYSEXT as well as any required application libraries are defined as STEPLIBs to that library in Natural Security
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 Portus Natural interface- and example programs.

graphics/natsum04.png

The Portus server Job / STC

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 Portus 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 Portus server region is sufficiently sized to cope for Natural's storage requirements, including the local bufferpool(s) if it is used.

Loading the Portus Natural system- and demo programs on the Mainframe

Any standard Natural INPL job can be used to load the Portus 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 Portus 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
/* 
//

Type mapping

The Service 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 Portus server when a WSDL is requested through the

http://<server>:<port>/<Service>?WSDL URI for a specific Service.

When the signature (parameters) of a subprogram change, only the DataView needs to be recreated (via "discovery") and the Service "refreshed" (the DataView cleared out of the cache), with the next access to the WSDL it will automatically reflect the changed parameters.

NATURAL to WSDL XML Schema Data Type mapping

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)

PDF BOOKS | HOME UP PREV NEXT