Integrating Web Services and
Natural Objects Using EntireX
Technical Paper: Calling a Web Service from Natural
4/15/2013
Software AG
Global Support Services
Calling a Web Service from Natural
1) Start Broker (e.g. ETB1331)
2) Check that Service RPC/SRV2/CALLNAT and Service RPC/XMLGETTEMP/CALLNAT are defined in the
Broker Attribute File
3) Start a Natural RPC Server with the following settings (see Sample RPC Server JCL in Appendix A):
STACK=(LOGON MYLIB2)
RPC=(SERVER=ON,RPCSIZE=8000,SRVNAME=SRV2,SRVNODE=ETB1331,MAXBUFF=4000,
TRACE=(0),ACIVERS=9)
NOTE: If Library MYLIB2 is empty, create a Natural object of any type, so that the Natural Wrapper
can save objects remotely into this Library (see Step 18 below).
4) Optional: Check that the Service RPC/SRV2/CALLNAT has been registered (e.g. using SMH)
5) Start Software AG Designer (e.g. Start > Software AG > Tools > Software AG Designer 8.2)
6) In Software AG Designer, make sure you are in the EntireX Perspective, and create a new Project:
7) Select General > Project and click Next:
Page 1
Calling a Web Service from Natural
8) Provide a new Project Name (e.g. CallWebServiceFromNaturalDemo2) and click Finish
9) Right-click the Project Name (e.g. CallWebServiceFromNaturalDemo2), click “New” and select “IDL
Extractor for WSDL”:
10) Select “Use Entry from List” and “URL”, and click Next:
Page 2
Calling a Web Service from Natural
11) Provide the URL of the Web Service WSDL, and click Next:
NOTE: The following is the URL of the WSDL associated with this external Web Service:
http://www.w3schools.com/webservices/tempconvert.asmx?WSDL
12) The name of the Container will be the Project name (e.g. /CallWebServiceFromNaturalDemo2) – at
this point, click Next:
Page 3
Calling a Web Service from Natural
13) On the “Broker Settings” screen, point to the Broker and Server from Steps 1 and 3 above – then,
click Next:
14) The next screen shows the Legacy Options. Click Finish on the Legacy Options screen.
NOTE 1: For this particular example, you can use the default settings. In some particular instances, you
might have to select options such as “Transform variable-length alphanumeric fields (e.g. AV -> An,
AVn)” or “Transform unbounded arrays (e.g. V -> n, Vn)”.
NOTE 2: You can select whether Library/Program short names will be created for Natural, COBOL or
PL/I RPC Clients, by selecting the corresponding option from the following drop-down field:
Page 4
Calling a Web Service from Natural
15) The IDL will be created within the selected Project and displayed automatically in the Editor:
NOTE: The corresponding XMM will also be created within the Project. This will be the XMM used by the
XML RPC Server, as described in the corresponding steps below.
16) Right-click the IDL and select “Generate Natural from Software AG IDL” > “RPC Client…”:
Page 5
Calling a Web Service from Natural
17) Select the existing RPC environment that points to the Broker in Step 1 and the RPC Server that
was started in Step 3. Then, check the box “Modify the selected RPC environment” and click Next:
18) On the next screen (under “Wrapper Settings”), select “Save remotely” and enter “MYLIB2” as the
Target Library Name -- then, click Next:
Page 6
Calling a Web Service from Natural
NOTE: If error “There are no libraries matching your filter MYLIB2!” occurs while trying to save
remotely, create a Natural object of any type in Library MYLIB2 (refer to Step 3 above).
19) On the next screen, select Library MYLIB2 and click Finish.
NOTE: Optionally, you can check the box “Overwrite existing Natural objects” – use caution when
using this option, as you might not be able to restore these objects from an earlier state.
20) Open a Natural Session passing the following parameters, and LOGON to Library MYLIB2:
NAT823 RPC=(RPCSIZE=64,MAXBUFF=60,AUTO=ON,ACIVERS=9)
21) List the objects in Library MYLIB2 (all Objects, except for TEST, were generated by the Natural
Wrapper Wizard):
Name
*________
CELSIUST
CELSIUS1
CELSIUS2
FAHRENHE
FAHRENH1
FAHRENH2
TEST
Type
*__________
Subprogram
Parameter
Program
Subprogram
Parameter
Program
Text
S/C SM Version User ID
Date
Time
*__ * *______ *________ *__________ *________
S
S 8.2.02
MYUID
2013-04-04 11:14:53
S
S 8.2.02
MYUID
2013-04-04 11:14:53
S
S 8.2.02
MYUID
2013-04-04 11:14:53
S
S 8.2.02
MYUID
2013-04-04 11:14:52
S
S 8.2.02
MYUID
2013-04-04 11:14:52
S
S 8.2.02
MYUID
2013-04-04 11:14:52
S
8.2.03
MYUID
2013-04-04 11:10:02
22) Stow all Natural Objects (or perform a CATALL of all existing Source Code) in Library MYLIB2
NOTE: At this point, we will proceed to work on the XML RPC Server. We will return to Natural in
Step 29.
Page 7
Calling a Web Service from Natural
23) On Windows, create a BAT file to start the XML RPC Server:
- Copy file:
C:\SoftwareAG\EntireX\bin\jxmlrpcserver.bat
To file:
C:\SoftwareAG\EntireX\bin\jxmlrpcserver_GETTEMP.bat
24) Using a text editor, EDIT file jxmlrpcserver_GETTEMP.bat and make these changes:
- Change the Properties file:
From: @set EXXPROP=%EXXDIR%\config\entirex.xmlrpcserver.properties
To:
@set EXXPROP=%EXXDIR%\config\entirex.xmlrpcserver_GETTEMP.properties
- Change the Configuration file:
From: @set EXXCONF=%EXXDIR%\config\entirex.xmlrpcserver.configuration.xml
To:
@set EXXCONF=%EXXDIR%\config\entirex.xmlrpcserver.configuration_GETTEMP.xml
- Change the Java Trace Level:
From: "%JAVA_HOME_BIN%java" %PROXY% -Dentirex.trace=0...
To:
"%JAVA_HOME_BIN%java" %PROXY% -Dentirex.trace=2...
(do not modify the rest of the line)
25) Create the XML RPC Server Properties and Configuration files:
- Copy file:
C:\SoftwareAG\EntireX\config\entirex.xmlrpcserver.properties
To file:
C:\SoftwareAG\EntireX\config\entirex.xmlrpcserver_GETTEMP.properties
- Copy file:
C:\SoftwareAG\EntireX\config\entirex.xmlrpcserver.configuration.xml
To file:
C:\SoftwareAG\EntireX\config\entirex.xmlrpcserver.configuration_GETTEMP.xml
26) Using a text editor, make these changes in entirex.xmlrpcserver_GETTEMP.properties:
- Change the Configuration file:
From:
entirex.sdk.xml.runtime.configurationfile=entirex.xmlrpcserver.configuration.xml
To:
entirex.sdk.xml.runtime.configurationfile=entirex.xmlrpcserver.configuration_GETTEMP
.xml
- Change the Broker node:
From: entirex.server.brokerid=localhost
To:
entirex.server.brokerid=MyMainframe:MyPortNumber (use your Broker ID and Port)
- Change the RPC Server:
From: entirex.server.serveraddress=RPC/XMLSERVER/CALLNAT
To:
entirex.server.serveraddress=RPC/XMLGETTEMP/CALLNAT
27) Using a text editor, make these changes in entirex.xmlrpcserver.configuration_GETTEMP.xml:
- In section <BrokerID>:
From: localhost:1971
To:
MyMainframe:MyPortNumber (use your Broker ID and Port)
- In section <ServerAddress>:
From: RPC/XMLSERVER/CALLNAT
To:
RPC/XMLGETTEMP/CALLNAT
Page 8
Calling a Web Service from Natural
- In section <TargetServer name=...>:
From: "http://localhost:10010/wsstack/services/exampleXML"
To:
"http://www.w3schools.com/webservices/tempconvert.asmx"
- In tag <exx-xmm name=...> of section <xmms>:
From: "C:\SoftwareAG\EntireX\examples\RPC\basic\example\XMLServer\example.xmm"
To:
"C:\workspace82\CallWebServiceFromNaturalDemo2\TempConvert.xmm"
(the actual location can be obtained from the XMM Properties in SAG Designer)
28) Start the EntireX XML RPC Server by executing the Windows BAT file
“C:\SoftwareAG\EntireX\bin\jxmlrpcserver_GETTEMP.bat” from a DOS Command Prompt window,
for example, as follows:
NOTE: Since the Java Trace Level was set to ‘2’ in Step 24 above, the XML RPC Server will start,
echoing back a number of trace lines in the DOS window above. At this point, we should have a
running XML RPC Server registered with Broker on the Mainframe, and we can return to the Natural
session on the Mainframe.
Page 9
Calling a Web Service from Natural
29) Run program FAHRENH2 from Natural Library MYLIB2, and provide the data requested, for example:
EntireX RPC Template - Natural FAHRENHE Client
Node name .......
Server name .....
RPC Library .....
Compression .....
ETB1331
XMLGETTEMP______________________
__________________________________________________
_
Encryption ...... 0
EntireX Authentication
User id ......... MYUID___
Password ........
RPC
RPC
RPC
RPC
Server Authentication
User id .... ________
Password ....
ETID ........ ________
Natural Logon ... _ (Y/L = Logon, N/' ' = No Logon)
FAHRENHEIT .............. 80______________________________________
FAHRENHEITTOCELSIUSRESULT ________________________________________
30) Press PF5 to execute the call to the Web Service
31) The results should be similar to the following:
FAHRENHEIT .............. 80______________________________________
FAHRENHEITTOCELSIUSRESULT 26.6666666666667________________________
Broker Logon
: ok
Calling FAHRENHE: success.
Broker Logoff
: ok
NOTE: The messages above indicate that the first test was successful (Fahrenheit to Celsius).
Change the Fahrenheit field and press PF5 to test with different values, or press any other PF-Key
to exit the FAHRENH2 program.
Page 10
Calling a Web Service from Natural
32) Run program CELSIUS2 from Natural Library MYLIB2, and provide the data requested, for example:
EntireX RPC Template - Natural FAHRENHE Client
Node name .......
Server name .....
RPC Library .....
Compression .....
ETB1331
XMLGETTEMP______________________
__________________________________________________
_
Encryption ...... 0
EntireX Authentication
User id ......... MYUID___
Password ........
RPC
RPC
RPC
RPC
Server Authentication
User id .... ________
Password ....
ETID ........ ________
Natural Logon ... _ (Y/L = Logon, N/' ' = No Logon)
CELSIUS ................. 35______________________________________
CELSIUSTOFAHRENHEITRESULT ________________________________________
33) Press PF5 to execute the call to the Web Service
34) The results should be similar to the following:
CELSIUS ................. 35______________________________________
CELSIUSTOFAHRENHEITRESULT 95______________________________________
Broker Logon
: ok
Calling CELSIUST: success.
Broker Logoff
: ok
NOTE: The messages above indicate that the second test was successful (Celsius to Fahrenheit).
Change the Celsius field and press PF5 to test with different values, or press any other PF-Key to
exit the CELSIUS2 program.
Page 11
Calling a Web Service from Natural
Appendix A
A) Sample Natural RPC Server JCL
//RPMYLIB2 JOB MYJOB,MSGLEVEL=1,
//
CLASS=S,MSGCLASS=X,REGION=4M,NOTIFY=&SYSUID
//*
//NATB0100 EXEC PGM=NAT822BA,
//
COND=(0,LT),
//
PARM=('IM=D,INTENS=1,MADIO=0,MAXCL=0,DU=OFF')
//STEPLIB
DD DSN=NAT822.LOAD,DISP=SHR
//
DD DSN=ADA825.LOAD,DISP=SHR
//
DD DSN=EXX822.LOAD,DISP=SHR
//DDPRINT
DD SYSOUT=*
//DDDRUCK
DD SYSOUT=*
//SYSOUT
DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//DDKARTE
DD DUMMY
//DDCARD
DD *
ADARUN DB=dbid,DE=device,SVC=svcnr,MODE=MULTI
//CMPRINT
DD SYSOUT=*
//CMTRACE
DD SYSOUT=*
//CMPRT01
DD SYSOUT=*
//CMPRT10
DD SYSOUT=*
//TRACE1
DD SYSOUT=*
//CMPRMIN
DD *
STACK=(LOGON MYLIB2)
RPC=(SERVER=ON,RPCSIZE=8000,SRVNAME=SRV2,SRVNODE=ETB1331,MAXBUFF=4000,
TRACE=(0),ACIVERS=9)
//CMSYNIN DD *
//
Page 12