service-enabling db2 sql

Service-Enabling DB2 SQLVersion 4.2, March 2007

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.While the information in this publication is believed to be accurate, 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 shall not be liable for errors contained herein, or for incidental or consequential damages in connection with the furnishing, performance or use of this material.

COPYRIGHT NOTICENo 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 publication. This publication and features described herein are subject to change without notice.

Copyright © 1999-2007 IONA Technologies PLC. All rights reserved.

All products or services mentioned in this publication are covered by the trademarks, service marks, or product names as designated by the companies that market those products.

Updated: May 18, 2007

Contents
List of Figures 5
List of Tables 7

Preface 9

Chapter 1 Process and Demonstration Overview 15Sample Demonstration 16Process Summary 17Graphical Overview of Deployment Process 18Grapical Overview of Runtime Invocations 19

Chapter 2 Starting the DB2 Gateway Service 21Introduction to Starting the DB2 Gateway Service 22Starting the DB2 Gateway Service 24Checking the DB2 Gateway Service is Running Successfully 29

Chapter 3 Defining and Uploading DB2 Operations to z/OS 31Summary of Steps 33Starting Artix Designer 34Opening the Artix for z/OS Perspective 37Creating a z/OS Project from DB2 39Working with the Artix for z/OS Perspective 42Managing Site Details 44Creating Operations 47Renaming Operations 51Deleting Operations 52Testing Operations and Viewing Results 53Uploading Operations to z/OS 55Retrieving or Removing Operations from z/OS 56Publishing WSDL from the DB2 Gateway Service 59

3

CONTENTS

Chapter 4 Developing and Running a Web Service Client 61Versions of the Client Demonstration 63Artix C++ Client Example 64.NET C# Client Example 71WebLogic Java Client Example 76Client Output 82

Index 83

4

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 for z/OS Perspective 38

Figure 6: Selecting a Project Wizard 39

Figure 7: Specifying General Project Details 40

Figure 8: Adding a New DB2 Gateway Service Site 44

Figure 9: Editing Site Details 45

Figure 10: DB2 Configuration View 47

Figure 11: Renaming an Operation 51

Figure 12: Example of SQL Results for DB2 View 53

Figure 13: Uploading DB2 Operations to z/OS 55

Figure 14: Resolving operation name conflicts 57

5

LIST OF FIGURES

6

List of Tables

7

LIST OF TABLES

8

PrefaceWhat is Covered in This BookThis book discusses how to use Artix for z/OS to expose DB2 SQL statements and stored procedures as Web services.

Who Should Read This BookThis book is intended for Artix for z/OS users who wish to expose DB2 SQL statements and stored procedures as Web services.

PrerequisitesSee the Artix Installation Guide for z/OS for a full list of supported platforms, supported compilers, and other prerequisites relating to the use of Artix for z/OS.

Standards ComplianceArtix for z/OS 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

PREFACE

The Artix for z/OS LibraryThe Artix for z/OS documentation library includes the following books:

� Introduction to Artix for z/OS

� Getting Started for z/OS

� 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 for z/OS

� Administrator�s Guide for z/OS

Introduction to Artix for z/OS

The Introduction to Artix for z/OS guide provides an introductory overview of Artix for z/OS 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 for z/OS

The Getting Started for z/OS guide is intended to help you get started quickly with Artix for z/OS. It provides demonstration walkthroughs of the various integration solutions that Artix for z/OS supports.

Service-Enabling Existing z/OS Applications

The Service-Enabling Existing z/OS Applications guide explains how to use Artix for z/OS 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 for z/OS 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 for z/OS to create z/OS-based COBOL or PL/I Artix CORBA clients starting from IDL.

10

../session_mgr/index.htm





PREFACE

Service-Enabling DB2 SQL

This is the book you are currently reading. It explains how to use Artix for z/OS to expose DB2 SQL statements and stored procedures as Web services.

Common User Tasks for z/OS

The Common User Tasks for z/OS guide explains how to use Artix for z/OS 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 for z/OS

The Administrator�s Guide for z/OS describes how to set up and configure the various features of Artix for z/OS. It also discusses the various levels of security that can be used in the product.

Organisation of This BookThis 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 for z/OS, 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



PREFACE

Getting the Latest VersionThe latest updates to the Artix for z/OS 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 LibraryYou 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/4.2/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 HelpArtix 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




http://www.iona.com/support/docs/artix/mainframe/4.2/index.xml

