Integrating Web Services and Natural Objects Using EntireX

Integrating Web Services and

Natural Objects Using EntireX

Technical Paper: Calling a Web Service from Natural

4/15/2013

Software AG

Page 1

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:

Page 2

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”:

Page 3

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 4

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 5

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.

Page 6

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 7

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 Type S/C SM Version User ID Date Time *________ *__________ *__ * *______ *________ *__________ *________

CELSIUST Subprogram S S 8.2.02 MYUID 2013-04-04 11:14:53 CELSIUS1 Parameter S S 8.2.02 MYUID 2013-04-04 11:14:53 CELSIUS2 Program S S 8.2.02 MYUID 2013-04-04 11:14:53 FAHRENHE Subprogram S S 8.2.02 MYUID 2013-04-04 11:14:52 FAHRENH1 Parameter S S 8.2.02 MYUID 2013-04-04 11:14:52 FAHRENH2 Program S S 8.2.02 MYUID 2013-04-04 11:14:52 TEST Text 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 8

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 9

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 10

29) Run program FAHRENH2 from Natural Library MYLIB2, and provide the data requested, for example:

EntireX RPC Template - Natural FAHRENHE Client Node name ... ETB1331

Server name ... XMLGETTEMP______________________ RPC Library ... __________________________________________________ Compression ... _ Encryption ... 0 EntireX Authentication RPC Server Authentication User id ... MYUID___ RPC User id .... ________ Password ... RPC Password .... RPC 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 11

32) Run program CELSIUS2 from Natural Library MYLIB2, and provide the data requested, for example:

EntireX RPC Template - Natural FAHRENHE Client Node name ... ETB1331

Server name ... XMLGETTEMP______________________ RPC Library ... __________________________________________________ Compression ... _ Encryption ... 0 EntireX Authentication RPC Server Authentication User id ... MYUID___ RPC User id .... ________ Password ... RPC Password .... RPC 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 12

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 * //