Twin City User Group

1

• Twin City User Group

Using Natural and EntireX to Call a Web
Service
Dave Hupp Advisory Systems Engineer
December 3, 2004
2
Intoduction

• Dave Hupp
• Software AG
• System Engineering Services
• Advisory Systems Engineer
• 703-391-6635
• David.Hupp_at_softwareagusa.com

3
Background

• Working at Software AG for 6 Years
• Primary doing System/Enterprise Integration
• System Experience
• Mainframe
• UNIX (HP, AIX, SUN)
• Windows
• Database Experience
• ADABAS
• Oracle

4
Agenda

• Overview of the Web Service architecture
• SOAP
• Web Services Description Language (WSDL)
• Creating a mainframe Web Service
• Using the EntireX Workbench to create a Web
  Service
• Deploying the XML Servlet environment
• Steps to create a Natural program to call a Web
  Services
• Demonstration - Natural Client to call a Web
  Service

5
Web Services Architecture
Web Service Provider
Web Service Client
 
 
Server Object
Web Server
Application Code
WSDL
WSDL
HTTP Get
SOAP Toolkit
SOAP Handler
SOAP
HTTP Post
SOAP Toolkit
6
Web Services Defined

• Web Services are
• Self-describing, self-contained modular
  applications
• Platform independent
• Built using open standards for description,
  discovery, and invocation (e.g., WSDL, SOAP,
  HTTP)
• Programmatically connects business processes
• Provides integration with existing systems
• Web Services perform business functions
• Uses simple request/reply communication

7
Web Services Defined (continued)

• Web Services
• Can be mixed and matched to create complete
  processes
• Enable dynamic integration
• Can be a new application or use an existing
  application

8
Web Services Standards
Registry
Web ServiceBroker
UDDI
           
Discover Service
Publish Service Description
Get Service Description
SOAP
SOAP
Server
Client
SOAP
ServiceDescription
Web ServiceProvider
Web ServiceRequester
WSDL
Use Service Based on Service Description
9
SOAP

• SOAP originally stood for Simple Object Access
  Protocol.
• SOAP specification now does not mandate the use
  of objects anymore
• W3C now says SOAP has no special meaning
• SOAP still accepted protocol for Web Services

10
SOAP (cont)

• XML based protocol used for exchanging
  information between computers.
• RPC based communication model (request/reply)
• Uses HTTP transport protocol
• Transport protocol-independent
• Basically program-to-program communication using
  HTTP

