IBM z/TPF Limited License for Development and Test readme Copyright IBM Corporation 2016 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 z/TPF Limited License for Development and Test 4.1 Hints and tips for copying your z/TPF volumes to zD&T 4.2 Hints and tips for creating a device map 5.0 Running z/TPF Limited License for Development and Test 6.0 Known problems, workarounds, and other considerations 6.1 Potential issues during z/TPF IPL or normal operations 6.2 Additional information about z/TPF processing and usage 7.0 Other sources of information 8.0 Notices 8.1 Trademarks 8.2 Warranty 1.0 Introduction _________________ IBM® z/TPF Limited License for Development and Test provides you entitlement to run a copy of your z/TPF system on IBM® z Systems® Development and Test Environment. Use the information in this README together with the Quick Start Guide for z/TPF Limited License for Development and Test that is provided with the product download. Restriction: This Program is licensed only for development, testing, employee education, or demonstration of your applications that run on z/TPF. The Program may not be used for production workloads of any kind, nor robust development workloads, including without limitation, production module builds, preproduction testing, stress testing, or performance testing. 2.0 Change history ___________________ 2016Nov17 Initial version 3.0 Prerequistes _________________ * z Systems Development and Test Environment (zD&T), Version 10 or later * z/TPF APAR PJ44374, installed on the copy of the z/TPF system that you plan to run on zD&T. 4.0 Installing z/TPF Limited License for Development and Test ______________________________________________________________ Use the following hints and tips with the Quick Start Guide to install the z/TPF Limited License for Development and Test. 4.1 Hints and tips for copying your z/TPF volumes to zD&T * Consider using a file naming convention to help to uniquely relate the Linux file to the DASD that the file was copied from. For example, use the volume serial number of the associated DASD (such as, BJ0001) for the Linux file name. * To ensure that all DASD modules that you need are copied (or refreshed), consider adding all of your hckd2ckd command statements to a migration script. * Copying VPARS volumes might not work. Consider copying a z/TPF test system that is loaded on non-VPARS DASD modules. 4.2 Hints and tips for creating a device map * The number after the device manager name in the manager stanza is arbitrary, but required. For more information, see Chapter 3 of the zPDT Guide and Reference. * Set up an OSA connection based on one of the adapters available. Use the zPDT find_io command to display the adapters. The find_io command provides the path name and interface name for the adapters that are available. Specify the path name, and if necessary, the interface name on the awssoa device manager statement. * Tapes must be initialized before they can be mounted to the z/TPF system. When you use the emulator, you must create a file and initialize the file in the file system. To create emulated tape files for your device map, use the aws_tapeInit command. * To keep files in order, keep the tape file name the same as the volume serial number (VSN) that is assigned to the tape. For example, to create a tape file with a VSN of TAPE01, enter the following command: aws_tapeInit tape01 /tmp/mywork/TAPE01 Note: The aws_tapeInit command translates the specified VSN to uppercase EBCDIC characters. * Ensure that you create the file with the correct Linux file permissions to match the intended use on the z/TPF system. For example, if you plan to write to the tape (such as an RTA tape), use the chmod command to define write permissions for the file. * If you want to examine existing emulated tape files for standard header labels, use the aws_tapeInsp command. If the tape file appears to be in awstape format, the command checkes for VOL1, HDR1, and HDR2 labels. * Contact your IBM Software Support representative or search IBM Support Fix Central (https://www.ibm.com/support/fixcentral/options) for the latest version of the aws_tapeInit tool. * You can use a 3215 or 3270 operator console in a zD&T environment. Use the zPDT 3270port statement in the system stanza to define the port number for TN3270 connections. For more information about the aws3274 device manager and other 3270 support information, see the zPDT Guide and Reference. Note: x3270 was used during testing to emulate a 3270 console. * Consider defining a system printer to make it easier to get formatted dumps. To set up a printer, see the information about the zPDF awsprt device manager in Chapter 3 of the zPDT Guide and Reference. For more information about accessing dumps, see the considerations in section 6.2 of this readme. * After you build the device map, to check the file for errors, run the zPDT awsckmap command. For information about the command syntax, see Chapter 4 of the zPDT Guide and Reference. 5.0 Running z/TPF Limited License for Development and Test ___________________________________________________________ 1. Start the zPDT emulator by using the zPDT awsstart command. For more information about the syntax of the awsstart command, see Chapter 4 of the zPDT Guide and Reference. Notes: * If you use a 3215 console, consider using two Linux windows: one window to enter commands and another window to see the output. The output window is the window where you enter the awsstart command. Open another Linux window to enter z/TPF commands. To route data to the 3215 emulator, you must prefix the data with awsin. For example, awsin zdsys routes the ZDSYS command to the IPLed z/TPF system through the 3215 emulator. * If you use a 3270 console, you do not have to prefix the commands with awsin. 2. IPL the z/TPF system by using the zPDT ipl command and specifying the prime module symbolic device address (SDA). For example: ipl 1ec0 clear 6.0 Known problems, workarounds, and other considerations __________________________________________________________ There are some issues that might occur during z/TPF IPL or normal operations that you might need to address, as well as some other considerations related to z/TPF processing and usage. 6.1 Potential issues during z/TPF IPL or normal operations * The XML parser might take longer to process deployment descriptors through common deployment; consider increasing the application timeout for the parser. For example, enter the following z/TPF command: ZAPAT CXML TIMEOUT-65535 C-B * DASD I/O might not complete as quickly in the emulated environment. If stalled or potentially stalled module queue messages appear frequently on the z/TPF system, consider increasing the DASD lost interrupt timeout value on this system. Enter the z/TPF ZSONS ALTER LOSTINT command with the TIME parameter specified to increase the lost interrupt timeout value. * The z/TPF system that you copied from has different OSA adapter information than the the information that is defined in the device map file. To create the OSA connection information, complete the following steps: 1. Enter the ZOSAE command with the DELETE parameter specified to delete the connection that was copied when you copied the z/TPF volumes to zD&T. 2. Enter the netstat command with the -r option specified to determine the gateway information for this Linux system. 3. Enter the ZOSAE command with the DEFINE parameter specified to define the connection for this Linux system. * If you use a 3215 console, some z/TPF display messages might be truncated because the emulator does not process the hexadecimal x'00' value the same way that z/VM or TPF Operations Server does. (On 3270 consoles, the display messages are not truncated.) For more information, contact IBM Software Support. 6.2 Additional information about z/TPF processing and usage * You cannot use the ZRIPL command in a multiple I-stream emulated environment. To IPL the z/TPF system in this enviroment, enter the zPDT ipl command. Note: The ipl command is entered through zPDT, not on the z/TPF system. If you issue the ipl command on the z/TPF system with the awsin command, an error is issued. * The CP trace facility commands are not available. To perform simple tracing and displays use zPDT commands such as adstop, cpu, d, and start. For more information about these commands, see Chapter 4 of the zPDT Guide and Reference. * If your OSA connection is established, you can use the z/TPF debugger session in IBM TPF Toolkit to trace real-time applications. * The ability to FTP loadsets correctly to the z/TPF system can be affected by the large-receive-offset (LRO) and generic-receive-offset (GRO) settings in your Linux on z Systems environment. To ensure that FTP functions correctly, consider disabling these settings. To disable the settings, complete the following steps: 1. Display the settings for your Linux environment. Enter the following command, where X is the number of the interface that is being used for your OSA adapter emulator: ethtool -k ethX 2. If either the LRO or GRO setting is ON, consider disabling them. Enter the following commands, where X is the number of the interface that is being used for your OSA adapter emulator: ethtool -K ethX lro off ethtool -K ethX gro off Note: This modification is not permanent and you might need to enter these commands each time the Linux system is restarted. For your distribution of Linux, consider updating a script that is run during restart to maintain these settings. * You might not have access or ability to write to tape and easily access dumps. Consider using one of the following methods to debug your application: * Set the DBUG parameter on the ZASER command to catch dump data, and use the TPF Dump Viewer in TPF Toolkit to debug application dumps. * If you have a printer defined in your device map file, set the PRT parameter in the ZASER command to have the dump formatted by the z/TPF system and write the dump to the file associated with the real-time printer. When a dump is issued, to close the file, enter the awsmount command with the -u option specified. For example, if your real-time printer is 0x00E, enter the command: awsmount 00E -u For new dumps to be written, you must mount a new file as the output location for the real-time printer. To create a new file, enter the awsmount command with the -m option specifie. For example, awsmount 00E -m ./printer_00E.lst -rw To set up the real-time printer and default output file name in your device map, see the information about the awsprt device manager in Chapter 3 of the zPDT Guide and Reference. 7.0 Other sources of information _________________________________ For more information about starting and operating z/TPF Limited License for Development and Test and z Systems Development and Test Environment, see the following resources: * IBM z/TPF product website (http://www.ibm.com/software/products/en/ztransaction-processing-facility) * IBM z/TPF product documentation on IBM Knowledge Center (http://www.ibm.com/support/knowledgecenter/SSB23S) * IBM z Systems Development and Test Environment product website (http://www.ibm.com/software/products/en/ibm-z-systems-development-and-test-environment) * IBM z Systems Development and Test Environment product documentation on IBM Knowledge Center (http://www.ibm.com/support/knowledgecenter/SSTQBD) * IBM zPDT Guide and Reference (http://www.redbooks.ibm.com/abstracts/sg248205.html) * IBM System z Personal Development Tool Messages and Codes (http://www.redbooks.ibm.com/abstracts/sg248103.html) * Rational z Systems Development and Testing Hub on IBM developerWorks® (https://www.ibm.com/developerworks/community/groups/service/html/communityview?communityUuid=5d4610cf-76f1-46d9-806f-88f157367222) 8.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. 8.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. 8.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.