PREFACE

Artix GlossaryThe 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 ResourcesThe 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 ConventionsTypographical 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

http://www.iona.com/support/kb/index.jspa

http://www.iona.com/support/updates/index.xml

http://www.iona.com/support/index.xml

http://www.iona.com/support/index.xml

../glossary/index.htm

PREFACE

Keying Conventions

This book uses the following keying conventions:

Bold Bold words in normal text represent graphical user interface components such as menu commands and dialog boxes. For example: the User Preferences dialog.

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

CHAPTER 1

Process and Demonstration OverviewThis chapter provides an introductory overview of the overall process you must follow with Artix for z/OS, 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

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

Process Summary

Process Summary

Overview This section provides an introductory overview of the overall process you must follow with Artix for z/OS, 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 for z/OS, 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 59 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 61.

17


Graphical Overview of Deployment Process

Overview Figure 1 provides a graphical overview of the overall process involved in using Artix for z/OS to deploy DB2 SQL queries as Web services.

Figure 1: Deploying DB2 SQL Queries as Web Services

4

Windows or UNIX z/OS

DB2Gateway

Artix Designer

ConfigurationRepository

Web service client

SQLStatementStore File

WSDLWeb service

clientdevelopment

Service

DB2operations

18

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.

Figure 2: Invoking on DB2 SQL Query as Web Service

z/OS

DB2

SOAP overHTTP/HTTPS

or WebSphere MQ

DB2 CLI(ODBC)

DB2 Gateway Service File read

ConfigurationRepository

SQLStatement

StoreFile

Windows or UNIXClient

(Artix, .NET, orWebLogic)

19


20

CHAPTER 2

Starting the DB2 Gateway ServiceBefore 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.


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

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 service

A number of configuration files are supplied for use with Artix for z/OS. By default, the ARTIX configuration file is the main configuration domain for an insecure Artix for z/OS 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 required to

22

Introduction to Starting the DB2 Gateway Service

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 Administrator�s Guide for z/OS for full details of how to configure the DB2 gateway service and all setup requirements for using Artix for z/OS.

DB2 gateway service logging information

When the DB2 gateway service is started, if a sufficient logging level is 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


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 27.

� �Stopping the DB2 gateway service� on page 28.

24


The DB2GW JCL The following is an overview of the default artixhlq.JCLLIB(DB2GW) JCL that is supplied with Artix for z/OS to run the DB2 gateway service:

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.

//DB2GW JOB (),// CLASS=A,// MSGCLASS=X,// MSGLEVEL=(1,1),// NOTIFY=&SYSUID,// REGION=0M,// TIME=1440//*// JCLLIB ORDER=(HLQ.ARTIX42.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

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 Common User Tasks for z/OS guide.

25


To enable the DB2 gateway service to run in HTTP server mode, 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 Administrator�s Guide for z/OS for more details of these configuration items.

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:

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.

� iona_services { � db2 { � orb_plugins = ["local_log_stream", "http", "atli2_mq", "soap", "soap_deploy", "wto_announce"];

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";

26


See the Artix Administrator�s Guide for z/OS 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):

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.

#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"];

//* DD DISP=SHR,DSN=&MQLOAD//* DD DISP=SHR,DSN=&MQLANG//* DD DISP=SHR,DSN=&MQAUTH

27


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

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)).

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.

http://host:port/ionasoap/ManageSQL

29


30

CHAPTER 3

Defining and Uploading DB2 Operations to z/OSAfter 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.


Summary of Steps page 33

Starting Artix Designer page 34

Opening the Artix for z/OS Perspective page 37

Creating a z/OS Project from DB2 page 39

31

CHAPTER 3 | Defining and Uploading DB2 Operations to z/OS

Working with the Artix for z/OS Perspective page 42

Managing Site Details page 44

Creating Operations page 47

Renaming Operations page 51

Deleting Operations page 52

Testing Operations and Viewing Results page 53

Uploading Operations to z/OS page 55

Retrieving or Removing Operations from z/OS page 56

Publishing WSDL from the DB2 Gateway Service page 59

32

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


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 4.2|Artix Designer from the Windows Start menu.