11
SOAP Envelope
SOAP envelope
ltSOAP-ENVEnvelope attributesgt
SOAP-ENVHeadergt header elements
lt/SOAP-ENVHeadergt
SOAP header
ltSOAP-ENVBodygt body elements
lt/SOAP-ENVBodygt
SOAP body
lt/SOAP-ENVEnvelopegt
12
SOAP Create Envelope
SOAP-ENVEnvelope xmlnsSOAP-ENV"http//schemas.x
mlsoap.org/soap/envelope/" xmlnsSOAP-ENC"http/
/schemas.xmlsoap.org/soap/encoding/"
xmlnsxsihttp//www.w3.org/2001/XML
Schema-instance xmlnsxsd"http//www.w3.org/2001
/XMLSchema"gt ltSOAP-ENVBodygt ltmPersread
xmlnsm"urncom-softwareag-entirex-rpcWEBSERV"
SOAP- ENVencodingStyle"http//schemas
.xmlsoap.org/soap/encoding/"gt
ltPersonnel-ID xsitype"xsdstring"gtStringlt/Person
nel-IDgt ltFirst-Name
xsitype"xsdstring"gtStringlt/First-Namegt
ltName xsitype"xsdstring"gtStringlt/Namegt
ltSex xsitype"xsdstring"gtStringlt/Sexgt
ltCity xsitype"xsdstring"gtStringlt/City
gt lt/mPersreadgt lt/SOAP-ENVEnvelopegt
lt/SOAP-ENVBodygt
13
SOAP Request
lt?xml version"1.0"?gt SOAP-ENVEnvelope
xmlnsSOAP-ENV"http//schemas.xmlsoap.org/soap/en
velope/" xmlnsSOAP-ENC"http//schemas.xmlsoap.o
rg/soap/encoding/" xmlnsxsihttp//www.w3.org/20
01/XML Schema-instance xmlnsxsd"http//www.w3.o
rg/2001/XMLSchema"gt ltSOAP-ENVBodygt
ltmPersread xmlnsm"urncom-softwareag-entirex-rp
cWEBSERV" SOAP- ENVencodingStyle"htt
p//schemas.xmlsoap.org/soap/encoding/"gt
ltPersonnel-ID xsitype"xsdstring"gt50005800lt/
Personnel-IDgt ltFirst-Name
xsitype"xsdstring"gtStringlt/First-Namegt
ltName xsitype"xsdstring"gtStringlt/Namegt
ltSex xsitype"xsdstring"gtStringlt/Sexgt
ltCity xsitype"xsdstring"gtStringlt/City
gt lt/mPersreadgt lt/SOAP-ENVEnvelopegt
lt/SOAP-ENVBodygt
14
SOAP Response
lt?xml version"1.0" encoding"UTF-8"?gt ltSOAP-ENV
Envelope SOAP- ENVencodingStyle"http//schemas.x
mlsoap.org/soap/encoding/" xmlnsSOAP-
ENC"http//schemas.xmlsoap.org/soap/encoding/"
xmlnsxsi"http//www.w3.org/2001/XMLSchema-insta
nce" xmlnsxsdhttp//www.w3.org/2001/XML
Schema xmlnsSOAP- ENV"http//schemas.xmlsoap.or
g/soap/envelope/"gt ltSOAP-ENVBodygt
ltmPersreadResponse xmlnsm"urncom-softwareag-en
tirex-rpcWEBSERV"gt ltPersonnel-ID1
xsitype"xsdstring"gt50005800lt/Personnel-ID1gt
ltFirst-Name1 xsitype"xsdstring"gtSIM
ONElt/First-Name1gt ltName1
xsitype"xsdstring"gtADAMlt/Name1gt
ltSex1 xsitype"xsdstring"gtFlt/Sex1gt
ltCity1 xsitype"xsdstring"gtJOIGNYlt/City1gt
lt/mPersreadResponsegt
lt/SOAP-ENVBodygt lt/SOAP-ENVEnvelopegt  
15
SOAP Encoding
lt?xml version"1.0" encoding"UTF-8"?gt
SOAP-ENVEnvelope xmlnsSOAP-ENV"http//schemas.
xmlsoap.org/soap/envelope/" xmlnsSOAP-ENC"http
//schemas.xmlsoap.org/soap/encoding/"
xmlnsxsihttp//www.w3.org/2001/XML
Schema-instance xmlnsxsd"http//www.w3.org/2001/
XMLSchema"gt ltSOAP-ENVBodygt
ltmgetPriceResponse xmlnsm"urnexamplepriceserv
ice"gt ltReturn xsitypexsddoublegt75.99lt
/Returngt lt/mgetPriceResponsegt
lt/SOAP-ENVBodygt lt/SOAP-ENVEnvelopegt
SOAP Response with a Data Type of Double
16
SOAP Client Toolkits

• Microsoft SOAP Toolkit 2.0
• Apache Soap Toolkit
• Microsoft .NET
• Other SOAP Toolkits avaiable

17
Web Service Description

• What is a WSDL ?
• WSDL stands for Web Services Description
  Language
• Basically an XML document that describes a Web
  Services

           
           
18
WSDL Specification

• A WSDL is platform and language independent
• Used to describe web services
• The five components the make up the WSDL
• Definitions
• Types
• Message
• Port type
• Binding
• Service

19
WSDL Specification

• Definitions
• Root element of WSDL defining the name of Web
  Service, declares multiple namespaces used in
  document, and contains all service elements.

ltdefinitions namePersread' targetNamespace'htt
p//namespace.softwareag.com/entirex/xml/mapping
xmlns'http//schemas.xmlsoap.org/wsdl/'
xmlnsxsd'http//www.w3.org/2001/XMLSchema xmln
ssoap'http//schemas.xmlsoap.org/wsdl/soap/ xml
nswsdl'http//schemas.xmlsoap.org/wsdl/
xmlnsSOAP-ENC'http//schemas.xmlsoap.org/soap/en
coding/ xmlnstns'http//namespace.softwareag.co
m/entirex/xml/mapping'
20
WSDL Specification

