Uploaded on

 

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
206
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
0
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. Artix Mainframe TM Service-Enabling DB2 SQL Version 5.0, July 2007 Making Software Work TogetherTM
  • 2. IONA Technologies PLC and/or its subsidiaries may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this publication. Except as expressly provided in any written license agreement from IONA Technologies PLC, the furnishing of this publication does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Any rights not expressly granted herein are reserved. IONA, IONA Technologies, the IONA logos, Orbix, Artix, Making Software Work Together, Adaptive Runtime Technology, Orbacus, IONA University, and IONA XMLBus are trademarks or registered trademarks of IONA Technologies PLC and/or its subsidiaries. Java and J2EE are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. CORBA is a trademark or registered trademark of the Object Management Group, Inc. in the United States and other countries. All other trademarks that appear herein are the property of their respective owners. IONA Technologies PLC makes no warranty of any kind to this material including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. IONA Technologies PLC shall not be liable for errors contained herein, or for incidental or consequential damages in connection with the furnishing, perform- ance or use of this material. COPYRIGHT NOTICE No part of this publication may be reproduced, stored in a retrieval system or transmitted, in any form or by any means, photocopying, recording or otherwise, without prior written consent of IONA Technologies PLC. No third party intellectual property right liability is assumed with respect to the use of the information contained herein. IONA Technologies PLC assumes no responsibility for errors or omissions contained in this book. This publication and features described herein are subject to change without notice. Copyright © 2001-2007 IONA Technologies PLC. All rights reserved. All products or services mentioned in this manual are covered by the trademarks, service marks, or product names as designated by the companies who market those products. Updated: July 4, 2007
  • 3. Contents List of Figures 5 List of Tables 7 Preface 9 Chapter 1 Process and Demonstration Overview 15 Sample Demonstration 16 Process Summary 17 Graphical Overview of Deployment Process 18 Grapical Overview of Runtime Invocations 19 Chapter 2 Starting the DB2 Gateway Service 21 Introduction to Starting the DB2 Gateway Service 22 Starting the DB2 Gateway Service 24 Checking the DB2 Gateway Service is Running Successfully 29 Chapter 3 Defining and Uploading DB2 Operations to z/OS 31 Summary of Steps 33 Starting Artix Designer 34 Opening the Artix Mainframe Perspective 37 Creating a z/OS Project from DB2 39 Viewing the Project Summary 42 Working with the Artix Mainframe Perspective 44 Managing Site Details 46 Creating Operations 49 Renaming Operations 53 Deleting Operations 55 Testing Operations and Viewing Results 56 Uploading Operations to z/OS 58 Retrieving or Removing Operations from z/OS 59 Publishing WSDL from the DB2 Gateway Service 62 3
  • 4. CONTENTS Chapter 4 Developing and Running a Web Service Client 65 Versions of the Client Demonstration 66 Artix C++ Client Example 67 Client Output 72 Index 73 4
  • 5. List of Figures Figure 1: Deploying DB2 SQL Queries as Web Services 18 Figure 2: Invoking on DB2 SQL Query as Web Service 19 Figure 3: Workspace Selection 34 Figure 4: The Welcome Screen 35 Figure 5: The Artix Mainframe Perspective 38 Figure 6: Selecting a Project Wizard 39 Figure 7: Specifying General Project Details 40 Figure 8: Example of Project Summary for DB2 SQL 42 Figure 9: Adding a New DB2 Gateway Service Site 46 Figure 10: Editing Site Details 47 Figure 11: DB2 Configuration View 49 Figure 12: Renaming an Operation 53 Figure 13: Example of SQL Results for DB2 View 56 Figure 14: Uploading DB2 Operations to z/OS 58 Figure 15: Resolving operation name conflicts 60 5
  • 6. LIST OF FIGURES 6
  • 7. List of Tables 7
  • 8. LIST OF TABLES 8
  • 9. Preface What is Covered in This Book This book discusses how to use Artix Mainframe to expose DB2 SQL statements and stored procedures as Web services. Who Should Read This Book This book is intended for Artix Mainframe users who wish to expose DB2 SQL statements and stored procedures as Web services. Prerequisites See the Artix Mainframe Installation Guide for a full list of supported platforms, supported compilers, and other prerequisites relating to the use of Artix Mainframe. Standards Compliance Artix Mainframe complies with the following specifications: • The W3C specification for SOAP 1.1. • The W3C specification for HTTP 1.0 and 1.1. • The W3C specification for WSDL 1.1. • The Web Services Interoperability Organisation Specification, Basic Profile Version 1.0. • The OASIS Web Services Security UsernameToken Profile 1.0 specification for credentials checking in SOAP headers. • The HTTP tunnel CONNECT specification as outlined in RFC 2817 for secure client proxy support. 9
  • 10. PREFACE The Artix Mainframe Library The Artix Mainframe documentation library includes the following books: • Introduction to Artix Mainframe • Getting Started • Service-Enabling Existing z/OS Applications • Creating New z/OS Applications from WSDL • Creating New z/OS Applications from IDL • Service-Enabling DB2 SQL • Common User Tasks • Administrator’s Guide Introduction to Artix Mainframe The Introduction to Artix Mainframe guide provides an introductory overview of Artix Mainframe in terms of its components and the various integration solutions that it supports. It also provides an introductory overview of Web services and CORBA technology in general. Getting Started The Getting Started guide is intended to help you get started quickly with Artix Mainframe. It provides demonstration walkthroughs of the various integration solutions that Artix Mainframe supports. Service-Enabling Existing z/OS Applications The Service-Enabling Existing z/OS Applications guide explains how to use Artix Mainframe to expose existing mainframe applications as Web services or CORBA servers or both. Creating New z/OS Applications from WSDL The Creating New z/OS Applications from WSDL guide explains how to use Artix Mainframe to create CICS or IMS-based COBOL or PL/I Web services starting from WSDL. It also explains how to create z/OS-based COBOL or PL/I Web service clients starting from WSDL. Creating New z/OS Applications from IDL The Creating New z/OS Applications from IDL guide explains how to use Artix Mainframe to create z/OS-based COBOL or PL/I Artix CORBA clients starting from IDL. 10
  • 11. PREFACE Service-Enabling DB2 SQL This is the book you are currently reading. It explains how to use Artix Mainframe to expose DB2 SQL statements and stored procedures as Web services. Common User Tasks The Common User Tasks guide explains how to use Artix Mainframe to perform various common tasks that are not specific to any particular integration solution. It is provided as an addendum to the other user guides. Administrator’s Guide The Administrator’s Guide describes how to set up and configure the various features of Artix Mainframe. It also discusses the various levels of security that can be used in the product. Organisation of This Book This book contains the following chapters: Chapter 1, “Process and Demonstration Overview” This chapter provides an introductory overview of the overall process you must follow with Artix Mainframe, to expose and subsequently invoke on a DB2 SQL statement or stored procedure as a Web service. It also provides an overview of the sample demonstrations this chapter uses to demonstrate this process. Chapter 2, “Starting the DB2 Gateway Service” This chapter describes how to start the DB2 gateway service. Chapter 3, “Defining and Uploading DB2 Operations to z/OS” This chapter describes how to use Artix Designer to define the SQL statements and stored procedure calls that form the basis of the DB2 operations that you want to expose as Web services. It also describes how to use Artix Designer to upload these DB2 operations to the DB2 gateway service on z/OS. Chapter 4, “Developing and Running a Web Service Client” For the purposes of illustration, this chapter describes how to write, build and run the supplied client demonstrations to invoke on the DbSample demonstration Web service that you have exposed. 11
  • 12. PREFACE Getting the Latest Version The latest updates to the Artix Mainframe documentation can be found at http://www.iona.com/support/docs. Compare the version dates on the web page for your product version with the date printed on the copyright page of the PDF edition of the book you are reading. Searching the Artix Library You can search the online documentation by using the Search box at the top right of the documentation home page: http://www.iona.com/support/docs To search a particular library version, browse to the required index page, and use the Search box at the top right, for example: http://www.iona.com/support/docs/artix/mainframe/5.0/index.xml You can also search within a particular book. To search within a HTML version of a book, use the Search box at the top left of the page. To search within a PDF version of a book, in Adobe Acrobat, select Edit|Find, and enter your search text. Artix Online Help Artix Designer and Artix Orchestration Designer include comprehensive online help, providing: • Step-by-step instructions on how to perform important tasks • A full search feature • Context-sensitive help for each screen There are two ways that you can access the online help: • Select Help|Help Contents from the menu bar. The help appears in the contents panel of the Eclipse help browser. • Press F1 for context-sensitive help. In addition, there are a number of cheat sheets that guide you through the most important functionality in Artix Designer and Artix Orchestration Designer. To access these, select Help|Cheat Sheets. 12
  • 13. PREFACE Artix Glossary The Artix Glossary is a comprehensive reference of Artix terms. It provides quick definitions of the main Artix components and concepts. All terms are defined in the context of the development and deployment of Web services using Artix. Additional Resources The IONA Knowledge Base (http://www.iona.com/support/knowledge_base/ index.xml) contains helpful articles written by IONA experts about Artix and other products. The IONA Update Center (http://www.iona.com/support/updates/index.xml) contains the latest releases and patches for IONA products. If you need help with this or any other IONA product, go to IONA Online Support (http://www.iona.com/support/index.xml). Comments, corrections, and suggestions on IONA documentation can be sent to . Document Conventions Typographical conventions This book uses the following typographical conventions: Fixed width Fixed width (Courier font) in normal text represents portions of code and literal names of items such as classes, functions, variables, and data structures. For example, text might refer to the IT_Bus::AnyType class. Constant width paragraphs represent code examples or information a system displays on the screen. For example: #include <stdio.h> Fixed width italic Fixed width italic words or characters in code and commands represent variable values you must supply, such as arguments to commands or path names for your particular system. For example: % cd /users/YourUserName Italic Italic words in normal text represent emphasis and introduce new terms. 13
  • 14. PREFACE Bold Bold words in normal text represent graphical user interface components such as menu commands and dialog boxes. For example: the User Preferences dialog. Keying Conventions This book uses the following keying conventions: No prompt When a command’s format is the same for multiple platforms, the command prompt is not shown. % A percent sign represents the UNIX command shell prompt for a command that does not require root privileges. # A number sign represents the UNIX command shell prompt for a command that requires root privileges. > The notation > represents the MS-DOS or Windows command prompt. ... Horizontal or vertical ellipses in format and syntax . descriptions indicate that material has been . eliminated to simplify a discussion. . [] Brackets enclose optional items in format and syntax descriptions. {} Braces enclose a list from which you must choose an item in format and syntax descriptions. | In format and syntax descriptions, a vertical bar separates items in a list of choices enclosed in {} (braces). In graphical user interface descriptions, a vertical bar separates menu commands (for example, select File|Open). 14
  • 15. CHAPTER 1 Process and Demonstration Overview This chapter provides an introductory overview of the overall process you must follow with Artix Mainframe, to expose and subsequently invoke on a DB2 SQL statement or stored procedure as a Web service. It also provides an overview of the sample demonstrations that are used to demonstrate this process. In this chapter This chapter discusses the following topics: Sample Demonstration page 16 Process Summary page 17 Graphical Overview of Deployment Process page 18 15
  • 16. CHAPTER 1 | Process and Demonstration Overview Sample Demonstration Overview This section provides an overview of the sample demonstration used in guide to show how to to expose and subsequently invoke on a DB2 SQL statement or stored procedure as a Web service. Demonstration overview The example used in this guide describes how to expose an SQL statement as a Web service called DbSample that can be contacted by various clients running on different platforms. The exposed Web service contains an operation called list_by_department that is based on an SQL statement that takes a department name as input and outputs SQL query results relating to the specified department. 16
  • 17. Process Summary Process Summary Overview This section provides an introductory overview of the overall process you must follow with Artix Mainframe, to expose and subsequently invoke on a DB2 SQL statement or stored procedure as a Web service. Steps The process of exposing a DB2 SQL statement or stored procedure as a Web service, using Artix Mainframe, involves some steps that must be completed on z/OS and other steps that must be completed off-host on Windows or UNIX. These steps can be summarized as follows and are explained in detail in the subsequent sections: 1. Start DB2 if it is not already running, and ensure the DB2 database is available. 2. Start the DB2 Gateway service on z/OS. See “Starting the DB2 Gateway Service” on page 21 for more details. 3. Use Artix Designer to define the SQL statements and stored procedure calls that are to form the basis of your Web service operations, and then upload these operations to the DB2 gateway service on z/OS. See “Defining and Uploading DB2 Operations to z/OS” on page 31 for more details. 4. Use the DB2 gateway service on z/OS to publish a WSDL file based on the deployment descriptor files you have deployed. This WSDL file exposes a Web service interface for the DB2 operations. See “Publishing WSDL from the DB2 Gateway Service” on page 62 for more details. 5. Develop and run a Web service client on Windows or UNIX that can use the DB2 gateway service on z/OS to contact the existing application as a Web service. See “Developing and Running a Web Service Client” on page 65. 17
  • 18. CHAPTER 1 | Process and Demonstration Overview Graphical Overview of Deployment Process Overview Figure 1 provides a graphical overview of the overall process involved in using Artix Mainframe to deploy DB2 SQL queries as Web services. Windows or UNIX z/OS Configuration Repository Artix Designer DB2 operations 4 SQL DB2 Statement Gateway Store File Service Web service client Web service client WSDL development Figure 1: Deploying DB2 SQL Queries as Web Services 18
  • 19. Grapical Overview of Runtime Invocations Grapical Overview of Runtime Invocations Overview Figure 2 provides a graphical overview of how the DB2 gateway service allows clients to invoke on DB2 SQL queries that have been exposed as Web services. Windows or UNIX Client (Artix, .NET, or WebLogic) SOAP over HTTP/HTTPS or WebSphere MQ z/OS SQL File read Statement DB2 Gateway Service Store File Configuration DB2 CLI Repository (ODBC) DB2 Figure 2: Invoking on DB2 SQL Query as Web Service 19
  • 20. CHAPTER 1 | Process and Demonstration Overview 20
  • 21. CHAPTER 2 Starting the DB2 Gateway Service Before you can proceed you must configure and run the DB2 gateway service on z/OS. This chapter describes how to start the DB2 gateway service. In this chapter This chapter discusses the following topics: Introduction to Starting the DB2 Gateway Service page 22 Starting the DB2 Gateway Service page 24 Checking the DB2 Gateway Service is Running Successfully page 29 21
  • 22. CHAPTER 2 | Starting the DB2 Gateway Service Introduction to Starting the DB2 Gateway Service Overview The first step in the process is to configure and run the DB2 gateway service component on z/OS. The DB2 gateway service must be configured, so that it can access at runtime the SQL statement store file containing the various DB2 operation details that Artix Designer uploads to it. The DB2 gateway service must then be started on z/OS, so that it is ready to listen for incoming client requests. It services these requests by transforming the Web service client request into an SQL query that it then forwards onto DB2. In turn, it transforms the reply from DB2 back into Web service data and returns it to the client. This subsection outlines some prerequisites and details you should know before starting the DB2 gateway service. DB2 gateway modes You can choose to start the DB2 gateway service in various modes, depending on the type of client requests you want it to support: • HTTP server mode to support Web service client requests via SOAP over HTTP/HTTPS. • MQ server mode to support Web service client requests via SOAP over WebSphere MQ. The default mode in which to run the DB2 gateway service is HTTP server mode. You may run the DB2 gateway service in either of the following ways: • HTTP server mode only. • HTTP server mode and MQ server mode. Configuring the DB2 gateway A number of configuration files are supplied for use with Artix Mainframe. service By default, the ARTIX configuration file is the main configuration domain for an insecure Artix Mainframe deployment. It also serves as the base for a secure deployment. The AXSECURE configuration file re-opens the existing scopes in the ARTIX configuration file and adds any additional settings 22
  • 23. Introduction to Starting the DB2 Gateway Service required to deploy Artix securely. To use the security features, you simply need to include the AXSECURE configuration file at the bottom of the ARTIX configuration file. Before you can start the DB2 gateway service, you must ensure that it has been properly configured for your system. See the Artix Mainframe Administrator’s Guide for full details of how to configure the DB2 gateway service and all setup requirements for using Artix Mainframe. DB2 gateway service logging When the DB2 gateway service is started, if a sufficient logging level is information enabled, some basic information is displayed on how the DB2 gateway service is configured, including which DB2 database it is going to connect with. 23
  • 24. CHAPTER 2 | Starting the DB2 Gateway Service Starting the DB2 Gateway Service Overview This subsection describes how to start the DB2 gateway service in HTTP server mode and MQ server mode. It discusses the following topics: • “The DB2GW JCL” on page 25. • “Enabling HTTP server mode” on page 25. • “Enabling MQ server mode” on page 26. • “Starting the DB2 gateway service” on page 28. • “Stopping the DB2 gateway service” on page 28. 24
  • 25. Starting the DB2 Gateway Service The DB2GW JCL The following is an overview of the default artixhlq.JCLLIB(DB2GW) JCL that is supplied with Artix Mainframe to run the DB2 gateway service: //DB2GW JOB (), // CLASS=A, // MSGCLASS=X, // MSGLEVEL=(1,1), // NOTIFY=&SYSUID, // REGION=0M, // TIME=1440 //* // JCLLIB ORDER=(HLQ.ARTIX50.PROCLIB) // INCLUDE MEMBER=(ARTXVARS) //* //* Run the Artix DB2 Gateway Service //* //* Make the following changes before running this JCL: //* //* 1. Change 'SET DOMAIN='ARTIX' to your configuration //* domain name. //* // SET DOMAIN='ARTIX' //* //GO EXEC PROC=ORXG, // PROGRAM=ORXDB2GW, // LOADLIB=&DB2LOAD, // PPARM='' //* PPARM='-ORBname iona_services.db2.use_mq' *Add for MQ //* //* Statement store. //* Statements saved to store if console stop command used for shutdown //STMNTS DD DISP=SHR,DSN=&ARTIX..DEMOS.DB2.STATMNTS //ITDOMAIN DD DSN=&ARTIXCFG(&DOMAIN),DISP=SHR Enabling HTTP server mode The DB2 gateway service must be enabled to run in HTTP server mode if you want it to support client requests via SOAP over HTTP on DB2 SQL statements and stored procedures being exposed as Web services. Note: The default mode in which to run the DB2 gateway service is to support SOAP over HTTP client requests without SSL/TLS security enabled. For details of how to start the DB2 gateway service in HTTP server mode with SSL/TLS security enabled, see the Artix Mainframe Common User Tasks guide. 25
  • 26. CHAPTER 2 | Starting the DB2 Gateway Service To enable the DB2 gateway service to run in HTTP server mode: 1. Open the main configuration file for the DB2 gateway service (this is artixhlq.CONFIG(ARTIX) by default). Then ensure the correct host and port for your DB2 gateway service are specified in the LOCAL_HOSTNAME and HTTP_DB2_SERVER_PORT configuration items. Also, ensure that the correct values are specified for the configuration items in the db2 scope. See the Artix Mainframe Administrator’s Guide for more details of these configuration items. Note: The default configuration for the DB2 gateway service running in HTTP server mode is defined directly in the db2 scope, and not in some sub-scope of this. 2. Ensure that you remove the comment character (that is, *) from the following lines in artixhlq.PROCLIB(ORXG): //* DD DISP=SHR,DSN=&DB2EXIT //* DD DISP=SHR,DSN=&DB2LOAD Removing the comment character from these lines adds the DB2 load libraries to your STEPLIB concatenation. Enabling MQ server mode The DB2 gateway service must be enabled to run in MQ server mode if you want it to support client requests via SOAP over WebSphere MQ on DB2 SQL statements and stored procedures being exposed as Web services. To enable the DB2 gateway service to run in MQ server mode: 1. Open the main configuration file for the DB2 gateway service (this is artixhlq.CONFIG(ARTIX) by default). Then ensure that the following configuration items are added to the iona_services.db2 scope: … iona_services { … db2 { … orb_plugins = ["local_log_stream", "http", "atli2_mq", "soap", "soap_deploy", "wto_announce"]; 26
  • 27. Starting the DB2 Gateway Service plugins:soap:mq:endpoints = ["DbSample"]; #Uncomment the following line, if you want MQ #to dynamically create queues for you. #plugins:soap:mq:default_model_queue_name # = "SYSTEM.DEFAULT.MODEL.QUEUE"; #Uncomment the following line, if you wish to enable #this endpoint to support multiple services. Note, #the service name must be in the requests MQMD #ApplIdentityData field. #plugins:soap:mq:Customer:support_multiple_services = # "true"; plugins:soap:mq:Customer:request_queue_manager_name = "CSQ1"; plugins:soap:mq:Customer:request_queue_name = "CSQ1.CALLB.LQ1"; # Use the service_name field when the actual service # name is different from the endpoint name. plugins:soap:mq:GPS:service_name = "GPSService"; plugins:soap:mq:GPS:request_queue_manager_name = "CSQ2"; plugins:soap:mq:GPS:request_queue_name = "CSQ2.CALLB.LQ1"; … }; … }; plugins:cicsa:bridge_language_packs = ["ORXNBCB1","ORXNBCC1","ORXNBPB1"]; See the Artix Mainframe Administrator’s Guide for more details of these configuration items. 2. Ensure that you remove the comment character (that is, *) from the following lines in artixhlq.PROCLIB(ORXG): //* DD DISP=SHR,DSN=&DB2EXIT //* DD DISP=SHR,DSN=&DB2LOAD Removing the comment character from these lines adds the DB2 load libraries to your STEPLIB concatenation. 27
  • 28. CHAPTER 2 | Starting the DB2 Gateway Service 3. Ensure that you remove the comment character (that is, *) from the following lines in artixhlq.PROCLIB(ORXG): //* DD DISP=SHR,DSN=&MQLOAD //* DD DISP=SHR,DSN=&MQLANG //* DD DISP=SHR,DSN=&MQAUTH Removing the comment character from these lines adds the WebSphere MQ load libraries to your STEPLIB concatenation. Starting the DB2 gateway service After you have configured the DB2 gateway service, you can start it on z/OS in any of the following ways: • As a batch job. • Using a TSO command. • As a started task (by converting the batch job into a started task). Submit artixhlq.JCLLIB(DB2GW) to start the DB2 gateway service. Stopping the DB2 gateway service Whenever you want to stop the DB2 gateway service, issue the STOP operator command from the console: P DB2GW Note: The DB2 gateway service must be running to enable successful uploads to it and to enable successful processing of Web service client requests on the DB2 database. 28
  • 29. Checking the DB2 Gateway Service is Running Successfully Checking the DB2 Gateway Service is Running Successfully Overview This subsection describes how to ensure that the DB2 gateway service is running successfully on z/OS. Steps To ensure that the DB2 gateway service is running successfully on z/OS, enter the following URL in a Windows or UNIX browser (where host and port represent the values specified for the LOCAL_HOSTNAME and HTTP_DB2_SERVER_PORT configuration items in artixhlq.CONFIG(ARTIX)). http://host:port/ionasoap/ManageSQL Web Services Description Language (WSDL) for the corresponding service should then be automatically generated by the DB2 gateway service and displayed on the client browser window. 29
  • 30. CHAPTER 2 | Starting the DB2 Gateway Service 30
  • 31. CHAPTER 3 Defining and Uploading DB2 Operations to z/OS After you have started the DB2 gateway service, the next step is to define the SQL statements and stored procedure calls that form the basis of the DB2 operations that you want to expose as Web services. These DB2 operations can then be uploaded from Artix Designer to the DB2 gateway service on z/OS. The uploaded DB2 operations are stored in an SQL statement store file that is used by the DB2 gateway service at runtime when supporting client invocations on the SQL queries being exposed as Web services. In this chapter This chapter discusses the following topics: Summary of Steps page 33 Starting Artix Designer page 34 Opening the Artix Mainframe Perspective page 37 Creating a z/OS Project from DB2 page 39 31
  • 32. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Viewing the Project Summary page 42 Working with the Artix Mainframe Perspective page 44 Managing Site Details page 46 Creating Operations page 49 Renaming Operations page 53 Deleting Operations page 55 Testing Operations and Viewing Results page 56 Uploading Operations to z/OS page 58 Retrieving or Removing Operations from z/OS page 59 Publishing WSDL from the DB2 Gateway Service page 62 32
  • 33. Summary of Steps Summary of Steps Overview This subsection outlines a summary of the steps you must perform with Artix Designer to enable you to expose a DB2 SQL statement or stored procedure as a Web service. These steps are explained in detail in the subsequent sections. Summary The steps involved in this part of the process can be summarized as follows: 1. Start Artix Designer and choose to create a z/OS Web services project from DB2. 2. Specify the URL that Artix Designer is to use to contact the DB2 gateway service on z/OS. 3. Define the SQL statements or stored procedure calls that form the basis of your DB2 operations. 4. Upload the DB2 operations to the DB2 gateway service on z/OS. 33
  • 34. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Starting Artix Designer Overview This subsection describes how to start Artix Designer on both Windows and UNIX. Windows steps To start Artix Designer on Windows, do either of the following: • Select Programs|IONA|Artix 5.0|Artix Designer from the Windows Start menu. • Use Windows Explorer to navigate to InstallDirtoolseclipse (where InstallDir represents the full path to your Artix installation directory) and double click eclipse.exe. UNIX steps To start Artix Designer on UNIX, run the InstallDir/tools/eclipse/ eclipse command from your Artix installation directory (where InstallDir represents the full path to your Artix installation directory). Selecting the default workspace When you start Artix Designer, a dialog box, shown in Figure 3, asks you to select a workspace. The workspace is the root folder into which all your Eclipse projects are stored. You can either accept the recommended default or enter a new workspace. Figure 3: Workspace Selection 34
  • 35. Starting Artix Designer If you do not want to see this dialog at start-up, select the Use this as the default and do not ask again check box. Artix Designer will open in the specified workspace from now on. Once Artix Designer is running, you can changes workspaces by selecting File|Switch Workspace. The Welcome screen When you start Artix Designer for the first time, the Welcome screen shown in Figure 4 is displayed. Figure 4: The Welcome Screen The icons on this screen are as follows: This provides a link to overview material on Artix Designer and the Eclipse workbench. This provides a link to the Artix and Artix Mainframe release notes. This provides a link to various tutorials on the uses of Artix Designer. 35
  • 36. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS This provides a link to the Artix and Artix Mainframe documentation set. This opens the Eclipse workbench. 36
  • 37. Opening the Artix Mainframe Perspective Opening the Artix Mainframe Perspective Overview Your Eclipse workbench includes a number of perspectives that enable you to work with various different types of projects in Eclipse. When you start Artix Designer, the workbench includes an Artix Mainframe perspective that you can open to work with Artix Mainframe projects. This subsection describes how to open the Artix Mainframe perspective in your Eclipse workbench. Note: The Artix Mainframe perspective does not need to be opened in your Eclipse workbench for the purposes of creating a z/OS project. However, it must be opened if you subsequently want to customize type mappings or other details relating to a z/OS project. Choosing the Artix Mainframe To open the Artix Mainframe perspective, do any of the following: perspective • Select Window>Open Perspective>Other to open the Select Perspective window. Then select Artix Mainframe and click OK. • Click the Open Perspective icon at the top-right of the workbench. Click Other to open the Open Perspective window. Then select Artix Mainframe and click OK. • If the icon is displayed at the top-right of the workbench, click it to see a list of perspectives that are currently open but not active. If Artix Mainframe is listed, select it to make it the active perspective. 37
  • 38. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS The Artix Mainframe perspective When you open the Artix Mainframe perspective for the first time, the screen shown in Figure 5 is displayed. To indicate which perspective is currently active, its name is displayed both in the title bar and at the top-right of the workbench. Figure 5: The Artix Mainframe Perspective “Working with the Artix Mainframe Perspective” on page 44 provides more details about working within the Artix Mainframe perspective after you have created a project. 38
  • 39. Creating a z/OS Project from DB2 Creating a z/OS Project from DB2 Overview The New Project wizard guides you through the steps to create an Artix Mainframe project, depending on the particular integration solution you want to achieve. This subsection describes how to create a z/OS project to expose an SQL statement or stored procedure call as a Web service. Steps The steps to create the new project are: 1. Open the Select a Wizard panel of the New Project wizard in any of the following ways: ♦ Select File>New>Project from the menu bar on the workbench. ♦ Select the New icon from the toolbar on the workbench. ♦ Click the down arrow beside the New icon on the workbench and select Project. This opens the window shown in Figure 6. Figure 6: Selecting a Project Wizard 39
  • 40. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS 2. Expand Artix and then Mainframe. 3. Click (to highlight) Web Services Project from DB2. 4. Click Next to open the General Details panel of the New z/OS Web Services Project from DB2 wizard shown in Figure 7. Figure 7: Specifying General Project Details 5. Type the name of your project. You can call the project any name you want. 6. If you do not want to accept the default location for storing your project details, uncheck the Use default location check box and use the browse button to select an alternative location. Note: The default location is based on the default workspace you specified on the Workspace Launcher window when starting Artix Designer. 7. Type the URL that Artix Designer is to use to contact the DB2 gateway service in the Service URL field. The URL takes the form http://host:port/ionasoap/ManageSQL (where host represents the 40
  • 41. Creating a z/OS Project from DB2 name of the host on which the DB2 gateway service is running, and port represents the port number that it uses to listen for incoming requests). 8. Click Next to open the Project Summary panel where you can view a summary of your project. See “Viewing the Project Summary” on page 42 for more details. 41
  • 42. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Viewing the Project Summary Overview The Project Summary panel allows you to double check the project details you have set up on the previous window before you proceed any further. If you are not happy with any of the information displayed, click Back to make any necessary modifications before you proceed. Project summary example Based on the sample details for the xyz demonstration, for example, the Project Summary screen should look similar to that shown in Figure 8. Figure 8: Example of Project Summary for DB2 SQL 42
  • 43. Viewing the Project Summary When you are happy with the summary information, click Finish to automatically add your project details to the Eclipse workbench and to reopen the workbench. Note: At this point, if the Artix Mainframe perspective is not already open in the Eclipse workbench, an Open Associated Perspective? dialog is displayed prompting you to open it now. For details of how to customize your project details further, and upload DB2 operations to z/OS, see “Working with the Artix Mainframe Perspective” on page 44. 43
  • 44. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Working with the Artix Mainframe Perspective Overview When you click Finish after defining and reviewing all the details of a new z/OS project, Artix Designer loads the details of that project into your Eclipse workbench. The details of the newly created project are automatically opened in the workbench at that point. Workbench layout For a z/OS Web services project from DB2, the Artix Mainframe perspective of your Eclipse workbench is divided into four main panels, called views: • The Navigator view • The Outline view • The DB2 Configuration view • The SQL Results for DB2 view The Navigator view The Navigator view is the top-left panel in your Eclipse workbench. It provides a list of your Artix projects and their associated project files. The Artix Designer project file for a z/OS Web services project from DB2 always has a .mfdb extension. By double clicking on the various elements in the Navigator view you can control what is displayed in the Outline and Mapping views. When you double click the .mfdb file for a specific project, the current project mode is displayed on the status bar at the bottom of the screen, to indicate the project type. The Outline view The Outline view is the bottom-left panel in your Eclipse workbench. When you double click the .mfdb file for a specific project in the Navigator view, the Outline view displays the DB2 sites and service/operation combinations relating to that project, in hierarchical form. By clicking on a particular element in this view you can control what is displayed in the DB2 Configuration view. 44
  • 45. Working with the Artix Mainframe Perspective The DB2 Configuration view The DB2 Configuration view is the top-right panel in your Eclipse workbench when you are working with a z/OS project from DB2. When you double click the .mfdb file in the Navigator view, that file is opened in the DB2 Configuration view. The DB2 Configuration view allows you to define the DB2 operations for your project, and subsequently upload them to the DB2 gateway service on z/OS. By clicking the Test SQL button in this view you can automatically open the SQL Results for DB2 view. The SQL Results for DB2 view The SQL Results for DB2 view is the bottom-right panel in your Eclipse workbench. It opens when you click the Test SQL button for a particular operation in the DB2 Configuration view. It is divided into a series of panels that display the results of the test on the SQL statement or stored procedure call that forms the basis of the operation. Summary of further tasks From the Eclipse workbench you can choose to perform a number of additional tasks that are relevant to a z/OS project from DB2. These tasks include: • Managing site details via the Outline or DB2 Configuration view. • Creating operations via the DB2 Configuration view. • Renaming operations via the Outline or DB2 Configuration view. • Deleting operations via the Outline or DB2 Configuration view. • Testing operations and viewing test results via the DB2 Configuration view. • Uploading operations to z/OS via the Outline or DB2 Configuration view. • Retrieving or removing operations from z/OS via the Outline or DB2 Configuration view. All these tasks are described in the following sections. Note: See the Artix Mainframe Common User Tasks guide for details of how to close, reopen and delete views and projects within the workbench. 45
  • 46. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Managing Site Details Overview A particular instance of the DB2 Gateway service on z/OS is also known as a site. When you create a z/OS project from DB2, you must specify a URL that describes the location of a particular site. The specified URL is subsequently used for communication with that instance of the DB2 Gateway service. You may add multiple different sites (that is, multiple different instances of the DB2 Gateway service) to the same project, if you wish. Each site in turn may support multiple different operations. Artix Designer allows you to perform various site management tasks, including adding new sites, editing details of existing sites, or deleting sites. Adding a new site If you want to add a new site: 1. Double click the .mfdb file for the relevant project in the Navigator view of the workbench. 2. Right-click an existing site name in the Outline view or DB2 Configuration view. Note: The name of the site that Artix Designer automatically creates when you create a project is based on the project name by default. 3. Select New Site. This opens the Create Site window shown in Figure 9. Figure 9: Adding a New DB2 Gateway Service Site 4. Type the name of the new site you want to create in the Name field. 46
  • 47. Managing Site Details 5. Type the URL that Artix Designer is to use to contact this new site in the Service URL field. 6. Click OK to add the new site details to the workbench. To add another site, simply repeat these steps. Editing site details If you want to edit the details of an existing site: 1. Double click the .mfdb file for the relevant project in the Navigator view of the workbench. 2. Right-click the relevant site name in the Outline view.or DB2 Configuration view 3. Select Edit Service Site. This opens the Edit Site window shown in Figure 10. Figure 10: Editing Site Details 4. Type the new name of the site in the Name field. 5. Type the new URL that Artix Designer is to use to contact this new site in the Service URL field. 6. Click OK to save your changes. To edit another site, simply repeat these steps. Deleting a site If you want to delete a site: 1. Double click the .mfdb file for the relevant project in the Navigator view of the workbench. 2. Right-click the relevant site name in the Outline view or DB2 Configuration view 47
  • 48. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS 3. Select Remove Site. This automatically deletes the site from the workbench. To delete another site, simply repeat these steps. 48
  • 49. Creating Operations Creating Operations Overview When you create a z/OS project from DB2, Artix Designer automatically creates a single operation for that project in your workbench. The default name for that operation takes the form project_nameOperation@project_nameService. You may add additional operations to the same project if you wish. Different operations may relate to the same site or different sites all within the same project. Note: A particular site cannot support a particular operation unless that operation is specifically created for that site. Steps To add an additional operation to a DB2 project: 1. In the Navigator view, select the .mfdb file for the relevant project. 2. In the DB2 Configuration view, click the name of the site to which you want to add the new operation. 3. Click the icon. This automatically opens a blank configuration panel for the new operation in the DB2 Configuration view, as shown in Figure 11. Figure 11: DB2 Configuration View 49
  • 50. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS The default name for each additional operation you create takes the form operationX@project_nameService (where X is a unique sequential number, starting from 0). 4. In the Outline view, click the operation you want to configure. Alternatively, click the tab for that operation in the DB2 Configuration view. 5. Type the SQL statement or stored procedure call on which you want to base the operation in the SQL field. Note: The SQL statements or stored procedure calls must conform to the SQL-92 standard. For example: SQL statement SELECT * FROM employee_account WHERE ID=? Stored procedure without parameters Call get_all Stored procedure with parameters Call add_salary_inout(?,?,?) Note: If you are following the supplied demonstration, type the following value in the SQL field: SELECT * FROM DSN8810.DEPT WHERE DEPTNAME=? 6. If you have entered a stored procedure call in the SQL field, check the Stored Procedure checkbox. 7. If you wish to enable scrolling support for the operation, check the Support Scrolling checkbox. See “Scrolling support” on page 52 for more details about scrolling support. 50
  • 51. Creating Operations 8. If your SQL query contains parameters, you can provide details for each parameter in the SQL Parameters grid. To add a parameter: i. Click the Add button. This automatically adds a new parameter to the grid, with a unique sequential number that cannot be edited. ii. Type the name of the parameter in the Parameters column. Note: If you are following the supplied demonstration, type department_name as the parameter name. iii. The Direction column is only enabled if you have checked the Stored Procedure check box, and the value in the SQL field is a stored procedure with parameters. In this case, click the direction value that corresponds to the parameter and use the down arrow to select its correct direction. Direction values can be "in" (that is, from client to server), "out" (that is, from server to client), or "inout" (that is, both in and out). iv. The Nullable column defaults to False for each parameter. If the parameter can contain null values, use the down arrow to set this to True. v. If you want to test your SQL statement or stored procedure to ensure it is valid, type the relevant parameter value on which you want to base your test in the Test Value field. Note: If you are following the supplied demonstration, type PLANNING as the test value. See “Testing Operations and Viewing Results” on page 56 for more details of how to test an operation. 9. If you wish to subsequently edit a specific parameter for an operation, click that parameter line in the SQL Parameters grid and then click individual values to edit them as appropriate. 10. If you wish to subsequently delete a specific parameter for an operation, click that parameter line in the SQL Parameters grid and then click Delete. 51
  • 52. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Scrolling support Scrolling support relates to SQL statements or stored procedures that return a result set. It enables you to break a large result set into smaller, more manageable increments. When you check the Support Scrolling checkbox in the DB2 Configuration view, the DB2 Gateway service on z/OS creates two additional parameters for the relevant SQL statement or stored procedure: • scrolling_start_row This parameter indicates which is the first row to be returned by the result set. All rows before this one are then skipped. Note: If you do not specify a value for this parameter, or if you specify 0, scrolling support is disabled. • scrolling_row_count This parameter indicates how many rows should be returned in the result set. A value must be specified for this parameter if the scrolling_start_row parameter is set to anything other than blank or 0. Note: If the value you specify for scrolling_row_count exceeds the value specified in the DB2 Gateway service configuration for the maximum number of rows it is allowed to return, the value specified in the DB2 Gateway service configuration takes precedence and the result set will be limited to that number of rows. 52
  • 53. Renaming Operations Renaming Operations Overview Artix Designer allows you to rename your DB2 operations, as appropriate. Steps To rename an operation in a DB2 project: 1. In the Navigator view, select the .mfdb file for the relevant project. 2. Right-click the relevant operation name in the Outline view or DB2 Configuration view. 3. Select Rename. This opens the Rename Operation window as shown in Figure 11. Figure 12: Renaming an Operation 4. Type the new name of the operation in the Operation Name field. Note: If you are following the supplied demonstration, rename your operation to list_by_department. 5. If you want to also change the service name, check the Also change service name check box and type the new name of the service in the Service Name field. Note: If you are following the supplied demonstration, rename your service to DbSample. 53
  • 54. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS 6. Click OK to save your changes. 54
  • 55. Deleting Operations Deleting Operations Overview Artix Designer allows you to delete your DB2 operations, as appropriate. Steps To delete an operation in a DB2 project: 1. In the Navigator view, select the .mfdb file for the relevant project. 2. Right-click the relevant operation name in the Outline view or DB2 Configuration view and select Delete. Alternatively, click the tab for that operation in the DB2 Configuration view and click the icon. The operation is automatically deleted from the workbench. 55
  • 56. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Testing Operations and Viewing Results Overview After you have defined a DB2 operation, Artix Designer allows you to test the SQL on which that operation is based, to ensure that it is valid. Artix Designer then displays the results of that SQL test in your workbench. Steps To test a DB2 operation and view the results: 1. In the Navigator view, select the .mfdb file for the relevant project. 2. Click the relevant operation name in the Outline view or DB2 Configuration view, to ensure its details are open in the DB2 Configuration view. 3. Click the Test SQL button. This automatically opens the SQL Results for DB2 view in the bottom-right panel of the workbench, as shown in Figure 13 Figure 13: Example of SQL Results for DB2 View 56
  • 57. Testing Operations and Viewing Results Layout of the SQL Results view for As shown in Figure 13, the SQL Results for DB2 view is divided into various DB2 panels. Click the tab or corresponding link for a particular panel to open it. The panels are: • Summary This indicates the status of the test result and provides links to the other panels. • Result Set This is only relevant to SELECT statements in the SQL field. It displays the results of your SQL query in tabular form. Click the Result Schema tab for schema type details about each of the fields in your result set. • Update Count This provides details relating to INSERT, UPDATE, and DELETE statements. • Output Parameter This is only relevant if you have specified a stored procedure call in the SQL field and checked the Stored Procedure check box. It lists the output parameters that relate to the stored procedure call. • Log This provides a log of the steps taken during the SQL test. 57
  • 58. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Uploading Operations to z/OS Overview After you have defined your DB2 operations, you must use Artix Designer to upload them to the DB2 gateway service on z/OS. Steps To upload DB2 operations to the DB2 Gateway service: 1. In the Navigator view, select the .mfdb file for the relevant project. 2. In the Outline view or DB2 Configuration view, right-click on the site to which you want to upload the SQL statements and select Upload Operations. Alternatively, click on the tab for the relevant site in the DB2 Configuration view and then click the icon. This opens the Uploading Operations window as shown in Figure 14 Figure 14: Uploading DB2 Operations to z/OS 3. Select the relevant operations you want to upload to the DB2 Gateway service and click OK. Note: If an operation of the same name has been previously uploaded to z/OS, the operation you are currently uploading automatically overwrites the previous one. 58
  • 59. Retrieving or Removing Operations from z/OS Retrieving or Removing Operations from z/OS Overview Artix Designer allows you to retrieve previously uploaded DB2 operations from z/OS. It also allows you to remove a DB2 operation from a particular site. Retrieving operations To retrieve DB2 operations from the DB2 Gateway service: 1. In the Navigator view, select the .mfdb file for the relevant project. 2. In the Outline view or DB2 Configuration view, right-click on the site from which you want to upload the SQL statements and select Retrieve Operations. Alternatively, click on the tab for the relevant site in the DB2 Configuration view and then click the icon. This automatically retrieves the SQL statements from the DB2 Gateway service and loads them into your project. 59
  • 60. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Resolving name conflicts If you try to retrieve an operation from z/OS, but an operation of the same name is already in your project, Artix Designer opens a Name Conflict window, as shown in Figure 15, to prompt you to either overwrite or rename the operation that you are trying to retrieve. Figure 15: Resolving operation name conflicts To resolve a name conflict: • Select Overwrite the existing operation if you want the operation you are currently retrieving to be replaced with the operation already in your project. • Select Rename the existing operation if you want to rename the operation that you are currently retrieving rather than overwrite it. In this case, type the new name for the operation you are currently retrieving in the corresponding text field. Click OK to save your changes. The operation you are retrieving is automatically overwritten or renamed, as appropriate. 60
  • 61. Retrieving or Removing Operations from z/OS Removing operations To remove DB2 operations from the DB2 Gateway service: 1. In the Navigator view, select the .mfdb file for the relevant project. 2. In the Outline view or DB2 Configuration view, right-click on the site from which you want to remove the SQL statements and select Remove Operations. Alternatively, click on the tab for the relevant site in the DB2 Configuration view and then click the icon. This automatically removes the SQL statements from the DB2 Gateway service. 61
  • 62. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS Publishing WSDL from the DB2 Gateway Service Overview After you have uploaded your DB2 SQL operations to the DB2 gateway service on z/OS, you can use the DB2 gateway service to generate and publish the WSDL interface that your Web service clients can subsequently use to invoke on your DB2 SQL query that is being exposed as a Web service. Publishing WSDL To enable the DB2 gateway service to publish WSDL for your deployed Web service, enter a URL with the following format in a Windows or UNIX browser: http://host:port/ionasoap/service_name The preceding URL can be explained as follows: host This represents the name of the host on which the transformer service is running. The value specified here must match the value specified for the LOCAL_HOSTNAME configuration item in artixhlq.CONFIG(ARTIX). port This represents the port that the transformer service uses to listen for incoming requests. The value specified here must match the value specified for the HTTP_DB2_SERVER_PORT configuration item in artixhlq.CONFIG(ARTIX). service_name This is the name of the deployed Web service for which you want the DB2 gateway service to publish a WSDL interface. For example, to publish WSDL for the demonstration DbSample Web service, enter the following URL in a Windows or UNIX browser (where host and port represent the relevant hostname and port values for your DB2 gateway service): http://host:port/ionasoap/DbSample?wsdl 62
  • 63. Publishing WSDL from the DB2 Gateway Service The relevant WSDL is then published in your Windows or UNIX browser, and you can copy it to your local host for use in developing your Web service clients. 63
  • 64. CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS 64
  • 65. CHAPTER 4 Developing and Running a Web Service Client If you have followed the various steps described so far, you should now have an SQL statement or stored procedure call exposed as a Web service, and the DB2 gateway service up and running to handle any client requests on that Web service. For the purposes of illustration, this chapter describes how to write, build and run the supplied client demonstration to invoke on the DbSample demonstration Web service. In this chapter This chapter discusses the following topics: Versions of the Client Demonstration page 66 Artix C++ Client Example page 67 Client Output page 72 Note: The instructions provided in this section are also supplied in the db2.html readme file located in the InstallDir/mainframe/samples/db2/ readme directory of your Artix installation on Windows or UNIX. 65
  • 66. CHAPTER 4 | Developing and Running a Web Service Client Versions of the Client Demonstration Overview The demonstration provided in this chapter relates specifically to an insecure Artix client that uses a document-literal encoding mechanism with the HTTP transport. .NET and WebLogic For an example of how to build and run a .NET or WebLogic client, see demonstrations chapter 1 of the Service-Enabling Existing z/OS Applications guide. WebSphere MQ demonstrations For an example of how to build and run demonstrations to use the WebSphere MQ transport, see chapter 1 of the Creating New z/OS Applications from WSDL guide. Secure demonstrations For links to demonstrations that use various levels of security, see chapter 1 of the Service-Enabling Existing z/OS Applications guide. RPC literal and SOAP encoded For links to demonstrations that use RPC literal and RPC SOAP-encoded demonstrations mechanisms for data transfer, see chapter 1 of the Service-Enabling Existing z/OS Applications guide. 66
  • 67. Artix C++ Client Example Artix C++ Client Example Overview This subsection describes how to write, build and subsequently run the demonstration Artix C++ client supplied for the example in this chapter. Note: The client shown here runs in insecure mode and supports a document-literal encoding mechanism for data transfer. Note: More details of how to use Artix Designer to automatically generate starting point code for an Artix client are provided in the Artix Mainframe Common User Tasks guide in the section on generating Artix clients for mainframe Web services. Writing the client The code for the demonstration Artix C++ client that can contact the exposed DbSample Web service is located in your Artix installation on Windows or UNIX at InstallDir/mainframe/samples/db2/client. The client code in helper.h is as follows: /******************************************************************** * * * Copyright (c) 1993-2007 IONA Technologies PLC. * All Rights Reserved. * * ********************************************************************* #include "DbSampleSOAPPortClient.h" namespace DB2Demo { // add some helper functions to the demo namespace void get_records( const IT_Bus::String department_name, DB2Demo::SequenceOfResultSet_list_by_department& rec, DB2Demo::DbSampleSOAPPortClient& client ) IT_THROW_DECL((IT_Bus::Exception)); 67
  • 68. CHAPTER 4 | Developing and Running a Web Service Client IT_Bus::Boolean display_records( DB2Demo::SequenceOfResultSet_list_by_department &rec ); }; #endif /* _DB2_DEMO_H_ */ The client code in helper.cxx is as follows: /******************************************************************** * * * Copyright (c) 1993-2007 IONA Technologies PLC. * All Rights Reserved. * * *********************************************************************/ #include "helper.h" IT_USING_NAMESPACE_STD using namespace DB2Demo; void DB2Demo::get_records( const IT_Bus::String department_name, DB2Demo::SequenceOfResultSet_list_by_department& rec, DB2Demo::DbSampleSOAPPortClient& client ) IT_THROW_DECL((IT_Bus::Exception)) { Input_list_by_department department; department.setdepartment_name(department_name); IT_Bus::Int list_by_departmentResult; cout << "Performing lookup of department: " << department_name << endl << endl; client.list_by_department(department, list_by_departmentResult, rec); } IT_Bus::Boolean DB2Demo::display_records( DB2Demo::SequenceOfResultSet_list_by_department &val ) 68
  • 69. Artix C++ Client Example { cout << "Number of rows returned: " << val.size() << endl << endl; for (int i = 0; i < val.size(); i++) { cout << "Department record number " << i << ":" << endl << " DEPTNO : " << val[i].getDEPTNO().getvalue() << endl << " DEPTNAME : " << val[i].getDEPTNAME().getvalue() << endl << " MGRNO : " << (val[i].getMGRNO())->getvalue() << endl << " ADMRDEPT : " << val[i].getADMRDEPT().getvalue() << endl << " LOCATION : " << (val[i].getLOCATION())->getvalue() << endl << endl; } return true; } 69
  • 70. CHAPTER 4 | Developing and Running a Web Service Client The client code in client.cxx is as follows: // ****************************************************************** // // // Copyright (c) 1993-2007 IONA Technologies PLC. // All Rights Reserved. // // // ****************************************************************** #include <it_bus/bus.h> #include <it_bus/exception.h> #include <it_cal/iostream.h> #include "helper.h" IT_USING_NAMESPACE_STD using namespace DB2Demo; int main( int argc, char* argv[] ) { try { IT_Bus::init(argc, argv); IT_Bus::String department_name = "PLANNING"; if (argc > 1) { department_name = argv[1]; } DB2Demo::DbSampleSOAPPortClient client; SequenceOfResultSet_list_by_department rec; get_records(department_name, rec, client); display_records(rec); } catch(const IT_Bus::Exception& e) { cerr << endl << "Error: Unexpected error occured!" << endl << e.message() 70
  • 71. Artix C++ Client Example << endl; return -1; } cout << "DB2 Demo completed successfully" << endl; return 0; } Building the client for HTTP The steps to build the demonstration client on Windows or UNIX for the purposes of using the HTTP transport are: 1. After installing IONA’s Artix 5.0, if you need to set up your client environment, open the InstallDir/mainframe/samples/index.html file in your Artix installation on Windows or UNIX, and click the Webservices Product Development Environment Setup link for instructions. 2. Navigate to the InstallDir/mainframe/samples/db2/client directory (where InstallDir represents the full path to your Artix installation on Windows or UNIX). 3. Enter the following command to build the client (where hostname represents the z/OS TCP/IP hostname where the DB2 gateway service is running, and port represents the port that the DB2 gateway service uses to listen for client requests): Windows: nmake /f makefile.win32 WS_HOST=hostname WS_PORT=port UNIX: make -f makefile.unix WS_HOST=hostname WS_PORT=port This generates the Artix Web services client proxy classes and type helpers, compiles the generated C++ application files, and produces a client executable. Running the client To run the client on Windows or UNIX, enter the client command. 71
  • 72. CHAPTER 4 | Developing and Running a Web Service Client Client Output Overview This subsection provides an overview of the output produced by the demonstration clients for the example in this chapter. Output The client output is similar to the following: Performing lookup of department: PLANNING Number of rows returned: 1 Department record number 0: DEPTNO : B01 DEPTNAME : PLANNING MGRNO : 000020 ADMRDEPT : A00 LOCATION : MA 02451 DB2 Demo completed successfully 72
  • 73. Index A J Artix client demonstration JCL running against DB2 SQL Web service 67 CICST, for server mode 28 Artix Designer for z/OS usage summary for exposing CICS or IMS applications as Web O services 33 operations Web service, defining further 46 C CICST JCL S for running in server mode 28 server mode CICS transformer service starting CICS transformer service in 24 starting in server mode 24 T D transformer service DB2 SQL queries starting in server mode for CICS 24 exposing as Web services 65–72 demonstration client Artix W running against DB2 SQL Web service 67 Web service operations output defining further 46 running against DB2 SQL Web service 72 Web services exposing DB2 SQL queries as 65–72 73
  • 74. INDEX 74