Health Center API sample driver readme Copyright IBM Corporation 2019 US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. NOTE: Before using this information and the product it supports, read the general information under "Notices" in this document. CONTENTS ________ 1.0 Introduction 1.1 Driver components and architecture 2.0 Change history 3.0 Prerequisites 4.0 Installing the driver 5.0 Configuring the z/TPF system 6.0 Running the Health Center API sample 7.0 Notices 7.1 Trademarks 7.2 Warranty 1.0 Introduction __________________ This sample driver code demonstrates how to utilize the Health Center API in a Java application. For a description of how to use the Health Center API, see the documentation in IBM Knowledge Center ( https://www.ibm.com/support/knowledgecenter/en/SS3KLZ/com.ibm.java.diagnostics.healthcenter.doc/topics/api.html). 1.1 Driver components and architecture The Health Center API sample code contains the following core components, which represent the Java application: o Hcclientdrv.java is a Java application that calls the Health Center API o myClassEvenListener.java is a class to handle the class event o myGCEvenListener.java is a class to handle the garbage collection event o myProfilingEvenListener.java is a class to the handle profiling event o myThreadEvenListener.java is a class to handle the thread event 2.0 Change history ___________________ 2019May21 Initial version 3.0 Prerequisites __________________ The following list provides the required release levels: o z/TPF with APAR PJ45580 and all prerequisite APARs applied. For more information, see the APEDIT for PJ45580 (https://www.ibm.com/support/docview.wss?uid=swg1PJ45580). For more information about installing, building, and configuring z/TPF support for Java, see the z/TPF product documentation in IBM Knowledge Center (https://www.ibm.com/support/knowledgecenter/SSB23S). o Java Agent for IBM Monitoring and Diagnostic Tools - Health Center on z/TPF https://www-01.ibm.com/support/docview.wss?uid=swg1PJ45580 4.0 Installing the driver __________________________ 1) Use FTP to transfer the tar file (Hcclientdrv.tar.gz) to your Linux on IBM Z build system. This file can be placed in any directory as a holding location, for example, /tmp/ztpftar 2) Create a root directory to hold the unpacked files, for example, /ztpfdrvs 3) Extract the source code from the tar file by entering the following commands: cd /ztpfdrvs tar -xvzf /tmp/ztpftar/Hcclientdrv.tar.gz The project source files are extracted in the following directory structure: List of files: ------------- o ./hcclientDrv * hcclientdrv.mak * hcclientdrv.cntl * hcclientdrv.loadfile * pom.xml * ./src/com/ibm/drivers/Hcclientdrv.java * ./src/com/ibm/drivers/myClassEventListener.java * ./src/com/ibm/drivers/myGCEventListener.java * ./src/com/ibm/drivers/myProfilingEventListener.java * ./src/com/ibm/drivers/myThreadEventListener.java 4) Create a maketpf.cfg file with the following contents: APPL_ROOT := /ztpfdrvs TPF_ROOT := /ztpf LOADTPF_IP:=ftp://@ TPF_BSS_NAME := BSS #TPF_SS_NAME := #USER_VERSION_CODE := a) Set APPL_ROOT to the directory that contains the driver source code that was extracted. b) Set TPF_ROOT to the directory that contains the z/TPF source code. c) Set LOADTPF_IP to the correct user/host of your z/TPF system. d) Set TPF_BSS_NAME to the basic subsystem name of your z/TPF system. By default, this value is set to BSS. e) Optional: Set TPF_SS_NAME to the subsystem name. f) Optional: Set USER_VERSION_CODE to any 2-character string. The 2-character string that you set is appended to the shared objects that are built. By default, this value is set to null. For details about these variables, enter man maketpf.cfg on your Linux on Z build system. 5) Direct link to configuring a local maven repo: https://www.ibm.com/support/knowledgecenter/SSB23S_1.1.0.15/com.ibm.java.80.doc/user/cfglinxmaven_local.html 6) Run the maketpf utility with the accompanied control file (hcclientdrv.cntl) to assemble, compile, and link the driver programs: bldtpf /ztpfdrvs/hcclientdrv/hcclientdrv.cntl 7) Use the standard load procedure to transfer and load the driver shared jar files (Java programs). loadtpf -s hccfload /ztpfdrvs/hcclientdrv/hcclientdrv.loadfile 8) Use the standard procedure to activate these loadsets on the z/TPF system. For more information about program management, including how to build and load programs to the z/TPF system, see the z/TPF product documentation in IBM Knowledge Center (https://www.ibm.com/support/knowledgecenter/SSB23S). 5.0 Configuring the z/TPF system _________________________________ Ensure that you have a Java application running with an attached Health Center agent with default port 1972. 6.0 Running the Health Center client driver ___________________________________________ By default, the jar files are deployed in the /sys/tpf_pbfiles/apps/hcclientdrv directory on the z/TPF system. Before you run the driver, enter the following commands: 1. zfile export hcclientdrv=/sys/tpf_pbfiles/apps/hcclientdrv/monitoring-api-1.0.jar 2. zfile export hcclientdrv=$hcclientdrv:/sys/tpf_pbfiles/apps/hcclientdrv/Hcclientdrv.jar 3. Define your domain and host: zdtcp do define-{your domain} zdtcp ho define-{your houst} o The driver will run for 5 minutes User: zfile java -Xhealthcenter -cp $hcclientdrv com.ibm.drivers.Hcclientdrv System: While Hcclientdrv is running the following logs file gets generated: /tmp/classapi.log /tmp/gcapi.log /tmp/profilingapi.log /tmp/threadapi.log 7.0 Notices ____________ This information was developed for products and services offered in the US. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive, MD-NC119 Armonk, NY 10504-1785 US For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan Ltd. 19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo 103-8510, Japan INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk. IBM may use or distribute any of the information you provide in any way it believes appropriate without incurring any obligation to you. 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 Director of Licensing IBM Corporation North Castle Drive, MD-NC119 Armonk, NY 10504-1785 US Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. 7.1 Trademarks IBM, the IBM logo, and ibm.com are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Java and all Java-based trademarks are trademarks or registered trademarks of Oracle and/or its affiliates. 7.2 Warranty This package is provided on an "as is" basis. There are no warranties, express or implied, including the implied warranties of merchantability and fitness for a particular purpose. IBM has no obligation to provide service, defect correction, or any maintenance for the package. IBM has no obligation to supply any updates or enhancements for the package to you even if such are or later become available.