• Types
• Elements describing data types between client and
  server. Uses W3C XML Schema specification.

lttypesgt ltschema targetNamespace'http//namespa
ce.softwareag.com/entirex/xml/mapping'
xmlns'http//www.w3.org/2001/XMLSchema'gt
lt/schemagt lt/typesgt
21
WSDL Specification

• Message
• Describes a one way message either a single
  message request or single message response.

ltmessage name'Persread'gt ltpart
name'Personnel-ID' type'xsdstring'/gt
ltpart name'First-Name' type'xsdstring'/gt
ltpart name'Name' type'xsdstring'/gt ltpart
name'Sex' type'xsdstring'/gt ltpart
name'City' type'xsdstring'/gt lt/messagegt
ltmessage name'PersreadResponse'gt ltpart
name'Personnel-ID1' type'xsdstring'/gt
ltpart name'First-Name1' type'xsdstring'/gt
ltpart name'Name1' type'xsdstring'/gt
ltpart name'Sex1' type'xsdstring'/gt ltpart
name'City1' type'xsdstring'/gt
22
WSDL Specification

• Port type
• Combines multiple message elements to form a
  complete one-way or roundtrip operation.

ltportType namePersreadPort'gt ltoperation
name'Persread'gt ltinput
message'tnsPersread'/gt ltoutput
message'tnsPersreadResponse'/gt
lt/operationgt lt/portTypegt
23
WSDL Specification

• Binding
• How the service will be implemented on the wire
• Contains the SOAP specific information

ltbinding name'SystemSoapBinding'
type'tnsSystemPort'gt ltsoapbinding style'rpc'
transport'http//schemas.xmlsoap.org/soap/http'/gt
ltoperation name'Persread'gt ltsoapoperation
soapAction'Persread'/gt ltinputgt ltsoapbody
use'encoded' encodingStyle'http//schemas.xmlsoa
p.org/soap/encoding/' namespace'urnhttp//namesp
ace.softwareag.com/entirex/xml/mapping
/gt lt/inputgt
24
WSDL Specification

• Service
• Defines the URL address for invoking the SOAP
  service

ltservice name'persread'gt ltport
name'SystemPort' binding'tnsSystemSoapBinding'gt
ltsoapaddress location'http//localhost8080/en
tirex/xmlrt'/gt lt/portgt lt/servicegt
lt/definitionsgt
25
Steps for Creating a Mainframe Web Service

• Server
• Define the RPC server (Class/Server/Service) to
  Broker
• Set up the Natural RPC server to run as a batch
  job
• Start the RPC server
• Write the Natural subprogram

26
Steps for Creating a Mainframe Web Service

• Client
• Create/generate the IDL file
• Set the properties for the IDL file
• Define the XML mapping
• Create the XMM file
• Add the XMM file to the Servlet container
• Develop the client front-end

27
Using the EntireX Workbench

• Now lets walk through the steps using the EntireX
  Workbench to create the a Web Service
• XMM File
• SOAP
• WSDL

28
IDL File
Properties
IDL
29
Define XML Mapping
30
Define SOAP Mapping
31
Define SOAP Mapping
32
Create the XMM File
33
Create the WSDL
34
Create the WSDL Step 1
35
Create the WSDL Step 2
36
Create the WSDL Step 3
37
Create the WSDL
38
Deploy the EntireX Servlet

• Install Tomcat in your environment
• Copy the entirex.war file into the Tomcat WebApps
  folder.
• Start Tomcat
• In the Tomcat \bin directory, there is a
  startup.bat file. Also a shutdown.bat file.
• An EntireX application folder will be built along
  with the necessary configuration files and jar
  files.
• In Web Sphere, import the entirex.war file and
  follow the Web Sphere procedures for creating the
  application.

39
Deploy the EntireX Servlet (cont)

• The xml-init.xml configuration file is where
  the XMM mapping files are placed.
• The xml-init.xml file is loaded when Tomcat is
  started and makes the XMM files available to the
  EntireX servlet.

