64-Bit Assembler Conversion Aid README Copyright IBM Corporation 2005. All rights reserved. Note to U.S. 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 ABOUT THIS README FILE 1.1 Who should read this Readme file 1.2 How to get help 2.0 CONVERSION AID OVERVIEW 3.0 DOWNLOADING THE CONVERSION AID 4.0 INSTALLING THE CONVERSION AID 5.0 USING THE CONVERSION AID 6.0 KNOWN PROBLEMS AND WORKAROUNDS 7.0 OTHER SOURCES OF INFORMATION 8.0 NOTICES 8.1 Trademarks and service marks 1.0 ABOUT THIS README FILE This Readme file provides information about downloading, installing, and using the 64-Bit Assembler Conversion Aid. 1.1 Who should read this Readme file This Readme file is for anyone who wants to convert an assembler program or application on z/Transaction Processing Facility (z/TPF) for use in 64-bit mode. 1.2 How to get help This tool is not formally supported by the TPF Development Lab and is available for your use "as is". The "as is" tools are provided with no support intended or implied. If errors are found in the code, we make no commitment to correct them, although we might. Naturally, IBM retains all the rights to the tools as stated in the "as is" license that appears each time you download a tool. 2.0 CONVERSION AID OVERVIEW The 64-Bit Assembler Conversion Aid helps you to convert z/TPF programs and applications written in Basic Assembler Language (BAL) for use in a 64-bit environment. The conversion aid is not intended to address all conversion issues. You can run the conversion aid on a Linux machine against the following types of files: o Assembler (*.asm) o Copy Member or CSECT Copy Member (*.cpy) o Macro (*.mac). The conversion aid does the following: o Converts register instructions for use in 64-bit mode; register instructions use 64-bit values rather than 32-bit values. o Converts 31-bit and 32-bit values to 64-bit register values. o Converts most branch instructions to branch relatives (see Note 1). o Converts applicable literal instructions to immediate instructions where appropriate (see Notes 1 and 2). o Converts macro names as needed (see note 3). Notes: 1. This is one step in removing the 4-K (or base) register restriction. The conversion aid will not complete this process for you. 2. Instructions that are converted include the following: - Halfword instructions that use literals - Fullword instructions that use literal fullwords with a value less than 32,768. 3. For example, some macro names no longer include a dollar sign ($), so the conversion is to remove that symbol from the name of the macro. 3.0 DOWNLOADING THE CONVERSION AID To download the 64-Bit Conversion Aid, do the following: 1. Go to the TPF Web site and click Downloads under Fast Links, or go directly to: http://www.ibm.com/software/htp/tpf/download/tools.htm 2. Download the cvtto64.tar.gz file and place it in a directory on Linux. When moving (FTPing) the file, make sure that you use binary mode. 4.0 INSTALLING THE CONVERSION AID To install the 64-Bit Conversion Aid, do the following: 1. On the Linux system, unpack the cvtto64.tar.gz file: tar -xvzf cvtto64.tar.gz 2. Compile the cvtto64.c file and make sure that it has the execute file permissions: cc -o cvtto64.exe cvtto64.c chmod +x cvtto64.exe 3. Place the executable in a directory that is accessible via the PATH setting. 5.0 USING THE CONVERSION TOOL To convert your assembler programs for running in 64-bit mode, do the following: 1. At a Linux prompt, enter the command that does the desired conversion. Note: The following provides a basic overview of this command and information about how to use it. The opening commentary in the cvtto64.c file that you downloaded has additional information about the conversions. Refer to this information before using the conversion aid. The format for this command is: cvtto64.exe input_file output_file [flags] Where: o input_file is the path name of the .ASM, .CPY, or .MAC file that you want to convert. o output_file is the path name of the file that you want the new, converted code stored in. NOTE: The path names specified for input_file and output_file must not be the same. If you enter the same path name for both variables, your file will be destroyed. o [flags] are optional specifications for the conversions that are completed. When you do not specify any flags, the default conversion does the following: - Converts branch instructions - Converts applicable literal instructions - Converts register instructions - Uses '64MODE' as the SID code. However, if you specify any of the following flags, this default is ignored and only the actions of the specified flags will occur. You can specify any combination of the following, but omit the brackets ([ ]) when using these flags; they simply indicate that these flags are optional on the command line: o -br Converts most branch instructions. o -reg Converts most register instructions for use in 64-bit mode. o -mac Converts appropriate macro names. o -half Converts halfword instructions to 64-bit immediate instructions. o -half31 Converts halfword instructions to 31-bit immediate instructions. o -sidcode xxx Specifies the SID code to use in columns 73-80, where xxx is the 8-character desired SID code. The default SID code, if this flag is not specified, is '64MODE'. If a line should be converted, but the conversion aid is unable to convert it, SID code '64TODO' is used. o -verify Ensures that the input_file path name is for a .ASM, .CPY, or .MAC file. o -spm Converts obsolete structured programming macros (SPMs) to their replacement. The following changes will be made: #CASENTR -> #CAST #ECASE -> #ECAS #ELOOP -> #ELOP #ELSEIF -> #ELIF #ESRCH -> #EDO #ORELSE -> #OREL #SRCEX -> #DOEX #STRTSRC -> #DO 3. The output will be similar to the following: Sidcode used to mark changes is 64MODE Register instructions will be converted Branch instructions will be converted Macros will be converted Halfword instructions will be converted Input file is /u/shershn/esame/cfac40.cpy Output file is /u/shershn/source_updates/cfac40.cpy Conversion complete 254 lines converted 0 lines not converted 1332 total lines 6.0 KNOWN PROBLEMS AND WORKAROUNDS Before using this conversion aid, see the opening commentary of the cvtto64.c file that you downloaded for warnings and details. 7.0 OTHER SOURCES OF INFORMATION z/TPF product information is available at: http://www.ibm.com/software/htp/tpf/pubs/tpfpubs.htm The opening commentary of the cvtto64.c file that you downloaded has more detailed information about the conversion aid. 8.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. 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 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 USA 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 USA 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. 8.1 Trademarks and service marks The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, and 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.