� Use Windows Explorer to navigate to InstallDir\artix\4.2\eclipse (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/artix/4.2/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

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.

The icons on this screen are as follows:

Figure 4: The Welcome Screen

This provides a link to overview material on Artix Designer and the Eclipse workbench.

This provides a link to the Artix and Artix for z/OS release notes.

This provides a link to various tutorials on the uses of Artix Designer.

35


This provides a link to the Artix and Artix for z/OS documentation set.

This opens the Eclipse workbench.

36

Opening the Artix for z/OS Perspective

Opening the Artix for z/OS 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 for z/OS perspective that you can open to work with Artix for z/OS projects. This subsection describes how to open the Artix for z/OS perspective in your Eclipse workbench.

Choosing the Artix for z/OS perspective

To open the Artix for z/OS perspective, do any of the following:

� Select Window>Open Perspective>Other to open the Select Perspective window. Then select Artix for z/OS and click OK.

� Click the Open Perspective icon at the top-right of the workbench to open the Select Perspective window. Then select Artix for z/OS 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 for z/OS is listed, select it to make it the active perspective.

Note: The Artix for z/OS 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.

37


The Artix for z/OS perspective When you open the Artix for z/OS 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.

�Working with the Artix for z/OS Perspective� on page 42 provides more details about working within the Artix for z/OS perspective after you have created a project.

Figure 5: The Artix for z/OS Perspective

38

Creating a z/OS Project from DB2


Overview The New Project wizard guides you through the steps to create an Artix for z/OS 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


2. Expand IONA Artix Designer and click (to highlight) z/OS Web Services Project from DB2.

3. Click Next to open the General Details panel of the New z/OS Web Services Project from DB2 wizard shown in Figure 7.

4. Type the name of your project. You can call the project any name you want.

5. 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.

6. 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

Figure 7: Specifying General Project Details

Note: The default location is based on the default workspace you specified on the Workspace Launcher window when starting Artix Designer.

40


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).

7. Click Finish to automatically open your project details in the Eclipse workbench.

Note: At this point, if the Artix for z/OS perspective is not already open in the Eclipse workbench, an Open Associated Perspective? dialog is displayed prompting you to open it now.

41


Working with the Artix for z/OS 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 for z/OS 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.

42

Working with the Artix for z/OS 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 Common User Tasks for z/OS guide for details of how to close, reopen and delete views and projects within the workbench.

43


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.

3. Select New Site. This opens the Create Site window shown in Figure 8.

4. Type the name of the new site you want to create in the Name field.

Note: The name of the site that Artix Designer automatically creates when you create a project is based on the project name by default.

Figure 8: Adding a New DB2 Gateway Service Site

44

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:


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 9.

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:


2. Right-click the relevant site name in the Outline view or DB2 Configuration view

Figure 9: Editing Site Details

45


3. Select Remove Site. This automatically deletes the site from the workbench.

To delete another site, simply repeat these steps.

46

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.

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 10.

Note: A particular site cannot support a particular operation unless that operation is specifically created for that site.

Figure 10: DB2 Configuration View

47


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.

For example:

SQL statementSELECT * FROM employee_account WHERE ID=?

Stored procedure without parametersCall get_all

Stored procedure with parametersCall add_salary_inout(?,?,?)

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 49 for more details about scrolling support.

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.

If you are following the supplied demonstration, type department_name as the parameter name.

Note: The SQL statements or stored procedure calls must conform to the SQL-92 standard.

48

Creating Operations

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.

If you are following the supplied demonstration, type PLANNING as the test value.

See �Testing Operations and Viewing Results� on page 53 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.

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

49


This parameter indicates which is the first row to be returned by the result set. All rows before this one are then skipped.

� 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 you do not specify a value for this parameter, or if you specify 0, scrolling support is disabled.

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.

50

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:


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 10.

4. Type the new name of the operation in the Operation Name field.

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.

If you are following the supplied demonstration, rename your service to DbSample.

6. Click OK to save your changes.

Figure 11: Renaming an Operation

51


Deleting Operations

Overview Artix Designer allows you to delete your DB2 operations, as appropriate.

Steps To delete an operation in a DB2 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.

52

Testing Operations and Viewing Results

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:


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 12

Layout of the SQL Results view for DB2

As shown in Figure 12, the SQL Results for DB2 view is divided into various 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

Figure 12: Example of SQL Results for DB2 View

53


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.

54

Uploading 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:


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 13

3. Select the relevant operations you want to upload to the DB2 Gateway service and click OK.

Figure 13: Uploading DB2 Operations to z/OS

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.

55


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:


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.


This automatically retrieves the SQL statements from the DB2 Gateway service and loads them into your project.

56

