Using and configuring Web services with TXSeries for Multiplatforms

This article describes and takes you through how to use Web Services with TXSeries. It starts with some basic definitions of terms used very frequently in the article, like Web Services, TXseries. Then moves on to describe the architecture of Web Services in TXseries, explains a Sample that can be used as-is and deployed as a service, then there are steps and processes to generate and configure artifacts using command line, Java API mode. It also describes how to generate the WSBind,Wsdl and log files using RDZ.

Shubhendu Banerjee, Software Engineer, TXSeries for Multiplatforms, IBM

Shubhendu Banerjee has been working with TXSeries for the last couple of years. Before that he worked with the CTG team.He is a middle ware FVT specialist and an agile enthusiast.He has good conference experience as he has participated and presented in multiple forums in and outside India.



John Kurian, Advisory Software Engineer, TXSeries for Multiplatforms, IBM

John Kurian is an Advisory software engineer working for TXSeries for Multiplatforms product as a subject matter expert for Web services implementation. He has been working for this product for the past six years. As an experienced programmer in J2EE technologies, he has been instrumental in the implementation of inbound SOAP support and in the development of web administration console for TXSeries.



Lokanadham Nalla (loknalla@in.ibm.com ), Staff Software Engineer, TXSeries for Multiplatforms, IBM

Lokanadham Nalla is a TXSeries Developer located in India Software Labs, Bangalore, India, has also worked as technical leader for the test team for IBM CICS Transacton Gateway product with expertise in Java, J2EE and Web technologies. He is a co-author of 'Developing Connector Applications for CICS' redbook



25 March 2010

Also available in Japanese

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.

Figure 1. Services
Services

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.


Architecture of Web service in TXSeries

Figure 2. Exposing CICS as Web services
Exposing CICS as Web services

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.


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:

Listing 1. Setup script
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.

Listing 2. Sample employee.ccs
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:

Figure 3. Component locations
Component locations

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.


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.
Figure 4. Create a new Web services for CICS project
Create a new Web services for CICS project

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

Figure 5. Naming the project
Naming the CICS project

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

Figure 6. Import source files
Import source files

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

  1. 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'.
Figure 7. Language structures
Language structures

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.

Figure 8. COBOL preferences
COBOL preferences

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

Figure 9. Application and service properties
Application and service properties

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.

Figure 10. Web Services Assistant (WSBind)
Web Services Assistant (WSBind)

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

Figure 11. Target Artifacts
Target Artifacts

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.

Figure 12. Verifying the Artifacts
Verifying the Artifacts

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


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.


Downloads

DescriptionNameSize
ccs CICS C programemployee.ccs10KB
h Header File for Data Structuresemployee.h10KB
sh Configuration Shell Scriptemployee.sh10KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services
ArticleID=475851
ArticleTitle=Using and configuring Web services with TXSeries for Multiplatforms
publish-date=03252010