Sample SOAP Bridge Wrapper on z/TPF Enterprise Edition V1.1

Copyright International Business Machines Corporation, 2007. All Rights Reserved.

Note to US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Note: Before using this information and the product it supports, read the general information under "NOTICES" in this document.

CONTENTS

This file includes the following information:

1.0 ABOUT THIS README
2.0 SYSTEM REQUIREMENTS
3.0 DOWNLOADING
4.0 COMPILING, LINKING AND LOADING
5.0 DEPLOYING
6.0 RUNNING
7.0 NOTICES
7.1 Trademarks

1.0 ABOUT THIS README

This readme file will guide you through the process of downloading, installing, and using a sample Web service wrapper on your z/TPF system. This sample application demonstrates how to use the Web Services Deployment Table (WSDT) based deployment mechanism as well as the z/TPF SOAP bridge application programming interfaces (APIs) (APAR PJ31953).

The Sample SOAP bridge wrapper package provides you with a complete sample that can be run on your z/TPF system. You can use it as a starting point for your own Web service wrappers, use it for training purposes, or use it as-is. Go to the IBM TPF Product Information Center for more details about SOAP support.

Note: The TPF development lab does not maintain this application and will not accept APARs on this code.

2.0 SYSTEM REQUIREMENTS

Before proceeding with these instructions, ensure that PJ31953 has been applied to your z/TPF system and that at least one SOAP Communications binding has been installed on your z/TPF system. Two sample SOAP communications bindings are available for download at www.ibm.com/tpf/download/ztpfsoap.htm.

3.0 DOWNLOADING

To download this module, do the following:

1. Click the Download now button to download the compressed sample SOAP bridge wrapper package (the “tarball”) to your PC. The name of this package is soap_bridge_sample_zTPF.tar.Z.


2. FTP the tarball to your home directory on your Linux system using binary mode:
   • Open an MS-DOS window and activate FTP by using the following command:
     ftp your.linux.build.machine.com
   • Sign in using your user name and password.
   • Set the mode to binary by entering the following command:
     binary
   • Send the file to your Linux system by using the following command:
     send c:\your_path\soap_bridge_sample_zTPF.tar.Z soap_bridge_sample_zTPF.tar.Z
   • Exit FTP by entering the following command:
     bye


3. On your Linux system, create a working directory in your root directory by entering the following command:

   mkdir ~/your_workdir

4. Change to the working directory and extract the program files from the SOAP bridge wrapper sample application package by entering the following command:

   cd ~/your_workdir
   tar -xzkf ../soap_bridge_sample_zTPF.tar.Z

   After you have completed this step, you will have the following files on your Linux system:

   1. In the directory: ~/your_workdir/soap
      • Sample z/TPF SOAP bridge wrapper application code (qsbs.c)
      • MakeTPF sample makefile (qsbs.mak)
   2. In the directory: ~/your_workdir
      • Sample Provider Web service deployment descriptor for the sample application (zTPFCommandService.xml).
      • Sample Web Service Description Language (WSDL) for the sample application (zTPFCommandService.wsdl).
      • Sample client for the sample application (samplesoapbridge_client.html).
      • This readme (samplesoapbridge_readme.htm).

4.0 COMPILING, LINKING, AND LOADING

1. Change to the 'soap' directory:

   cd ~/your_workdir/soap

2. Create a maketpf configuration file named maketpf.cfg.
   
   • Ensure that the first assignment of TPF_ROOT in maketpf.cfg is the absolute path to your "~/your_workdir" directory.
     
   • Ensure that the first assignment of APPL_ROOT in maketpf.cfg is the absolute path to your "~/your_workdir" directory.
     
   • Update other fields (TPF_BSS_NAME, TPF_SS_NAME, USER_VERSION_CODE) if necessary.
     
     
3. Edit the sample maketpf .mak file for the sample SOAP bridge wrapper (qsbs.mak). Verify that the maketpf_env assignments in qsbs.mak are correct for your build environment.
    
4. Edit the sample SOAP bridge wrapper (qsbs.c) to include a list of LNIATAs that are available for use by SOAP bridge support on your z/TPF system. Ensure that the selected LNIATAs are registered in the CRAS table by using the ZACRS command.
    
5. Compile and link the SOAP bridge wrapper sample program.

   maketpf qsbs.mak -f 

6. Use the standard load procedure to transfer and load the SOAP bridge wrapper program (QSBS) to your test system.

5.0 DEPLOYING

To deploy the sample SOAP bridge wrapper, making it accessible to the z/TPF SOAP handler, you will need to FTP the provider Web service deployment descriptor to your z/TPF system and use the ZWSAT DEPLOY command.

1. FTP the provider Web service deployment descriptor to the /etc/tpf-ws/ directory on your z/TPF system using binary mode:
   • Change to the "~/your_workdir" directory:
     cd ~/your_workdir
   • FTP by using the following command:
     ftp your.zTPF.system
   • Sign in using your user name and password.
   • Set the mode to binary by entering the following command:
     binary
   • Send the file to your z/TPF system by using the following command:
     send zTPFCommandService.xml /etc/tpf-ws/zTPFCommandService.xml
   • Exit FTP by entering the following command:
     bye


2. On your z/TPF system, deploy the Provider Web service by entering the following command:

   ZWSAT DEPLOY DD-zTPFCommandService.xml

   Note: You must have completed Step 4 prior to issuing the ZWSAT DEPLOY command.

6.0 RUNNING

To run the SOAP bridge wrapper sample application using the zTPFCommandService.wsdl, you will need an HTTP server (e.g. Apache) and a SOAP communications binding for your HTTP server to interact with the z/TPF SOAP support. To use the zTPFCommandService.wsdl file you will need to edit it to fill in the location of your z/TPF system's HTTP server (update the location attribute of the wsdlsoap:addresss element, currently set to http://xxx.xxx.xxx.xxx/).

Once you have edited the zTPFCommandService.wsdl file, it can be used by tooling to generate SOAP Consumer requests for this sample Web service. The IBM TPF Toolkit for Websphere Studio V3.2 contains a Web services explorer that can take a WSDL file as input and generate an HTML form so that you can generate and send individual SOAP Consumer requests to your z/TPF system. See Testing WSDL documents and Web services using the WSDL Explorer in the IBM TPF Toolkit Information Center for more details.

Alternatively, you can use the included samplesoapbridge_client.html page to send SOAP Consumer requests to this service. To use this client you will need to transfer the file to a PC and open it with Microsoft Internet Explorer Version 5 or later and follow the instructions.

7.0 NOTICES

IBM may not offer the products, services, or features discussed in this information in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this information. The furnishing of this information does not give you any license to these patents. You can send license inquiries, in writing, to:

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

7.1 Trademarks

IBM is a trademark of International Business Machines Corporation in the United States, other
countries, or both.