Integrating Web Services and Natural Objects Using EntireX Technical Paper: Calling a Web Service from Natural 4/15/2013 Software AG Global Support Services
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
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
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
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
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
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
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 7
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
- 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
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 10
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 11
A) Sample Natural RPC Server JCL Appendix A //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