Retrieving or Removing Operations from 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 14, to prompt you to either overwrite or rename the operation that you are trying to retrieve.

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.

Figure 14: Resolving operation name conflicts

57


Removing operations To remove DB2 operations from the DB2 Gateway service:


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.


This automatically removes the SQL statements from the DB2 Gateway service.

58

Publishing WSDL from the DB2 Gateway Service

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:

The preceding URL can be explained as follows:

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/service_name

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.

http://host:port/ionasoap/DbSample?wsdl

59


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.

60

CHAPTER 4

Developing and Running a Web Service ClientIf 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 demonstrations to invoke on the DbSample demonstration Web service.


Versions of the Client Demonstration page 63

Artix C++ Client Example page 64

.NET C# Client Example page 71

WebLogic Java Client Example page 76

Client Output page 82

61

CHAPTER 4 | Developing and Running a Web Service Client

Note: The instructions provided in this section are also supplied in the db2.html readme file located in the InstallDir/artix/4.2/demos/mainframe/appl_first/readme directory of your Artix installation on Windows or UNIX.

Note: Demonstrations using the HTTP transport are provided for Artix, .NET and WebLogic.

62

Versions of the Client Demonstration

Versions of the Client Demonstration

Encoding mechanism The supplied DbSample demonstration relates to an insecure client that supports a document-literal encoding.

Location of demonstrations Versions of the DbSample demonstration are supplied for Artix, .NET and WebLogic in the following locations in your Artix installation on Window or UNIX:

InstallDir/artix/4.2/demos/mainframe/appl_first/artix/db2

InstallDir/artix/4.2/demos/mainframe/appl_first/dot_net/db2

InstallDir/artix/4.2/demos/mainframe/appl_first/weblogic/db2

63


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 Common User Tasks for z/OS guide in the section on generating Artix clients for mainframe Web services.

64


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/artix/4.2/demos/mainframe/appl_first/artix/db2/insecure/doc_literal/cxx_client. The client code in helper.h is as follows:

// ******************************************************************////// Copyright (c) 1993-2006 IONA Technologies PLC.// All Rights Reserved.////// ******************************************************************

#ifndef _DB2_DEMO_H_#define _DB2_DEMO_H_

/*********************************************************************** Copyright (c) 1993-2006 IONA Technologies PLC.*All Rights Reserved.***********************************************************************/

65


The client code in helper.cxx is as follows:

#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));

IT_Bus::Boolean display_records( DB2Demo::SequenceOfResultSet_list_by_department &rec );};

#endif /* _DB2_DEMO_H_ */


/*********************************************************************** Copyright (c) 1993-2006 IONA Technologies PLC.*All Rights Reserved.***********************************************************************/#include "helper.h"

IT_USING_NAMESPACE_STDusing namespace DB2Demo;

66


voidDB2Demo::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::BooleanDB2Demo::display_records( DB2Demo::SequenceOfResultSet_list_by_department &val){ 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;}

67


The client code in client.cxx is as follows:


/*********************************************************************** Copyright (c) 1993-2006 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_STDusing namespace DB2Demo;

intmain( 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;

68


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 4.2, if you need to set up your client environment, open the InstallDir/artix/4.2/demos/mainframe/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/artix/4.2/demos/mainframe/appl_first/artix/DB2/insecure/doc_literal/cxx_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:

UNIX:

get_records(department_name, rec, client);

display_records(rec); } catch(const IT_Bus::Exception& e) { cerr << endl << "Error: Unexpected error occured!" << endl << e.message() << endl; return -1; }

cout << "DB2 Demo completed successfully" << endl;

return 0;}

nmake /f makefile.win32 WS_HOST=hostname WS_PORT=port

make -f makefile.unix WS_HOST=hostname WS_PORT=port

69


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.

70

.NET C# Client Example


Overview This subsection describes how to write, build and subsequently run the demonstration .NET C# client supplied for the example in this chapter.

Writing the client The code for the demonstration .NET C# client that can contact the exposed DbSample Web service is located in your Artix for z/OS installation on Windows at InstallDir\artix\4.2\demos\mainframe\appl_first\dot_net\db2\insecure\doc_literal\csharp_client. The client code is as follows:

/*********************************************************************** Copyright (c) 1993-2006 IONA Technologies PLC.* All Rights Reserved.***********************************************************************/

using System;using remote_service;

