Sample SOAP Message Handler 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 SOAP message handler on your z/TPF system. This sample demonstrates how to create and deploy SOAP message handlers using the Web Services Deployment Table (WSDT) based deployment mechanism (APAR PJ31953).

The sample SOAP message handler package provides you with a complete SOAP message handler that can be run on your z/TPF system. It performs basic logging functionality for your Web services traffic using the syslog support on z/TPF. You can use it as a starting point for your own SOAP message handlers, 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 message handler package (the “tarball”) to your PC. The name of this package is soap_msghandler_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_msghandler_sample_zTPF.tar.Z soap_msghandler_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 sample SOAP message handler application package by entering the following command:

   cd ~/your_workdir
   tar -xzkf ../soap_msghandler_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 message handler code (csol.c)
      • MakeTPF sample makefile (csol.mak)
   2. In the directory: ~/your_workdir
      • Sample SOAP message handler deployment descriptor for the Sample application (logging.xml).
      • Sample syslog configuration file that can be used with syslogd (syslog.conf).
      • Sample provider Web service deployment descriptor that shows how to include the logging SOAP message handler in the processing for a Web service. This deployment descriptor can be used with the Sample Web Service Wrapper application available for download (CalculatorService_logging.xml).
      • This readme (samplemessagehandler_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 message handler (csob.mak). Verify that the maketpf_env assignments in csol.mak are correct for your build environment.
    
4. Compile and link the SOAP message handler sample program.

   maketpf csol.mak -f 

5. Use the standard load procedure to transfer and load the SOAP message handler sample program (csol) to your test system.

5.0 DEPLOYING

To deploy the sample SOAP message handler, making it accessible to the z/TPF SOAP support, and your Web services, you will need to FTP the SOAP message handler 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 logging.xml /etc/tpf-ws/logging.xml
   • Exit FTP by entering the following command:
     bye


2. On your z/TPF system, deploy the SOAP message handler by entering the following command:

   ZWSAT DEPLOY DD-logging.xml

6.0 RUNNING

To run the SOAP message handler sample sample application you will need to have a deployed Web service including "logging" in its SOAPMessagHandlerChain element in its deployment descriptor. Included in the package for this sample SOAP message handler is a deployment descriptor (CalculatorService_logging.xml) that can be used with the Web service Wrapper sample application that is available for download, that includes the "logging" SOAP message handler.

Once you have a Web service deployed on z/TPF that includes this logging SOAP message handler, you will need to ensure that the syslog daemon is running. This can be done using the ZINET START SERVER-syslogd command. A sample syslog.conf file is included and can be placed in /etc/ to configure syslogd to write out the messages logged by this SOAP message handler sample to the /etc/syslogd/ws-logging.log log file. Note: you may need to create the ws-logging.log file before log entries can be written to it.

After you have deployed the SOAP message handler and a Web service that uses the logging SOAP message handler, they once you start sending SOAP Consumer requests to that service, you will see those messages logged by the syslog daemon. To see the log you can enter the following command: zfile cat /etc/syslogd/ws-logging.log

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.