lt?xml version"1.0" encoding"utf-8"?gt ltEntireXXML
Init Version"7.1.1 xmlns"http//namespaces.sof
twareag.com/entirex/xml/rt"gt ltxmmsgt
ltexx-xmmgt/webserv.xmmlt/exx-xmmgt
ltexx-xmmgt/example.xmmlt/exx-xmmgt
ltexx-xmmgt/zipcodes.xmmlt/exx-xmmgt
ltexx-xmmgt/persread.xmmlt/exx-xmmgt
lt/xmmsgt lt/EntireXXMLInitgt
40
Calling a Web Service from Natural

• Basic Steps
• Get the WSDL from the Web Service Provided
• Import the WSDL into the EntireX Workbench
• Generate the XML and SOAP mappings
• Save the IDL-XML file mapping
• This generates the XMM file
• Configure the XML RPC Server
• Copy the XMM file to a directory where the XML
  RPC Server can load the XMM file
• Configure Natural to perform RPC call to XML RPC
  Server
• Write a Natural program to call the web service
• The IDL file generated by the WSDL import will
  provide the Natural PDA information

41
Natural Calling a Web Service - Diagram
Web Service Provider
Mainframe
SOAP Response
SOAP Request
EntireX XML RPC Server
Register to Broker
Broker
RPC XMLSRV CALLNAT
GeneratedXML Mapping File(s) Loaded by XML RPC
Server at Startup Time
Special Configuration Required
Natural Client
42
Calling a Web Service from Natural Step1

• Get the WSDL from the Web Service Provided
• The WSDL is needed determine the layout of the
  Web Service
• Copy the WSDL to your computer
• The Natural program will be written based on this
  layout

43
Calling a Web Service from Natural Step 2

• Import the WSDL into the EntireX Workbench
• Use the EXX Workbench to Import the WSDL
• The IDL file will be generated from the imported
  WSDL

44
Calling a Web Service from Natural Step 3

• Generate the XML and SOAP mappings
• In the EXX Workbench
• Click on XML Tab
• Select Define XML Mapping
• Select SOAP 1.1 Mappings for all Programs
• Save the IDL-XML Mapping file
• This generates the XMM file

45
Calling a Web Service from Natural Step 4

• Configure the XML RPC Server
• XML RPC Server works the same in UNIX and Windows
• Example in C\Program Files\Software
  AG\EntireX\Bin jxmlrpcserver.bat
• Add the following parameter Dentirex.trace2 in
  the jxmlrpcserver.bat file.
• Tracing is Extremely useful in diagnosing
  problems with the XML RPC Server and SOAP
  Request/Response.
• Copy the entirex.trace.standard file found in
  C\Program Files\Software AG\EntireX\Etc into the
  same directory as jxmlrpcserver.bat
• Rename it to entirex.trace.properties

46
Calling a Web Service from Natural Step 4

• Configure the XML RPC Server (cont)
• Edit the entirex.trace.properties file
• Change entirex.sdk.default.trace.level to
  ADVANCED and entirex.sdk.default.trace.filename
  to something other than STDOUT or STDERR
• The Name does not matter, the trace file will
  always be named exx.sdk.xml.runtime.log
• Edit the entirex.xml.runtime.configuration.xml
  file
• Located in C\Program Files\Software
  AG\EntireX\Etc
• XMM file name
• Target Server of Web Service
• Broker-ID
• Service Definition

47
Calling a Web Service from Natural Step 4

• Configure the XML RPC Server (cont)
• Example jxmlrpcserver.bat with trace

_at_setlocal _at_rem starts a xml rpc server _at_rem _at_rem
set own Java Runtime Environment, if exists. _at_rem
Otherwise use JAVA_HOME _at_if exist
"SAG_COMMON\jre1.3.1\bin\java.exe" set
JAVA_HOMESAG_COMMON\jre1.3.1 _at_if not exist
"JAVA_HOME\bin\java.exe" set JAVA_HOME_BIN _at_if
exist "JAVA_HOME\bin\java.exe" set
JAVA_HOME_BINJAVA_HOME\bin\ _at_echo JAVA_HOME
JAVA_HOME SET EXXDIRC\PROGRA1\SOFTWA1\
EntireX _at_set EXXCLSEXXDIR\classes\entirex.jar
EXXDIR\classes\xercesImpl.jar EXXDIR\classes\x
mlParserAPIs.jar _at_echo EntireX Runtime
EXXCLS _at_"JAVA_HOME_BINjava" -Dentirex.trace2
-classpath "EXXCLS" com.softwareag.entirex.xml.
rt.XMLRPCServer -p /../etc/entirex.xml.runtime.pr
operties -c /../etc/entirex.xml.runtime.configurat
ion.xml _at_endlocal
48
Calling a Web Service from Natural Step 4

