z/TPF DASD usage reporting tool readme Copyright IBM Corporation 2020 US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. NOTE: Before using this information and the product it supports, read the general information under "Notices" in this document. Contents ________ This file includes the following information: 1.0 Introduction 2.0 Change history 3.0 Prerequisites 4.0 Installing the z/TPF DASD usage reporting tool 6.0 Running the z/TPF DASD usage reporting tool 7.0 Known problems and workarounds 8.0 Other sources of information 9.0 Notices 9.1 Trademarks 9.2 Warranty 9.3 Third party license and terms 1.0 Introduction _________________ z/TPF DASD usage reporting tool The z/TPF DASD usage reporting tool works with continuous data collection (CDC) and the CDC_DASD_METRICS data type to produce a report of DASD usage during a user-specified time period. The IBM Tivoli Monitoring Agent for z/TPF does not process the DASD metrics that are provided with APAR PJ46077. If you want to collect and analyze this information, you must write a tool to retrieve and process the data. The z/TPF DASD usage reporting tool is an example of how to get the CDC information from the IBM MQ queue and how locate the CDC_DASD_METRICS data type in the CDC information. In addition, this tool provides an example of how to determine certain values such as average reads and writes per second and average service time. Additionally, you can use this tool to create DASD usage reports for z/TPF test systems or z/TPF production systems. The z/TPF DASD usage reporting tool creates a report of DASD usage over a specified time period for the z/TPF system where CDC is running. There are two report formats. The format is dependent on the file extension that is requested. * If the file extension is .txt, the report is easily readable. * If the file extension is .csv, the report is in a comma separated variable format. The intent is for the report to be used in a spreadsheet or a relational database. The report contains information for all online modules on the z/TPF system. There is no information for general files, general data sets, modules that are the destination of an all file copy process, or HyperPAV alias symbolic device addresses (SDAs). The report is organized by symbolic module. The report contains information that is similar to z/TPF data reduction random file access summary report. 2.0 Change history ___________________ 2020JUN16 Initial version 3.0 Prerequistes _________________ 1. An IBM MQ client or MQ server must be installed on your Linux system . For more information about installing an IBM MQ client, see https://www.ibm.com/support/pages/mqc91-ibm-mq-clients Additional information: * The z/TPF DASD usage reporting tool is a procedural application. For information about how to build a procedural application with IBM MQ, see https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.0.0/com.ibm.mq.dev.doc/q028330_.htm * The z/TPF DASD usage reporting tool is a 64-bit application. For information about hot to build a 64-bit application with IBM MQ see https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.0.0/com.ibm.mq.dev.doc/q028490_.htm 2. On the z/TPF system the following must be installed and in use. * PJ46077 must be installed. * Continuous data collection (CDC) must be started. * The CDC_DASD_METRICS data type must have a frequency greater than zero. 4.0 Installing the z/TPF DASD usage reporting tool ___________________________ To install the z/TPF DASD usage reporting tool, complete the following steps: 1. Use FTP to transfer the tar file (amqsCDCdasd.tar.gz) to your Linux system. This file can be placed in any directory as a holding location, for example, /tmp/ztpftar. 2. On the Linux system, extract the files from the amqsCDCdasd.tar.gz file: tar -xvzf amqsCDCdasd.tar.gz 3. Compile the amqsCDCdasd.c program, which is a non-threaded 64-bit C client application. Ensure that the program has execute file permissions. gcc -m64 -o amqsCDCdasd_64 amqsCDCdasd.c -I MQ_INSTALLATION_PATH/inc -L MQ_INSTALLATION_PATH/lib64 -Wl,-rpath=MQ_INSTALLATION_PATH/lib64 -Wl,-rpath=/usr/lib64 -lmqic For example, the following command is used to compile the amqsCDCdasd.c program in the IBM TPF lab: gcc -m64 -o amqsCDCdasd_64 amqsCDCdasd.c -I/opt/mqm/inc -L/opt/mqm/lib64 -Wl,-rpath=/opt/mqm/lib64 -Wl,-rpath=/usr/lib64 -lmqic Enter the following command to ensure the program has the execute file permissions: chmod +x amqsCDCdasd_64 4. Place the executable file in a directory that is accessible with the PATH setting. 6.0 Running the z/TPF DASD usage reporting tool ________________________ Before you run the program on Linux, enter the following command, where is the IP address of the target z/TPF system where CDC is running. export MQSERVER=CDCSVRCHL/TCP/'' To run the z/TPF DASD usage reporting tool at a Linux prompt, enter the following command: amqsCDCdasd_64 [flags] Where the required positional parameters are: * amqsCDCdasd_64 = name of the program that is being executed * = For CDC, the IBM MQ queue name is CDCRTQ.cpuid where cpuid is the CPU ID of the z/TPF processor. For example, CDCRTQ.B is the CDC MQ queue name for CPU B. * = TPFQM is an example. Optional keyword parameters [flags]: -t - Specifies the number of seconds that amqsCDCdasd_64 will collect data, where is the number of seconds. It is recommended to use the -t parameter. -r - Specifies the name of the file where the report will be written, where is the name of a file. If you do not specify this option, the report will be written to the Linux session where you entered the command. The file must have a file extension of .txt or .csv. If .txt is used, the file is more easily readable. If .csv is used, the file is a comma separated variable format and is intended for a spreadsheet or a relational database. It is recommended to use the -r option. -a - Appends to the file that is specified by the -r option. If you do not specify this option, the file specified by the -r option is overwritten. -save Saves the report every minute. A report will be created every minute that covers the minute. If the file extension is .txt, there will also be a report at the end that covers the entire time period. If the file extension is .csv, there will not be an entry at the end that covers the entire time period. If you do not specify -save, the report will cover the entire time period. You can use the -save option to prevent the loss of data. If you do not specify the -save option, and if the report period is a long period of time (such as 1 hour or 1 day) and if the program ends, all data will be lost. If you specify the -save option, data is saved as time progresses. This option also provides a breakdown of what happens every minute. Examples The following example processes a single MQ GET request for CDC information and displays the report on your Linux system. If the frequency of the CDC_DASD_METRICS data type in CDC is greater than the frequency for other data types, the DASD usage information might not be reported. amqsCDCdasd_64 CDCRTQ.B TPFQM The following example processes MQ GET requests for CDC information over 60 seconds. The report is written to the CDCtest.txt file. If the frequency of the CDC_DASD_METRICS data type in CDC is greater than 60 seconds, the DASD usage information might not be reported. amqsCDCdasd_64 CDCRTQ.B TPFQM -t 60 -r CDCtest.txt The following example processes MQ GET requests for CDC information over 600 seconds or 10 minutes. The report is written to the CDCtest.txt file. The report will be saved every minute over the 10 minute time period. amqsCDCdasd_64 CDCRTQ.B TPFQM -t 600 -r CDCtest.txt -save The following example shows the output in Linux when the tool is run. The time period for this example is 180 seconds and the report is written to the CDC_0617_1.txt file. Status messages are sent every time that the DASD metrics are in the CDC information. The report is saved when a minute boundary is crossed. Also, the tool disconnects and reconnects to the MQ queue manager every 120 seconds in order to prevent a long running ECB on z/TPF. shershn@linuxtpf:~/PJ46077> amqsCDCdasd_64 CDCRTQ.B TPFQM -t 180 -r CDC_0617_1.txt -save amqsCDCdasd - Started at Wed Jun 17 15:24:18 2020 amqsCDCdasd - MQCONNX request connection to TPFQM on Wed Jun 17 15:24:18 2020 amqsCDCdasd - MQOPEN request for queue CDCRTQ.B on Wed Jun 17 15:24:18 2020 Received DASD Metrics that was collected on 20200617 at 152407 that covered 10.46 seconds on Wed Jun 17 15:24:18 2020 Received DASD Metrics that was collected on 20200617 at 152417 that covered 10.38 seconds on Wed Jun 17 15:24:18 2020 Received DASD Metrics that was collected on 20200617 at 152427 that covered 9.61 seconds on Wed Jun 17 15:24:22 2020 Received DASD Metrics that was collected on 20200617 at 152437 that covered 9.81 seconds on Wed Jun 17 15:24:32 2020 Received DASD Metrics that was collected on 20200617 at 152447 that covered 9.75 seconds on Wed Jun 17 15:24:42 2020 Received DASD Metrics that was collected on 20200617 at 152457 that covered 10.42 seconds on Wed Jun 17 15:24:52 2020 Received DASD Metrics that was collected on 20200617 at 152507 that covered 10.46 seconds on Wed Jun 17 15:25:02 2020 amqsCDCdasd - Saving the report on Wed Jun 17 15:25:02 2020 Received DASD Metrics that was collected on 20200617 at 152517 that covered 9.43 seconds on Wed Jun 17 15:25:12 2020 Received DASD Metrics that was collected on 20200617 at 152527 that covered 9.70 seconds on Wed Jun 17 15:25:22 2020 Received DASD Metrics that was collected on 20200617 at 152537 that covered 10.80 seconds on Wed Jun 17 15:25:32 2020 Received DASD Metrics that was collected on 20200617 at 152547 that covered 9.51 seconds on Wed Jun 17 15:25:42 2020 Received DASD Metrics that was collected on 20200617 at 152557 that covered 10.35 seconds on Wed Jun 17 15:25:52 2020 Received DASD Metrics that was collected on 20200617 at 152607 that covered 9.39 seconds on Wed Jun 17 15:26:02 2020 amqsCDCdasd - Saving the report on Wed Jun 17 15:26:02 2020 Received DASD Metrics that was collected on 20200617 at 152617 that covered 10.71 seconds on Wed Jun 17 15:26:12 2020 amqsCDCdasd - Intermediate close and disconnect is complete amqsCDCdasd - MQCONNX request connection to TPFQM on Wed Jun 17 15:26:22 2020 amqsCDCdasd - MQOPEN request for queue CDCRTQ.B on Wed Jun 17 15:26:22 2020 Received DASD Metrics that was collected on 20200617 at 152627 that covered 9.70 seconds on Wed Jun 17 15:26:22 2020 Received DASD Metrics that was collected on 20200617 at 152637 that covered 9.67 seconds on Wed Jun 17 15:26:32 2020 Received DASD Metrics that was collected on 20200617 at 152647 that covered 10.40 seconds on Wed Jun 17 15:26:42 2020 Received DASD Metrics that was collected on 20200617 at 152657 that covered 10.39 seconds on Wed Jun 17 15:26:52 2020 Received DASD Metrics that was collected on 20200617 at 152707 that covered 9.59 seconds on Wed Jun 17 15:27:02 2020 amqsCDCdasd - Saving the report on Wed Jun 17 15:27:02 2020 Received DASD Metrics that was collected on 20200617 at 152717 that covered 9.68 seconds on Wed Jun 17 15:27:12 2020 amqsCDCdasd - Saving the report at Wed Jun 17 15:27:22 2020 amqsCDCdasd - Creating the final the report at Wed Jun 17 15:27:22 2020 Number of intervals with DASD Metrics = 20 Number of intervals without DASD Metrics = 22 amqsCDCdasd - Ended at Wed Jun 17 15:27:22 2020 shershn@linuxtpf:~/PJ46077> 8.0 Other sources of information _________________________________ z/TPF product documentation in IBM Knowledge Center: https://www.ibm.com/support/knowledgecenter/SSB23S_latest 9.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. 9.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. 9.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. 9.3 Third party license and terms ***************************************************************************************** * NOTE TO AUTHOR: If your tool or driver uses open source or other third party code, be * sure include any required license terms here. Work with legal as needed. If there are * no third party license terms required, just delete this section. *****************************************************************************************