Introduction

Web services are self-contained, modular applications that can be described, published, located, and invoked over a network. Web services perform encapsulated business functions ranging from simple request-reply to full business process interactions.

These services can be new applications or wrapped around existing business functions to make them Service Oriented Architecture(SOA) enabled. Services can rely on other services to achieve their goals.

TXSeries for Multiplatforms is a distributed CICS (Customer Information Control System) Online Transaction Processing (OLTP) environment for mixed language applications. It is widely used for integrating data and applications between distributed solutions and enterprise systems, and the deployment of CICS applications written in COBOL, C , C++ and PL/I.

TXSeries For Multiplatforms 7.1 support pac CN01 supports Inbound SOAP requests, wherein existing programs can be exposed as services. When these programs are deployed as services, any SOAP webservice requestor can access these server programs over HTTP.

Back to top

Architecture of Web service in TXSeries

TXSeries uses the above architecture to expose CICS server programs as Web services

Light-weight infrastructure (LWI)

The light-weight infrastructure addresses the need for a minimal footprint, easy to configure, secure infrastructure for hosting web applications and Web services. The Light-weight infrastructure functions as the web request gateway for the TXSeries Web services.

Servlet Engine

The Servlet engine receives SOAP request from the SOAP client, uses URIMapping module, Conversion module and Connector module to get the response and sends back the SOAP response or SOAPFault to the SOAP client.

URIMapping Module

Based on the URI requested by the SOAP client, URIMapping module finds the CICS program, the region it has to connect, and provide these details to the Servlet Engine.

Conversion Module

This is support module for the Servlet Engine, which receives the SOAP Body and converts it to COMMAREA byte buffer and vice versa.

Connector Module

This module actually connects to the TXSeries and calls the CICS program with the COMMAREA byte buffer and receives back the COMMAREA and sends back to Servlet Engine.

DFHLS2WS Tools

Using the DFHLS2WS tools we generate the WSDL and WSBind WSBind artifacts using either command line or Java API options.

Role of WSBind file

TX Series uses information in the WSBind file to perform the mapping between application data structures and SOAP messages at runtime.

Back to top

Sample explained

In the next section we take a simple employee example and take you through the steps which would explain how to configure, deploy and test your Web Services setup with TX Series. We would also take you through some critical commands in the example program which require explanation.

Samples provided along with the article to help configure and test Web service. The setup script(for Unix-Like and Windows platforms),the employee.ccs server program(which retrieves the commarea) and employee.h (the header file) will be provided as a zipped package.

The setup script is provided to generate sample records in SFS server and do required configurations. Snippet from the configuration file doing the required configuration is as follows:

   
cicssdt -s /.:/cics/sfs/sample  -c create Employee sfs_Ssample 
B empId signedInt32 empName string 50 empSalary double  " 
" "10                      " empId Y empId a " " 1 quit

cicssdt -s /.:/cics/sfs/sample -c w Employee 100 Srinivas 7000 
"N" quit

cicsadd -c fd -r sample -P Employee IndexName=empId

The cicssdt command creates a table called Employee defines three fields which are empId, empName and empSalary.

The second cicssdt command inputs the data into the employee table and the cicsadd command adds a file definition entry.

       
EXEC CICS READ FILE("EMPL")
		 INTO(ca) 
		 RIDFLD(&ca->empId)
                   KEYLENGTH(4)
		 RESP(resp);

This reads in the employee details from SFS using the employee ID received through commarea and puts them into response commarea.

The diagram below shows the flow and the explaining where exactly different components resides in:

Back to top

Configuration, deployment and usage

1. CICS region side configurations

First and foremost we need to identify a CICS program that can be exposed as a Web service.

Define Program Definition for this server program in the Region. That is we add a PD (program definition) entry in the TX Series server. The command for that would be:

Cicsadd –c pd –r <region name> <PD entry name> 
Pathname=<Path where the program is kept>
 

Define IPIC Listener Definition in the region.

    
Cicsadd –c ld –r <region name> <LD entry name> 
Protocol=IPIC TCPAddress="<machine IP or hostname>
 

Make an entry in the /etc/services with a port for this service with the service name and Port number. The services file can be found in C:\WINDOWS\system32\drivers\etc and name of the file is services.

Start the CICS region and make sure no errors are seen in the console log.

The console file can be checked in /var/cics_regions/<region_name>/console.000000n (where n is the number of latest console file).

2. Generate artifacts using DFHLS2WS tools

Use DFHLS2WS command line tool or the Java API to generate the artifacts (Wsdl & WSBind). The pre-requisite to deploy TXSeries applications as a Web services is to compile them with 8 byte boundary.