• Configure the XML RPC Server (cont)
• Example of entirex.trace.properties file

EntireX SDK Trace settings Wed Dec 13 105222
GMT0100 2000 to activate rename to
'entirex.trace.properties' !!! trace.level
NONE, STANDARD or ADVANCED
trace.directory output directory, '.'
means path of working directory.
If necessary, another path will
created. trace.filename any name, BUT
two reserved words
STDOUT or STDERR for direct output to the
console. trace.threadoriented true or false,
if true, for each
thread a separate file will be created.
'default', settings for all components, can be
replaced by special componentname(s), like
'xml.runtime' or 'xml.servlet'.
---------------------------- entirex.sdk.default.t
race.level ADVANCED entirex.sdk.default.trace.di
rectory . entirex.sdk.default.trace.filename
XMLtrace entirex.sdk.default.trace.threadoriented
false
49
Calling a Web Service from Natural Step 4

• Configure the XML RPC Server (cont)
• Example of entirex.xml.runtime.configuration.xml
  file

lt?xml version"1.0" encoding"iso-8859-1" ?gt
ltEntireX xmlns"http//namespaces.softwareag.co
m/entirex/xml/runtime/configuration"
version"7.1.1"gt ltXmlRuntime Version"1"gt
ltBrokerInfogt ltBrokerIdgtETB0011971lt/BrokerIdgt
ltServerAddressgtRPC/XMLSERV/CALLNATlt/ServerAddr
essgt ltLogical_BrokerIdgtlt/Logical_BrokerIdgt lt
Logical_Servicegtlt/Logical_Servicegt ltLogical_Set
Namegtlt/Logical_SetNamegt ltOptions
/gt lt/BrokerInfogt ltTargetServer
name"http//services.xmethods.net80/soap/servlet
/rpcrouter"gt ltxmmsgt ltexx-xmm
name"../etc/TemperatureService.xmm"
/gt lt/xmmsgt lt/TargetServergt lt/XmlRuntimegt lt/E
ntireXgt
50
Calling a Web Service from Natural Step 5

• Copy the XMM file
• In Step 3 we created and saved an XMM file
• Copy this XMM file to a location where it can be
  loaded by the XML RPC Server.

51
Calling a Web Service from Natural Step 6

• Configure Natural to perform the RPC call
• Start the Natural session with the following
  parameters
• RPC(RPCSIZE32,MAXBUFF28,AUTORPCON,COMPR2,
• DFS(SrvName, SrvNode,L))
• AUTORPC will cause the automatic stub generation
  for all unresolved (NAT0082) CALLNAT errors and
  assumes that the subprogram call will be handled
  by an XML RPC server
• COMPR deals with RPC buffer compression. As of
  October 2004, this needs to be set or an error
  will occur (data will not be displayed to the
  Natural Client
• SrvName is the name of the XML RPC Server
• SrvNode is the Broker-ID
• The parameter "L" is the Logon Indicator
  (neededif library name is something other than
  SYSTEM

52
Calling a Web Service from Natural Step 7

• Write a Natural program to call the web service
• The IDL file generated by the WSDL import will
  provide the Natural PDA information
• Write the natural program to call the Web Service

53
Natural Calling a Web Service - Diagram
Web Service Provider
Mainframe
SOAP Response
SOAP Request
EntireX XML RPC Server
Register to Broker
Broker
RPC XMLSRV CALLNAT
GeneratedXML Mapping File(s) Loaded by XML RPC
Server at Startup Time
Special Configuration Required
Natural Client
54
Demonstration

• Natural calling a Web Service

55
Summary

• Discussed the Web Service architecture
• Reviewed SOAP and the components of SOAP
• Reviewed the Web Services Description Language
  (WSDL) and the components that make up a WSDL
• Reviewed the steps to create a mainframe Web
  Service
• Described the steps for using the EntireX
  Workbench to create a Web Service
• Reviewed how to deploy the XML Servlet
  environment
• Identified the steps to create a Natural program
  to call a Web Services
• Demonstration

56
Questions