namespace DB2Demo{

/// <summary> /// The client of the Customer Web Service. /// </summary> class DB2Client { private DbSample m_service = null;

/// <summary> /// DbSampleClient constructor /// </summary> public DB2Client() { // instantiate the DbSample Web Service proxy // m_service = new DbSample();

71


}

/// <summary> /// The main entry point for the application. /// </summary> [STAThread] static void Main(string[] args) { try { // Register our own trusted cert policy, // .NET's default is too strict for this demo. // System.Net.ServicePointManager.CertificatePolicy = new trustedCertificatePolicy();

// Get a new instance of the DB2 Web Service DB2Client client = new DB2Client();

string department_name = "PLANNING"; if (args.Length > 0) { department_name = args[0]; } ResultSet_list_by_department[] rec = client.get_records(department_name); client.display_records(rec);

} catch (Exception ex) { Console.Error.WriteLine("Exception: " + ex.ToString()); return; }

Console.WriteLine("DB2 demo completed successfully"); }

72


/// <summary> /// Obtain the customer record details from the remote Web Service /// </summary> public ResultSet_list_by_department[] get_records( string department_name ) { // Initialise the input structure Input_list_by_department in_param = new Input_list_by_department(); in_param.department_name = department_name;

// Invoke the operation Console.WriteLine("Performing lookup of department: " + department_name); ResultSet_list_by_department[] resultset; int result = m_service.list_by_department(in_param, out resultset); return resultset; }

/// <summary> /// Display the customer record - return false if record is empty. /// </summary> public bool display_records( ResultSet_list_by_department[] rec ) { Console.WriteLine("Number of rows returned: " + rec.Length); Console.WriteLine("");

for (int i = 0; i < rec.Length; i++) { Console.WriteLine("Department record number " + i + " :");

Console.WriteLine("DEPTNO : " + rec[i].DEPTNO); Console.WriteLine("DEPTNAME : " + rec[i].DEPTNAME); Console.WriteLine("MGRNO : " + rec[i].MGRNO); Console.WriteLine("ADMRDEPT : " + rec[i].ADMRDEPT); Console.WriteLine("LOCATION : " + rec[i].LOCATION); Console.WriteLine(""); }

return true; } }

73


Building the client for HTTP The steps to build the demonstration client on Windows for the purposes of using the HTTP transport are:

1. After installing Microsoft�s .NET version 1.1, if you need to set up your client environment, open the InstallDir\artix\4.2\demos\mainframe\index.html file in your Artix for z/OS installation on Windows, and click the Webservices Product Development Environment Setup link for instructions.

2. If you do not have Microsoft .NET Framework SDK 1.1 installed:

♦ Go to http://www.microsoft.com/downloads to download it.

♦ After installing it, run the sdkvars.bat file in the .NET-install-dir\SDK\v1.1\Bin directory to set up the .NET Framework SDK environment.

3. Open a DOS command prompt and navigate to the InstallDir\artix\4.2\demos\mainframe\appl_first\dot_net\

db2\insecure\doc_literal\csharp_client directory (where InstallDir represents the full path to your Artix for z/OS installation on Windows).

/// <summary> /// A trustedCerticatePolicy that will accept invalid certs /// </summary> public class trustedCertificatePolicy : System.Net.ICertificatePolicy { public trustedCertificatePolicy() {}

public bool CheckValidationResult( System.Net.ServicePoint sp, System.Security.Cryptography.X509Certificates.X509Certificate certificate, System.Net.WebRequest request, int problem ) { return true; } }}

74



This generates the .NET Web services client proxy classes and type helpers, compiles the generated application C# files, and produces a client executable.

Running the client To run the client on Windows, enter the client command.

nmake WS_HOST=hostname WS_PORT=port

75


WebLogic Java Client Example

Overview This subsection describes how to write, build and subsequently run the demonstration WebLogic Java client supplied for the example in this chapter.

Writing the client The code for the demonstration WebLogic Java client that can contact the exposed DbSample Web service is located in your Artix installation on Windows or UNIX at InstallDir/artix/4.2/demos/mainframe/appl_first/weblogic/db2/insecure/doc_literal/java_client. The client code is as follows:

76



/*********************************************************************** Copyright (c) 1993-2006 IONA Technologies PLC.* All Rights Reserved.***********************************************************************/

package java_client;

// service access classesimport remote_service.DbSample;import remote_service.DbSample_Impl;import remote_service.DbSampleSOAPPort;import remote_service.DbSampleSOAPPort_Stub;

// datatype classesimport remote_types.*;

import weblogic.webservice.binding.BindingInfo;

77


public class DbSample_client{ public static void main(String[] args) { try { DbSample service_proxy = new DbSample_Impl(); DbSampleSOAPPort service_port = service_proxy.getDbSampleSOAPPort(); // set_verbose_mode(service_port, true);

String department_name = "PLANNING"; if (args.length > 0) { department_name = args[0]; }

ResultSet_List_By_Department[] output_param = get_records(department_name, service_port); display_records(output_param); } catch (Throwable t) { System.err.println("Exception occured during demo run: " + t); t.printStackTrace(); return; }

System.out.println("DB2 Demo completed successfully"); }

public static void set_verbose_mode( DbSampleSOAPPort service_port, boolean onOff ) { DbSampleSOAPPort_Stub stub = (DbSampleSOAPPort_Stub)service_port; BindingInfo info = (BindingInfo) stub._getProperty("weblogic.webservice.bindinginfo"); info.setVerbose(onOff); }

public static ResultSet_List_By_Department[] get_records( String department_name, DbSampleSOAPPort service_port ) throws java.rmi.RemoteException

78


{ Input_List_By_Department dept = new Input_List_By_Department(department_name); List_By_Department input_param = new List_By_Department(dept);

System.out.println("Performing lookup of department: " + department_name); List_By_DepartmentResponse result = service_port.list_by_department(input_param); ResultSet_List_By_Department[] resultset = result.getResultset(); return resultset; }

public static boolean display_records( ResultSet_List_By_Department[] rec ) { System.out.println("Number of rows returned: " + rec.length + "\n"); for (int i = 0; i < rec.length; i++) { System.out.println("Department record number " + i + ":"); System.out.println(" DEPTNO : " + rec[i].getDEPTNO()); System.out.println(" DEPTNAME : " + rec[i].getDEPTNAME()); System.out.println(" MGRNO : " + rec[i].getMGRNO()); System.out.println(" ADMRDEPT : " + rec[i].getADMRDEPT()); System.out.println(" LOCATION : " + rec[i].getLOCATION()); System.out.println(""); } return true; };

}

79


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 BEA�s WebLogic Platform 8.1 SP3, if you need to set up your client environment, open the InstallDir/artix/4.2/demos/mainframe/index.html file in your Artix installation on Windows or UNIX, and click the Webservices Product Development Environment Setup link for instructions.

2. Open a DOS command prompt and navigate to the InstallDir/artix/4.2/demos/mainframe/appl_first/weblogic/db2/insecure/

doc_literal/java_client directory (where InstallDir represents the full path to your Artix installation on Windows or UNIX).


Windows:

UNIX:

This generates the WebLogic Web services client proxy classes and type helpers, compiles the generated application Java files, and produces Java bytecode class files.

build http://hostname:port/ionasoap/DbSample

build.sh http://hostname:port/ionasoap/DbSample

80


Running the client To run the client on Windows, enter either of the following commands:

� java -cp .;%CLASSPATH% java_client.DbSample_client� build run_client

To run the client on UNIX, enter either of the following commands:

� java -cp .;$CLASSPATH java_client.DbSample_client� build.sh run_client

81


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

82

Index
Symbols.NET client demonstration
running against DB2 SQL Web service 71

AArtix client demonstration

running against DB2 SQL Web service 64Artix Designer for z/OS usage summary

for exposing CICS or IMS applications as Web services 33

CCICST JCL

for running in server mode 27CICS transformer service

starting in server mode 24

DDB2 SQL queries

exposing as Web services 15�??, 21�??, 31�??, 61�82

demonstration client.NET

running against DB2 SQL Web service 71Artix

running against DB2 SQL Web service 64output

running against DB2 SQL Web service 82

WebLogicrunning against DB2 SQL Web service 76

JJCL

CICST, for server mode 27

Ooperations

Web service, defining further 44

Sserver mode

starting CICS transformer service in 24

Ttransformer service

starting in server mode for CICS 24

WWebLogic client demonstration

running against DB2 SQL Web service 76Web service operations

defining further 44Web services

exposing DB2 SQL queries as 15�??, 21�??, 31�??, 61�82

83

INDEX

84

service-enabling db2 sql

Documents

db2 operations

db2 view53 figure

zos perspective38 figure

db2 sql statements

db2 sql version

zos project

use of artix

db2 sql queries