The DFHLS2WS tool simplifies the task of deploying your CICS application as a service provider. When using DFHLS2WS tool, need to start with the language data structures, and use the DFHLS2WS tool to generate the Web service artifacts.

DFHLS2WS tool is a set of jar files which provide facilities to generate required artifacts. To use these facilities, the following jar files should be in the system CLASSPATH.

• common.jar
• common.resources.jar
• ecore.change.jar
• ecore.jar
• ecore.xmi.jar
• NamespaceContext.jar
• woden.jar
• wsdl4j.jar
• XmlSchema.jar
• xsd.jar
• xsd.resources.jar
• cwsa.jar

You can use the DFHLS2WS tool through:

• Using the command-line mode
• Using the Java APIs mode

Using any of the modes described above will generate the following artifacts:

• employee.wsdl
• employee.wsbind
• employee.log

Of the above three artifacts, you need the Wsdl file and the bind file to expose the server program as a Web service. You must configure these two files in the LWI.

The Wsdl file is used by SOAP over HTTP client applications. Bind file is used by TXSeries LWI internally for data manipulation.

• On Windows systems, issue the following command: DFHLS2WS.bat inputParams
• On Unix systems, issue the following command: DFHLS2WS.sh inputParams

Where inputParams is an input file with parameters.

The following sample program illustrates the usage of Java API:

 import com.ibm.cics.gen.api.Factory;
                import com.ibm.cics.gen.api.IAssistantParameters;
                import com.ibm.cics.gen.api.ICICSWebServicesAssistant;
                import com.ibm.cics.gen.api.IAssistantResponse;

                   public class Test {

	        public static void main(String[] args) throws Exception {
	        String structDir = "C:\\test\\CStructures";
	        String structSource = "cstruct.h";
	        String bindFileName =
                            "C:\\test\\CStructures\\employee.wsbind";  
	        String logFileName = 
                            "C:\\test\\CStructures\\employee.log";
	        String wsdlFileName =
                             "C:\\test\\CStructures\\employee.wsdl"; 
	        IAssistantParameters params =
                             Factory.createAssistantParameters(); 

                   params.setParamURI
                   ("http://localhost:8080/txws/myregion/employee");
	        params.setParamLANG(IAssistantParameters.LANG_C);
	        params.setParamPDSLIB(structDir);
	        params.setParamPGMINT
                   (IAssistantParameters.PGMINT_COMMAREA);
	        params.setParamPGMNAME("EMPLOYEE");
	
	        params.setParamMAPPING_LEVEL
                   (IAssistantParameters.MAPPING_LEVEL_2);
	
	        params.setParamREQMEM(structSource);
	        params.setParamRESPMEM(structSource);
	        params.setParamSTRUCTURE("(message, message)");
	        params.setParamWSBIND(bindFileName);
	        params.setParamWSDL(wsdlFileName);
	        params.setParamLOGFILE(logFileName); 
	
	        ICICSWebServicesAssistant cwsa =
                   Factory.createCICSWebServicesAssistant();  
	        IAssistantResponse ar = cwsa.DFHLS2WS(params);
                   System.out.println(
	        "DFHLS2WS:AssistantResponse.getReturnCode():" +
                   ar.getReturnCode());  
	        System.out.println("AssistantResponse.getMessages()");
                   String[] msgs = ar.getAllMessages();
	        for (int i = 0; i < msgs.length; i++)
	        {
	            System.out.println(msgs[i]);
	        }
	        }
                   }

3. Configure the generated artifacts in LWI

Each program needs a <uri-map> entry in TXWSMapping.xml file exists in <TXInstall-Dir>/wui/ws_conf directory. Wsdl and WSBind file needs to be manually copied to the TXSeries <TXInstall-Dir>/wui/ws_conf/<region-name>/ <program-name> directory.

To expose programs as Web services, we need to configure the generated artifacts in LWI of TXSeries installed system to expose the program as web service. Since we have provided http://localhost:8082/txws/myregion/myprog as the URI for generating artifacts by the DFHLS2WS.

1. Since we have provided http://localhost:8082/txws/myregion/myprog as URI for generating artifacts by the DFHLS2WS, we need to create the following directory under <TXSeries install dir>/wui/ws_conf.
myregion/employee
(Ex: /wui/ws_conf/myregion/employee)

Note: The txws directory acts as context root for TXSeries Web services. It is mandatory that every URI must start with txws after host name and port number.

2. Copy the following artifacts to the directory created above

• employee.wsdl
• employee.wsbind

