Page 1 of 6 tpfdf/rt/readme_sdo.txt Service Data Objects (SDO) Access to z/tpfdf - PUT 05 Copyright International Business Machines Corporation 2008. All Rights Reserved US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Note: Before using this information and the product it supports, read the general information in the 10.0 NOTICES section of this document. ************ * CONTENTS * ************ This file includes the following information: 1.0 DESCRIPTION 2.0 PREREQUISITES 3.0 INSTALLATION OVERVIEW 4.0 INSTALL SDO 5.0 INSTALL AN XML PARSER 6.0 INSTALL THE WEBSPHERE MQ CLIENT 7.0 INSTALL THE z/tpfdf DATA ACCESS SERVICE (DAS) 8.0 INSTALL AND USE ECLIPSE SOFTWARE DEVELOPMENT KIT (SDK) INTEGRATED DEVELOPMENT ENVIRONMENT (IDE) (OPTIONAL) 8.1 Install Eclipse Software Development Kit (SDK) Integrated Development Environment (IDE) 8.2 Open the Java Perspective 9.0 INSTALL AND USE THE SDO SAMPLE APPLICATION (OPTIONAL) 9.1 Install the SDO Sample Application 9.2 Use the SDO Sample Application 10.0 NOTICES 10.1 Trademarks * 1.0 DESCRIPTION * Service data objects (SDO) access to z/tpfdf provides a framework for data application program development that includes an architecture and APIs. SDO access to z/tpfdf provides remote client applications access to z/tpfdf databases. You can use SDO access to z/tpfdf to write Java application programs by using a combination of the z/tpfdf data access service (DAS) application programming interfaces (APIs) with the SDO specification APIs. This combination of application interfaces are provided to allow client application programs that are running on an application server or workstation to access and update z/tpfdf databases using SDO. Using SDO access to z/tpfdf, it is possible to fully populate a new database that was defined and initialized previously on the z/tpf system by using database definitions (DBDEFs) and data definition assembler macros (DSECTs). See z/tpfdf Database Administration in the TPF Product Information Center for more information about DBDEFs and DSECTs.
Page 2 of 6 ** * 2.0 PREREQUISITES * ** The SDO access to z/tpfdf installation process requires the following: o Eclipse Modeling Framework (EMF) version 2.3.0 o Java Development Kit (JDK) version 5.0 o SAX2-compliant XML parser o Websphere MQ client. Optionally, you may find it helpful to download a software development kit (SDK) such as the Eclipse IDE for Java Developers, Eclipse Classic 3.3.1.1, or IBM TPF Toolkit for WebSphere Studio (also known as the TPF Toolkit) 3.2.2. ********** * 3.0 INSTALLATION OVERVIEW * ********** The following installation sections provide an overview for developing a working example of SDO that will run on your workstation. You should use this information to familiarize yourself with SDO concepts, the installation process, and a sample application program. This sample SDO working example will not access z/tpfdf data and will simply serve as an independent exercise. Additionally, go to http://www.ibm.com/developerworks/java/library/j-sdo for a brief overview of SDO and a sample installation. If you already have a sound understanding of SDO, you may choose to bypass the conceptual information on this web site and go directly to the sample installation instructions on the web site. We recommend that you use the sample installation information along with the information in the following installation sections to install SDO because this information provides some clarifications specific to SDO access to z/tpfdf. Be sure to read through the sample installation information in its entirety and follow all the installation steps. Note: The http://www.ibm.com/developerworks/java/library/j-sdo website may contain slightly different terms and procedures than SDO Access to z/tpfdf. You must download the following to install SDO: o Eclipse Modeling Framework (EMF) version 2.3.0 o Java Development Kit (JDK) version 5.0. See the 4.0 INSTALL SDO section of this document for these procedures. Optionally, you may choose to: o Install the sample SDO application. This application is not required to use the z/tpfdf DAS. o Download the Eclipse Software Development Kit (SDK) Integrated Development Environment (IDE) to assist you during the development process. Although it is not necessary to download the Eclipse SDK IDE, the SDO overview and sample installation information found at http://www.ibm.com/developerworks/java/library/j-sdo (mentioned previously) does assume that Eclipse is used as an IDE. See the 8.0 INSTALL AND USE ECLIPSE SOFTWARE DEVELOPMENT KIT (SDK) INTEGRATED DEVELOPMENT ENVIRONMENT (IDE) section of this document for more information. Note: The Eclipse SDK IDE is required only if you intend to use the SDO graphical user interface capabilities. * 4.0 INSTALL SDO * To install SDO, do the following:
Page 3 of 6 1. Go to http://www.ibm.com/developerworks/java/library/j-sdo to familiarize yourself with SDO. Do not follow the installation instructions found on the Web site; it is meant only as an introduction to SDO. 2. Download the Java Development Kit (JDK) by doing the following: 1. Go to http://java.sun.com/javaee/downloads/index.jsp to access JDK downloads. 2. Download JDK version 5.0. 3. Download Eclipse Modeling Framework (EMF) version 2.3.0 (which includes SDO version 1.0) by doing the following: 1. Go to http://www.eclipse.org/modeling/emf/downloads to access the Eclipse Modeling Framework (EMF) Downloads page. 2. Download either the "emf-sdo-xsd-sdk-2.3.0.zip" or the "emf-sdo-sdk-2.3.0.zip" file from the 2.3.0 link from the Archived Releases section of the page. 3. Extract the contents of the downloaded archive to a local directory which will be included in the class path for your Java application. If you have the Eclipse SDK IDE or the TPF Toolkit installed, extract the archive into the corresponding Eclipse directory. ********** * 5.0 INSTALL AN XML PARSER * ********** To use the z/tpfdf DAS to access and update z/tpfdf databases, an XML parser must be available to the z/tpfdf DAS. Although the z/tpfdf DAS implementation was developed and tested using Xerces2 Java Parser version 2.8.1, you can use any SAX2-compliant XML parser. To enable a SAX2-compliant XML parser other than Xerces2 Java Parser, you must set the Java property ZTPFDFDASXMLParser to the class name of the SAX2 XML parser and pass it through -D to JVM. For example, if you wanted an application called appname to use Crimson, which is a Java XML parser, in the ZTPFDFDAS, enter this command: java -DZTPFDFDASXMLParser="org.apache.crimson.parser.XMLReaderImpl" appname Go to http://xerces.apache.org/xerces2-j for more information about the Xerces2 Java Parser, and http://xml.apache.org/crimson for more information about Crimson. * * 6.0 INSTALL THE WEBSPHERE MQ CLIENT * * To use the z/tpfdf DAS to access z/tpfdf databases, a Websphere MQ client must be installed to establish communication between the Java client and the z/tpf system. You can download a free version of the Websphere MQ client by doing the following: 1. Go to http://www.ibm.com/software/integration/wmq/clients/ to access the IBM WebSphere MQ Web site. 2. Click the appropriate Download link. The Websphere MQ page displays. 3. Search for and download the appropriate WebSphere MQ V6.0 Client for the appropriate operating system. For example we downloaded IBM WebSphere MQ V6.0.2.3 Clients SupportPacs for Windows. 4. When the download completes successfully, verify that the com.ibm.mq.jar and connector.jar JAR files are in the class path for your Java application. *************** * 7.0 INSTALL THE z/tpfdf DATA ACCESS SERVICE (DAS) *
Page 4 of 6 *************** To install the z/tpfdf DAS, do the following: 1. Go to http://www.ibm.com/tpf/download/tools.htm to access the IBM Library Downloads for TPF Family of Products Web site. 2. Select the z/tpfdf Data Access Service (DAS) tool. 3. Click the download link for the appropriate version of the ZTPFDFDAS.zip file. 4. Place the Java archive file (ZTPFDFDAS.jar file), provided in the downloaded ZIP file, into a local directory which will be included in the class path for your Java application. ******** * 8.0 INSTALL AND USE ECLIPSE SOFTWARE DEVELOPMENT KIT (SDK) * * INTEGRATED DEVELOPMENT ENVIRONMENT (IDE) (OPTIONAL) * ******** If you want to download the Eclipse SDK IDE, continue with section 8.1 Install Eclipse Software Development Kit (SDK) Integrated Development Environment (IDE). If you already have an SDK that you will use, continue with 8.2 Open the Java Perspective. Otherwise, continue with 9.0 INSTALL AND USE THE SDO SAMPLE APPLICATION. 8.1 Install Eclipse Software Development Kit (SDK) Integrated Development Environment (IDE) ------------------------------------------------------------- To install the Eclipse SDK IDE (such as the Eclipse IDE for Java Developers or Eclipse Classic 3.3.1.1), do the following: 1. Go to http://download.eclipse.org to access the Eclipse Web site. 2. Select the Eclipse IDE for Java corresponding to the operating system and package contents that meets your needs. 3. Download Eclipse from any of the mirror sites. The name of the Eclipse file will vary based on the operating system that you are using. 8.2 Open the Java Perspective ----------------------------- If you are working with a software development kit (SDK), make sure that you have the Java perspective opened. For example, if you have the TPF Toolkit 3.2.2 installed, navigate to Window->Open Perspective->Java. **** * 9.0 INSTALL AND USE THE SDO SAMPLE APPLICATION (OPTIONAL) * **** If you want to install the sample SDO application, continue with this section. Otherwise, continue with 10.0 NOTICES. 9.1 Install the SDO Sample Application -------------------------------------- Install the sample SDO application. If you have the Eclipse SDK IDE or the TPF Toolkit installed, do the following to perform the installation: 1. Go to http://www.ibm.com/developerworks/java/library/j-sdo/#download for the actual sample SDO code (j-sdosample.zip file). 2. Navigate to File->Import->General->Existing Projects into Workspace. Select Next. 3. Select archive file and click Browse. Select the j-sdosample.zip file
Page 5 of 6 downloaded in step 1 and click Finish. 9.2 Use the SDO Sample Application ---------------------------------- Once you have downloaded and installed the following correctly, you are ready to work with the sample SDO application, which is provided as an example for your use when writing your own SDO application programs: o Java Development Kit (JDK) version 5.0 o Eclipse Modeling Framework (EMF) version 2.3.0 o Sample SDO application. See the 3.0 INSTALLATION OVERVIEW and 4.0 INSTALL SDO sections of this document for more information about installation. Note: The following procedures assume that TPF Toolkit 3.2.2 is installed. The menu options for other software development kits may be different. Run and compile the sample SDO application by doing the following: 1. Ensure the Java Perspective is opened. Navigate to Window->Open Perspective->Java. 2. Go to the Package Explorer view. Navigate to Window->Show View->Package Explorer. 3. Right click the SDOClient.java file in the SDOSample project. 4. Click Run As->Java Application. The sample SDO application will compile and run. If all prerequisites were installed correctly, no errors will be displayed and you can bypass this procedure. Otherwise, do the following: 1. Right click on the SDOSample project and select Properties. The Properties dialog box displays. 2. Click Java Build Path on the left. 3. Click the Libraries tab on the right. 4. Be sure that all of the following plug-ins are listed under the Plug-in Dependencies: o org.eclipse.emf.ecore o org.eclipse.emf.common o org.eclipse.emf.ecore.sdo o org.eclipse.emf.commonj.sdo o org.exlipse.emf.ecore.xmi o org.eclipse.emf.ecore.change Ensure that these plug-ins are included in the Java build path (project classpath). If they are not included, you might receive the following compiler error, which is common the first time that you run the sample SDO application: "The project was not built since its build path is incomplete. Cannot find the class file for java.lang.object. Fix the build path then try building this project." In this case, click "Add External JARS..." and navigate to the directory that contains the files extracted during EMF and SDO installation. Then, add the six JAR files listed previously. **************** * 10.0 NOTICES * **************** IBM may not offer the products, services, or features discussed in this information in other countries. Consult your local IBM representative for information on the products and services currently available in your area.
Page 6 of 6 Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this information. The furnishing of this information does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation Department 830A Mail Drop P131 2455 South Road Poughkeepsie, NY 12601-5400 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. 10.1 Trademarks --------------- The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM Other company, product, or service names may be trademarks or service marks of others. THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY PATENTS OR COPYRIGHTS.