After the artifacts are copied,you need to make an entry for the artifacts in TXWSMapping.xml. A sample file, TXWSMappingSample.xml exists in <TXSeries install dir>/wui/ws_conf directory. You will find a commented sample entry in the file. Copy and paste the sample file <TXSeries install dir>/wui/ws_conf/TXWSMappingSample.xml to <TXSeries install dir>/wui/ws_conf/TXWSMapping.xml

3. Copy the sample file TXWSMappingSample.xml as TXWSMapping.xml and create a<uri-map> entry inside <maps> element.

<maps xmlns="http://www.ibm.com/TXSeries/TXWSMappingSchema">
<uri-maps>
			<map-name>/txws/myregion/myprog</map-name>
      <description> Optional description goes here </description>
			<program-name> myprog</program-name>
			<region-name> myregion</region-name>
			<wsbind>myprog.wsbind</wsbind>
			<wsdl>myprog.wsdl</wsdl>
			<ipic-port>55555</ipic-por>
</uri-map>
</maps>

Note:

• If you are adding another new entry in TXWSMapping.xml then add a new <uri-map> section under <maps> tag.
• The namespace URI http://www.ibm.com/TXSeries/TXWSMappingSchema is mandatory.
• Clients using SOAP over HTTP can access the CICS program as normal Web service.
• Once the server program is deployed successfully, you can view the Wsdl configured by opening a browser and typing the URL with query-string Wsdl as: http://localhost:80/txws/myregion/employee?wsdl.

After all these settings, the client can be started and then the Web service invoked

4. Validate the configurations by viewing the Wsdl from a browser.

Once the configurations are done, the Wsdl can be viewed using a URL: http://<servername>:<LWI-http-port>/<map-name>?wsdl. For example: http://localhost:8082/txws/myregion/AGE?wsdl.

Back to top

Generating Artifacts Using Rational Developer for System z (RDz) 7.6

We will take you through generating artifacts using RDz in this section.

1. First we start with creating a Web Services project. In the RDZ 7.6 wizard,go to File > New > Project. A window "New project" pops-up, select a Web Services Project.

Choose a 'Next' here, and then give a Project Name. Once that is done we choose 'Finish' to complete the project creation exercise.

TXSeries supports bottom-up deployment scenario only, Service Provider mode of Application mode and Interpretive Conversion mode.

The next step is to Import source samples. And once you do that Click 'Finish' to complete the initial step.

2. Once you create the project, the project name could be seen the Left most pane of the wizard. Right click the project name and click on 'Generate Web Services for CICS resources'.

We see a window as shown above popping up. Here we go to both the 'Request language Structure' and 'Response Language Structure' Tab and choose the All-Type check box. We may also wish to change the some COBOL preferences like Code Page Selection and that can be changed using the 'Change COBOL Preferences' Button. We need to make sure that we support only IEEE floating points in COBOL preferences. A screen capture showing COBOL preferences is shown below. Click on 'Apply' and then 'Ok' to return to the 'Language Structures' Window.

After we are done with everything we choose 'Next'.

Here we can change the Program Name. The Program Interface supported by TXseries is only COMMAREA. The Service properties tab contains Namespace properties. We should click on the 'Change WSBind Preferences' and make sure that the mapping Level is set to 2.0.In the DFSLS2WS tab we find some important properties like SOAP version and Wsdl version that by default are set to 1.1.

After that we proceed with choosing 'Next' on the DFHLS2WS:Application and Service Properties Window.

Here we specify names for Wsdl, WSBind and the Log file. Then we click 'Next' and then a finish to complete the 'Generating the artifacts' step. We can verify the artifacts has been created by expanding the Project Name on the left most pane of the wizard.

The generated artifacts can now be used in the same way as described in Step 3 above 'Configure the generated artifacts in LWI'.

Back to top

Conclusion

With the inbound SOA support for TXSeries for Multiplatforms, CICS program running in distributed platforms can be easily exposed as Web Services.The supporting tools makes this transition easy and seamless.

With these feature TXSeries can become an integral part of any SOA based soluion.

Back to top

Downloads

Information about download methods

Resources

Learn

• In the SOA and Web services area on developerWorks, get the resources you need to advance your skills.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

Get products and technologies

• Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Architecture of Web service in TXSeries
• Sample explained
• Configuration, deployment and usage
• Generating Artifacts Using Rational Developer for System z (RDz) 7.6
• Conclusion
• Downloads
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: TXSeries for Multiplatforms
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: TXSeries for Multiplatforms

Dig deeper into SOA and Web services on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers