Object Code Accelerator for TNS/X (OCAX) Manual

Transcription

1 Object Code Accelerator for TNS/X (OCAX) Manual HP Part Number: Published: April 2015 Edition: L15.02 and subsequent L-series RVUs

2 Copyright 2015 Hewlett-Packard Development Company, L.P. Legal Notice Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor s standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Export of the information contained in this publication may require authorization from the U.S. Department of Commerce. Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation. Intel, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java is a trademark of Oracle and/or its affiliates. Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks, and IT DialTone and The Open Group are trademarks of The Open Group in the U.S. and other countries. Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc. OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. OSF shall not be liable for errors contained herein or for incidental consequential damages in connection with the furnishing, performance, or use of this material. 1990, 1991, 1992, 1993 Open Software Foundation, Inc. The OSF documentation and the OSF software to which it relates are derived in part from materials supplied by the following: 1987, 1988, 1989 Carnegie-Mellon University. 1989, 1990, 1991 Digital Equipment Corporation. 1985, 1988, 1989, 1990 Encore Computer Corporation Free Software Foundation, Inc. 1987, 1988, 1989, 1990, 1991 Hewlett-Packard Company. 1985, 1987, 1988, 1989, 1990, 1991, 1992 International Business Machines Corporation. 1988, 1989 Massachusetts Institute of Technology. 1988, 1989, 1990 Mentat Inc Microsoft Corporation. 1987, 1988, 1989, 1990, 1991, 1992 SecureWare, Inc. 1990, 1991 Siemens Nixdorf Informationssysteme AG. 1986, 1989, 1996, 1997 Sun Microsystems, Inc. 1989, 1990, 1991 Transarc Corporation.OSF software and documentation are based in part on the Fourth Berkeley Software Distribution under license from The Regents of the University of California. OSF acknowledges the following individuals and institutions for their role in its development: Kenneth C.R.C. Arnold, Gregory S. Couch, Conrad C. Huang, Ed James, Symmetric Computer Systems, Robert Elz. 1980, 1981, 1982, 1983, 1985, 1986, 1987, 1988, 1989 Regents of the University of California.

3 Contents About This Manual...7 Supported Release Version Updates (RVUs)...7 Intended Audience...7 New and Changed Information in This Edition, How to Use This Manual...7 Notation Conventions...7 General Syntax Notation...7 Publishing History...9 HP Encourages Your Comments Introduction...11 How the Object Code Accelerator for TNS/X (OCAX) Works...11 OCAX Translation Mode...12 Usage Consideration...12 OCAX Resource Requirements...12 Cross-Platform Acceleration Preparing Your Program for TNS/X Systems...14 General Considerations...14 Results After an Overflow...14 Detection Guideline...15 Required Changes...15 Example...15 Checking Segment Limits...15 Detection Guidelines...15 Required Change...16 Extended Segment Size...16 Detection Guideline...16 Required Change...16 Variances in TNS and Accelerated Code...16 Trap Handlers That Use the Register Stack...17 Detection Guideline...17 Required Change...17 Trap Handlers That Use the Program Counter...17 Detection Guideline...18 Required Change...18 Reserved Instructions...18 Detection Guideline...18 Required Change...18 Passing the Addresses of P-Relative Objects...18 Detection Guidelines...18 Required Change...19 Nonprivileged References to System Global Data...19 Detection Guidelines...19 Required Change...19 Example...19 Segment Wrapping...19 Required Change...19 Example...19 Odd-Byte References...20 Detection Guidelines...21 Required Change...21 Contents 3

4 Recommended Changes...21 Example...21 Shift Instructions With Dynamic Shift Counts...22 Detection Guidelines...22 Required Change...23 Example...23 Data Alignment in TNS and Accelerated Code...23 Misalignment Tracing Facility...23 Misalignment Handling Preparing Programs for Acceleration...26 General Considerations...26 Run-Time Libraries...26 User Libraries...26 C Function Prototypes...26 Binder and Inspect Symbols Regions...26 Variances in Accelerated Code...27 Trap Handlers Using the ENV Registers...27 Detection Guideline...27 Required Change...27 Passing Parameters in Registers...27 Detection Guidelines...28 Required Changes...28 Examples...28 Arithmetic Left-Shift Sign Bit...29 Detection Guideline...30 Required Change...30 Example...30 Non-Standard Procedure Call or Return RP Values...30 Required Changes...30 Examples...31 Relationship Between Global and Local Data Blocks...32 Required Change...33 Example...33 Procedure Name Conflicts Using OCAX...34 Strategy for Using OCAX...34 Invoking OCAX...34 OCAX Command Usage Examples...35 Specifying the Code Space...35 Accelerating User Libraries and Shared Run-Time Libraries...35 Accelerating Programs With Embedded SQL...36 Using Obey Files...36 Comments...36 Example...36 Online Help...36 OCAX Listings OCAX Syntax and Option Summary...39 OCAX Syntax...39 OCAX Options...39 Translating a System Library...40 SL Usage Considerations...41 Translating a User Library...41 UL Usage Considerations Contents

5 Specifying an Output File Name...41 Specifying an Obey File...41 Obey Usage Considerations...41 Determining TNS Register Usage...42 Correcting a Function s Return Values Size...42 Diagnosing and Managing Register or Condition Code Inheritance...42 Diagnosing Register or Condition Code Inheritance...42 Managing Register or Condition Code Inheritance...43 IGNORE_IRn...43 IGNORE_CC...43 INHERITSRn...43 INHERITSCC...44 IGNORE_IRn, IGNORE_CC, INHERITSRn, and INHERITSCC Usage Considerations Using OCAX With Other NonStop Tools...45 OCAX and Binder...45 CHANGE...45 SHOW...45 STRIP...46 OCAX and TNSVUX...46 OCAX, OCA and Accelerator...46 Accelerating for Multiple Platforms...47 OCAX and NonStop Debugging Tools Debugging OCAX Programs...49 Differences Between Debugging TNS and Accelerated Programs...49 Register-Exact points...49 Memory-Exact Points...50 Nonexact Points...50 A Strategy for Debugging Error and Warning Messages...51 Warning Messages...51 Error Messages...53 A Data Type Correspondence and Return Value Sizes...59 Glossary...63 Index...85 Contents 5

6 Figures 1 The Acceleration Process User Program Execution Modes on TNS/X Systems Comparing TNS and Accelerated Object File Sizes Without a Symbols Region Comparing TNS and Accelerated Object File Sizes Without a Symbols Region Data Segments Passing Parameters in Registers The OCAX Translation Process Translating Using Accelerator, OCA and OCAX Translating Using OCA and OCAX...48 Tables 1 TNS Misalignment Handling Methods OCAX Options Integer Types, Part Integer Types, Part Floating, Fixed, and Complex Types Character Types Structured, Logical, Set, and File Types Pointer Types...62 Examples 1 OCAX Online Help Example...37

7 About This Manual OCAX allows you to improve the performance of programs that run on TNS/X systems. OCAX optimizes TNS programs to take advantage of the TNS/X architecture and processes TNS object files to produce accelerated object files. Most TNS object code that has been accelerated runs faster on TNS/X systems than TNS object code that has not been accelerated. Most programs written for TNS systems do not require changes to run on TNS/X systems, either with or without acceleration. The OCAX Manual describes: How OCAX works and how to determine which programs to accelerate The changes that you must make to run your TNS object on TNS/X systems; most of these changes only affect low-level TAL programs The changes that you must make to your TNS object code before processing it with OCAX OCAX syntax and command options How to set OCAX options to eliminate certain variances Supported Release Version Updates (RVUs) This publication supports L15.02 and all subsequent L-series RVUs until otherwise indicated by its replacement publication. Intended Audience This manual is intended for systems and applications programmers familiar with HP systems, the HP NonStop operating system, and the source languages of the programs to be accelerated. The manual contains all the information needed to use OCAX. New and Changed Information in This Edition, This is a new manual. How to Use This Manual The following table guides you to the sections you should read, depending on what tasks you want to perform: If you want to: Run a TNS program on a TNS/X system Accelerate a TNS program Debug an accelerated program Understand errors and warning messages Read the following chapters: Chapter 2, Preparing Your Program for TNS/X Chapter 1, Introduction Chapter 2, Preparing Your Program for TNS/X Chapter 3, Preparing Programs for Acceleration Chapter 4, Using OCAX Chapter 5, OCAX Syntax and Option Summary Chapter 6, Using OCAX with Other NonStop Chapter 7, Debugging OCAX Programs Chapter 8, Error and Warning Messages Notation Conventions General Syntax Notation This list summarizes the notation conventions for syntax presentation in this manual. Supported Release Version Updates (RVUs) 7

8 UPPERCASE LETTERS Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH Italic Letters Italic letters, regardless of font, indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name Computer Type Computer type letters indicate: C and Open System Services (OSS) keywords, commands, and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: Use the cextdecs.h header file. Text displayed by the computer. For example: Last Logon: 14 May 2006, 08:02:23 A listing of computer code. For example if (listen(sock, 1) < 0) { perror("listen Error"); exit(-1); } Bold Text Bold text in an example indicates user input typed at the terminal. For example: ENTER RUN CODE?123 CODE RECEIVED: The user must press the Return key after typing the input. [ ] Brackets Brackets enclose optional syntax items. For example: TERM [\system-name.]$terminal-name INT[ERRUPTS] A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: FC [ num ] [ -num ] [ text ] K [ X D ] address { } Braces A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: LISTOPENS PROCESS { $appl-mgr-name } { $process-name } ALLOWSU { ON OFF } 8

9 Vertical Line A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: INSPECT { OFF ON SAVEABEND } Ellipsis An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: M address [, new-value ] - ] { } An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char " Punctuation Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.#su-name Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown. For example: "[" repetition-constant-list "]" Item Spacing Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: CALL STEPMOM ( process-id ) ; If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items: $process-name.#su-name Line Spacing If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: Publishing History ALTER [ / OUT file-spec / ] LINE [, attribute-spec ] Part Number a Product Version NA NA NA Publication Date February 2015 March 2015 April 2015 HP Encourages Your Comments HP encourages your comments concerning this document. We are committed to providing documentation that meets your needs. Send any errors found, suggestions for improvement, or compliments to docsfeedback@hp.com. Publishing History 9

10 10 Include the document title, part number, and any comment, error found, or suggestion for improvement you have concerning this document.

11 1 Introduction OCAX processes TNS object code to produce accelerated object code. On TNS/X systems, accelerated object code runs significantly faster than TNS object code. This section describes how OCAX works, how to determine which programs to accelerate, and the cost in time and space to accelerate your programs. How the Object Code Accelerator for TNS/X (OCAX) Works OCAX takes as input an executable TNS object file and produces as output an accelerated object file. The accelerated object file contains both the original TNS code and the logically equivalent optimized x86 instructions (accelerated object code). The Acceleration Process (page 11) illustrates the acceleration process. Figure 1 The Acceleration Process OCAX produces for each TNS instruction its functional equivalent on the TNS/X system, in the form of either: A sequence of zero or more (usually more than one) x86 instructions A call on a millicode routine In the first and more common case, OCAX treats a TNS instruction as though it were a macro instruction, expanding it into x86 instructions. In the second, OCAX treats a TNS instruction as though it were a call on a closed subroutine, referred to as a millicode routine. Millicode routines are sets of x86 instructions that implement various complex TNS instructions and low-level functions such as exception handling, real-time translation routines, and floating-point and quad arithmetic. Millicode is functionally equivalent to TNS microcode. OCAX can produce only optimized x86 instructions for TNS instruction sequences whose exact meaning can be determined before runtime. In cases where the exact meaning cannot be determined until run time, the program makes a transition into TNS code and executes the original TNS instructions. User Program Execution Modes on TNS/X Systems (page 12) shows two of the execution modes available to user programs on TNS/X systems: TNS mode and accelerated mode. TNS mode is the operational environment in which TNS instructions execute. On TNS/X systems, TNS instructions are implemented by millicode routines. Accelerated mode is the operational environment in which x86 instructions generated by OCAX execute. On TNS/X systems, x86 instructions execute directly on the x86 processor. How the Object Code Accelerator for TNS/X (OCAX) Works 11

12 Figure 2 User Program Execution Modes on TNS/X Systems OCAX runs on TNS/E and TNS/X systems, and produces the same output in both environments: a file containing both the original TNS code and its x86 code equivalent. Accelerated object files can run on both TNS/E and TNS/X systems, although TNS/E systems ignore the x86 code. OCAX can process bound, executable object programs generated by B40 and later releases of the C, COBOL85, FORTRAN, Pascal, and TAL compilers. OCAX processes executable object programs that run only in the Guardian environment. (You cannot accelerate object programs generated by the COBOL 74 compiler.) OCAX Translation Mode You explicitly accelerate your TNS program as part of the build or install process. When you explicitly accelerate your program in this way, you are immediately alerted of any error conditions. If you do not want to accelerate a TNS object file, you can use the Binder CHANGE OCAX ENABLE OFF command to disable inadvertent acceleration. For further information about Binder commands that work with OCAX and the Binder Manual, see OCAX and Binder (page 45). Usage Consideration If a program calls a user library and that library is not already accelerated, procedures in that library execute in TNS mode. OCAX Resource Requirements OCAX, like an optimizing compiler, is both CPU-intensive and memory-intensive. Try to run OCAX on a lightly loaded processor with more than 16MB of physical memory. OCAX uses large amounts of the extended segment heap area (about 135 KB per 1000 TNS instructions). Much of this virtual memory must remain in physical memory to avoid page faults that slow OCAX. Accelerating large programs on processors with less than 16MB of physical memory can lead to unacceptable performance. Accelerated object files require more disk space and memory space than TNS object files. Comparing TNS and Accelerated Object File Sizes Without a Symbols Region (page 13) shows that an accelerated object file, without a symbols region, requires about twice as much disk storage space as the corresponding TNS object file. 12 Introduction

13 Figure 3 Comparing TNS and Accelerated Object File Sizes Without a Symbols Region Comparing TNS and Accelerated Object File Sizes Without a Symbols Region (page 13) shows that an accelerated object file, with a symbols region, requires about 25 percent more disk storage space than the corresponding TNS object file. You can strip the symbols region from the accelerated program without affecting performance. However, accelerate the TNS object file with the symbols region and then strip the symbols region. OCAX produces more efficient code from source TNS object files that contain a symbols region than those without the region. Figure 4 Comparing TNS and Accelerated Object File Sizes Without a Symbols Region The inline code expansion factor measures the worst-case increase in main memory required for accelerated code. It is the number of bytes of x86 code divided by the number of bytes of TNS code. The OCAX listing reports the inline code expansion factor. The typical inline expansion factor in executable x86 code compared to TNS code is 5-7 times. Cross-Platform Acceleration OCAX is supported on L-series systems, enabling you to accelerate TNS object files on the TNS/X platform for execution on the TNS/X platform. (You can execute a file with a TNS region only on the TNS/X platform). The TNS/E acceleration equivalent, OCA, is supported on H-series, J-series and L-series RVUs, enabling you to accelerate TNS object files for execution on the TNS/E platform. With both the accelerators you can use the TNS/X platform to create files that are executed with improved performance either on the TNS/E or the TNS/X platform. Cross-Platform Acceleration 13

14 2 Preparing Your Program for TNS/X Systems Most TNS programs written for the HP NonStop operating system run on TNS/X systems without modification. Variances between TNS and TNS/X systems, however, might require modification in some programs, particularly low-level TAL programs. This chapter steps you through: General Considerations (page 14), discusses hardware and software release issues that affect moving programs between any two different models of HP NonStop systems. Variances in TNS and Accelerated Code (page 16) discusses the changes you must make to programs because of variances between TNS and TNS/X systems. Data Alignment in TNS and Accelerated Code (page 23) discusses the data alignment requirements for TNS code and the OCAX. It also describes how to use the Misalignment Tracing Facility diagnostic tool. General Considerations This section discusses hardware and software release issues that affect moving programs between any two different models of HP NonStop systems. You must consider these issues when you prepare a program to run on TNS/X systems, whether or not you plan to accelerate the program. These issues include results after an overflow, checking segment limits, segment length, and supported operating system releases. Results After an Overflow Multiplication and division results after an overflow are undefined on all HP systems. Each HP system generates different overflow results depending on the specific hardware and algorithms used for the operation. Do not depend upon overflow results being the same on TNS/X systems as they are on TNS systems. All TNS instructions for integer multiplication and division operations (except the LMPY instruction) on TNS/X systems have undefined and incompatible TNS overflow results: IDIV DDIV QDIV LDIV IMPY DMPY QMPY All TNS instructions for addition and subtraction operations and the LMPY instruction have compatible overflow results on all TNS and TNS/X systems: IADD DADD QADD LMPY ISUB DSUB QSUB INEG DNEG QNEG 14 Preparing Your Program for TNS/X Systems

15 Detection Guideline Examine source code that explicitly disables overflow traps to make sure it tests for arithmetic overflow with the $OVERFLOW function. Also look for user written trap handlers that return after an overflow. It is good coding practice always to test for overflow, not just after multiplication and division operations. Required Changes Example Programs that expect multiplication or division operations to overflow must explicitly test for overflow and establish the desired overflow answer. Programs can test for overflow by: Using the TAL $OVERFLOW function or the COBOL85 ONSIZE error clause immediately after the arithmetic statement that might overflow Examining the bits of the operands Refer to the Guardian Programmer s Guide for information on writing overflow traps handlers. The following TAL code explicitly tests for overflow. FIXED(0) count, time, result; CODE (RDE; ANRI %577; SETE);! Disable overflow traps result := count * time; IF $OVERFLOW THEN! Test immediately for overflow result := 0D;! Fix the overflow result Checking Segment Limits Erroneous programs which access memory beyond the logical end of a memory segment may fail differently and at different moments on TNS, TNS/R, TNS/E, and TNS/X systems, due to differences in memory page sizes. A segment's requested logical size, in bytes, is rounded up to a whole number of pages, where the page size depends on the host machine and NSK software release. Memory pages are 2 Kbytes each on TNS CISC systems, 4 K or 16 Kbytes on TNS/R systems, and 16 K or 64 Kbytes each on TNS/E and TNS/X systems. Erroneous program references beyond the requested logical end of the segment, but before the actual end of that last memory page, will go undetected. As a result of these differences, addressing past the logical end of segments may fail later or not at all depending on the system. You can notice this difference when debugging addressing errors. Detection Guidelines Addressing errors are reported as illegal address reference traps which are generally fatal. Earlier machines are stricter than newer machines and trap out on more cases of bad addresses that are slightly too high, because of their smaller page sizes. The following example shows a TNS/X system with an extended segment of 3.5 memory pages. On TNS/X systems, a program can reference data in addresses from the end of the allocated segment until the end of the memory page (area x between %h and %h00083fff) without an exception. General Considerations 15

16 Required Change If your programs reference data beyond a segment s logical limit, eliminate these references. Extended Segment Size The operating system now defines the maximum size of the selectable extended data segment at address 0x to be MB (0x07F80000) on all systems. Operating system releases before C30 defined the limit to be 128 MB. The ALLOCATESEGMENT, SEGMENT_ALLOCATE_, and RESIZESEGMENT system procedures no longer allocate selectable segments larger than MB. These size limits do not apply to "flat" segments allocated at other addresses, a feature supported on TNS/E and TNS/X systems, but not on TNS CISC. The starting addresses dynamically assigned to flat segments may be different on TNS/E and TNS/X, and the dynamic limits on flat segment sizes (due to other nearby segments) may be different on TNS/E and TNS/X. Detection Guideline If your programs allocate selectable segments larger than MB, or a combination of flat segments larger than the program's own 31-bit address space allows, ALLOCATESEGMENT and SEGMENT_ALLOCATE_ return error -2. Required Change Change your programs to use the maximum segment size if they allocate selectable segments larger than MB. Flat segments (at addresses other than 0x x07FFFFFF) have performance and size advantages over selectable segments (which must all timeshare the memory space at 0x x07FFFFFF). For best performance, it is recommended (but not required) to convert selectable segments into flat segments with non-overlapping addresses, and eliminate the associated expensive frequent calls to USESEGMENT or SEGMENT_USE_. This is also recommended (but not required) for native-mode programs. Variances in TNS and Accelerated Code This section describes the variances between TNS and TNS/X systems that apply to TNS object code and accelerated object code. The majority of these variances affect programs with user-written trap handlers or TAL programs with CODE statements. Additionally, these variances point out program bugs that can be detected on one system type and not on another. Check your programs for variances in: Trap handlers that use the register stack Trap handlers that use the P register Reserved instructions 16 Preparing Your Program for TNS/X Systems

17 Passing the address of P-relative objects Nonprivileged references to system global data Stack wrapping Odd-byte references Shift instructions with dynamic shift counts Trap Handlers That Use the Register Stack During program execution, the trap mechanism handles all error and exception conditions not related to input or output. User-written trap handlers differ on TNS and TNS/X systems because the register stack contents are imprecise at the moment of a trap. (The register stack consists of registers R0 through R7.) On TNS systems, trap handlers can be declared as functions (return a value to a caller) and they can modify the register stack. On TNS/X systems, trap handlers cannot be declared as functions and they can reliably examine and change only certain registers. User-written trap handlers must not alter the register stack. User-written trap handlers on TNS/X systems can: Print error messages and abend Clear overflow and resume Resume after a loop timer Put values into global variables Jump to a restart point by changing the trap variables P, L, ENV, space ID, and S Save the register stack with the usual code statement of: CODE (PUSH %777);! Save register stack contents However, the contents of the register stack are imprecise at the moment of a trap for programs executing on TNS/X systems. The contents of the register stack might not be the same as on TNS systems. Refer to the Guardian Programmer s Guide for information on writing overflow traps. Detection Guideline Find trap handlers by looking for calls to the ARMTRAP system procedure with parameters (address of label, address of data area). The ARMTRAP procedure specifies an entry point into the application program where execution is to begin if a trap occurs. You do not need to change ARMTRAP procedures with parameters of (-1,-1). These parameters cause programs to abend on traps. Trap handlers are usually small enough in both size and number to check visually. Required Change Change your programs to comply with the preceding restrictions. Trap Handlers That Use the Program Counter The reported program counter register, P, is imprecise for all code. Do not rely on the value of P to determine program flow, to inspect the TNS instruction word which triggered the trap, or to calculate the target of a jump. Variances in TNS and Accelerated Code 17

18 You can change the P trap variable to a valid restart point such as a cleanup point in the outer block, but do not perform arithmetic on P. For example, the results of the following operations are undefined: INT trap_p = 'L' - 2; trap_p := trap_p '+' 1; trap_p := trap_p '-' 1;! Location of the P register! Undefined! Undefined Refer to Trap Handlers That Use the Register Stack (page 17) for guidelines on writing trap handlers. Detection Guideline Find trap handlers by looking for calls to the system procedure ARMTRAP with parameters (address of label, address of data area). The ARMTRAP procedure specifies an entry point into the application program where execution is to begin if a trap occurs. You do not need to change ARMTRAP procedures with parameters of (-1,-1). These parameters cause programs to abend on traps. Trap handlers are usually small enough in both size and number to check visually. Required Change Change your programs to comply with the preceding restrictions. Reserved Instructions Two TNS instructions previously reserved for the operating system have changed from nonprivileged to privileged instructions on TNS/X systems: TOTQ - Test the Out Queue RCPU - Read Cpu Number These instructions continue to be nonprivileged instructions on existing TNS systems; HP reserves the right to change them to privileged instructions. Detection Guideline Programs that use these instructions in the nonprivileged environment fail with an Instruction Failure exception. Required Change Remove these instructions from nonprivileged programs. Passing the Addresses of P-Relative Objects Do not pass the address of a P-relative object to other routines in programs larger than one TNS code segment. Programs access the wrong object or an address fault occurs if you pass a: 16-bit address on TNS systems 16-bit address on TNS/X systems 32-bit extended address on TNS systems However, if you pass a 32-bit extended address on TNS/X systems, programs access the specified object and continue execution. This is a program error that TNS/X systems do not detect. Do not write programs that rely on this feature. There is one supported exception to this restriction: you can pass user code addresses into user library, system code, or system library routines. Detection Guidelines Look for statements that pass a 32-bit extended address of a P-relative object to other routines. Run your program on a TNS system. If the program runs correctly, your code is correct. 18 Preparing Your Program for TNS/X Systems

19 Required Change Recode statements that pass a 32-bit extended address of a P-relative object to other routines. Nonprivileged References to System Global Data Only privileged programs can access system global data. When a nonprivileged program references system global data, results differ depending on the system: On TNS systems, the program accesses the user global data segment, G, instead. On TNS/X systems, the program fails with an Instruction Failure exception. Detection Guidelines Use a text editor to search for SG in programs to locate potential variances. TNS/X systems terminate nonprivileged references to SG with an Instruction Failure exception. Required Change Example Remove references to SG variables from nonprivileged programs. The following TAL procedure tries to use the system value at address SG[0], but on a TNS system, the procedure uses whatever is at address G[0] in the user data segment. For more information on how to access the system data segment, refer to the section on privileged procedures in the TAL Reference Manual. INT cpuno = 'SG' + 0; INT.EXT xcpuno;! SG equivalencing! Extended pointer PROCEDURE foo;! Nonprivileged procedure BEGIN IF cpuno = 1 THEN! TNS/E system traps BEGIN! TNS system accesses G[0]! Lots of code := $XADR(cpuno); IF xcpuno = 1 THEN! TNS/E system traps...! TNS system accesses G[0] END; Segment Wrapping If a nonprivileged program tries to allocate and operate on variables partially lying across the end of the user data segment, results might differ depending on the system: On TNS systems, the variable reference wraps back to the base of the user data segment. On TNS/X systems, the variable reference is unpredictable; it might wrap or trap. Nonprivileged programs cannot access SG. Required Change Example Remove from your programs any constructs that result in segment wrapping. Change addressing operations so that they stay fully within the segment. The following examples show addressing operations that might not wrap back on the segment on TNS/X systems as they do on TNS systems. STRUCT s(*); BEGIN Variances in TNS and Accelerated Code 19

20 INT i; INT(32) d; INT j; END; PROC exam; BEGIN INT.p (s); STRUCT := -1;! -1 = (unsigned), structure starts at! the last word of the user data segment and! goes past the end s2 ':=' p FOR $LEN(s2) BYTES; p.d := %h %d; p.j := 6; END;! On TNS/X systems,! these operations! might wrap or trap In Data Segments (page 20), the structure defined by P starts near the end of the user data segment and goes past the end. On TNS systems, this addressing operation wraps back to G[0], as shown by the dotted line in the following figure. On TNS/X systems, this addressing operation might wrap or trap. Figure 5 Data Segments Odd-Byte References When a language compiler applies a TNS word instruction to an operand with an odd-byte address, run-time results are unpredictable. The instruction might do any, or any combination of: Round down the misaligned address (as the TNS CISC processors always did) Use the misaligned address without rounding it down Cause the instruction to fail The TNS instruction s misalignment behavior depends on: Operand size (16-bit, 32-bit, or 64-bit) Execution mode In TNS mode or accelerated mode, the action also depends on: TNS opcodes such as QCMP Although 64-bit integers with odd-byte addresses usually are not rounded down, they can beqcmp is one such example. Contextual optimizations How the instruction's result is used by later instructions The SCF attribute TNSMISALIGN (see Misalignment Handling (page 24)) 20 Preparing Your Program for TNS/X Systems

21 The varying behaviors and symptoms that misalignment errors cause can be confusing, for the following reasons: A source program can produce erroneous TNS object code that seems to execute correctly until you change the source program in an apparently innocent way. The program might behave differently in TNS mode than it does in accelerated mode. (Neither mode is better at avoiding alignment problems.) The debugger might display a different value for a variable than the program sees, because the debugger never rounds down addresses. The program might round down addresses for storage operations but not for subsequent retrieval operations of the same misaligned operand (or the reverse). TNS/X systems do not support the same odd-byte references to doublewords (4-byte units) or quadruplewords (8-byte units) as TNS systems do. Odd-byte references are made when the least significant bit (bit 31) of an extended pointer is set. TNS systems ignore bit 31 of an extended pointer and fetch or store data starting from the byte prior to the addressed one to ensure that the address is on a word boundary. This behavior is probably not what you intended. On TNS/X systems, odd-byte references to doublewords or quadruplewords are unpredictable; programs might trap or they might continue executing. Extended pointers to variables accessed as doublewords or quadruplewords must not have their least significant bit set. If your program was written following good TAL programming practices, odd-byte references are not a concern. In TAL, data types stored as doublewords or quadruplewords include INT(32), FIXED(n), REAL, REAL(64), and INT(64). In C, data types stored as doublewords or quadruplewords include long, unsigned long, long long, float, and double. You can use the Misalignment Tracing Facility to detect if your programs are using misaligned pointers.this tool detects where in the program the misaligned pointers are located so you can change the program to avoid misalignment. See Misalignment Tracing Facility (page 23) for more information. Odd-byte references to words (2-byte units) result in compatibility traps. Detection Guidelines Look for odd-byte references to doublewords or quadruplewords. Look for uninitialized pointers. Many odd-byte references to doublewords and quadruplewords result from uninitialized pointers (previously undetected programming errors). Required Change Remove odd-byte references to doublewords and quadruplewords from your programs. Recommended Changes Example Use pointer conversions as recommended for the source code language so that TNS word instructions are never applied to odd-byte addresses. Set the system s SCF attribute TNSMISALIGN to either FAIL or NOROUND (see TNS Misalignment Handling Methods (page 25)). FAIL can be unsafe on production systems, but is recommended on test systems. Remove odd-byte references to words from your programs. The results of the following program fragment are unpredictable on TNS/X systems. Variances in TNS and Accelerated Code 21

22 REAL(64).EXT RPTR; STRING.EXT SPTR = + 1d; IF SPTR = 'Z' THEN... IF RPTR = 0.0L0 THEN...! Same pointer as RPTR! OK! Results are unpredictable In the following example, an odd-byte address alignment error occurs on a TNS/X system because the program illegally references a nil pointer. The extended pointer P contains a byte address. When P is set to -1, the structure starts on an odd-byte boundary; therefore, the program might trap or it might continue executing. STRUCT s(*); BEGIN INT i; INT(32) d; INT j; END; PROC test; BEGIN INT.EXT -1d;! "nil" 4-byte pointer to structure p.d := %habcd1234%d;! Results are unpredictable END; Shift Instructions With Dynamic Shift Counts The implementation of TNS instructions for signed arithmetic and unsigned logical shifts with dynamic shift counts differs between TNS and TNS/X systems. This difference applies to both single-word (16-bit) and double-word (32-bit) shift instructions. For single-word shift operations with dynamic shift counts: TNS systems accept counts within the range of 0 to 255. Shift counts of 16 to 255 are treated as 16. TNS/X systems accept counts within the range of 0 to 31. Shift counts of 16 to 31 are treated as 16. Shift counts greater than 31 give undefined results. For double-word shift operations with dynamic shift counts: TNS systems accept counts within the range of 0 to 255. Shift counts of 32 to 255 are treated as 32. TNS/X systems accept counts within the range of 0 to 32,767. Shift counts greater than 32 are treated as 32. Dynamic shift counts that fall outside the acceptable ranges give undefined results. The ALS, LLS, ARS, and LRS instructions implement single-word shifts and the DALS, DLLS, DARS, and DLRS instructions implement double-word shifts. The TAL compiler generates these instructions for the bit-shift operators (<<, >>, <<, and >>) if the operand to the right of the operators is not a constant. These instructions can also be found in TAL CODE statements. Refer to the appropriate system description manual for more information about the TNS instruction set. Refer to the TAL Reference Manual for details on TAL bit-shift operators. Detection Guidelines Use a text editor to search for ALS 0, LLS 0, ARS 0, and LRS 0 in TAL CODE statements. Make sure that the operands for these instructions do not use shift counts greater than 31. Use a text editor to search for the TAL bit-shift operators: unsigned left and right shift (<< and >>) and signed left and right shift (<< and >>). Make sure that in cases where the left operand is a 16-bit unit and the shift count is dynamic, the count is never greater than Preparing Your Program for TNS/X Systems

23 Required Change Example Recode statements that use dynamic shift counts greater than 31. In this example, the value of p being arithmetically shifted to the right 35 positions. The value of p differs on TNS and TNS/X systems. INT p, nbits, q; p := -128; nbits := 35; q := p >> nbits;! INT variables! Shift value of 35-bits! On TNS systems,! same as p >> 16, q = -1! On TNS/X systems,! same as p >> (35-32), q = -16 Data Alignment in TNS and Accelerated Code This section describes the data alignment requirements for TNS code and the OCAX. It also describes how to use the Misalignment Tracing Facility diagnostic tool. On TNS systems, a word is 16 bits. The TNS instruction set includes data access instructions that use 32-bit byte addresses that must be even-byte aligned (that is, aligned 0 modulo 2) for correct operation. This requirement remains even after the OCAX translates TNS code. In TNS mode and accelerated mode, addresses that are odd-byte aligned (that is, aligned 1 modulo 2) are called misaligned. TNS processors consistently round down misaligned addresses (that is, they ignore the low-order bit). TNS/X processors handle the misaligned addresses of TNS programs inconsistently, rounding down some but not others and behaving differently in TNS mode and accelerated mode. These problems do not occur in programs that follow all of the programming rules for TNS languages, but compilers cannot catch misaligned addresses that are computed at run time. The behavior of TNS programs with misaligned addresses on TNS/X processors is almost impossible to predict. If you are not sure that your program has only aligned addresses, you can use the tracing facility to detect whether programs are using misaligned pointers, and if so, where. You should then change the programs to avoid misalignment. In addition to the OCAX, the data misalignment issue might affect the following HP compilers. If you use these compilers, see the appropriate data alignment addenda: Compiler TNS C TNS C++ TNS c89 TNS COBOL85 TNS/R ptal TNS TAL T Number T9255 T9541 T8629 T9257 T9248 T9250 Addendum C/C++ Programmer s Guide Data Alignment Addendum COBOL85 Manual Data Alignment Addendum ptal Reference Manual Data Alignment Addendum TAL Programmer s Guide Data Alignment Addendum Misalignment Tracing Facility The misalignment tracing facility is enabled or disabled on a system-wide basis (that is, for all processors in the node). By default, it is enabled (set to ON). It can be disabled (set to OFF) only Data Alignment in TNS and Accelerated Code 23

24 by the persons who configure the system, by means of the Subsystem Control Facility (SCF) attribute MISALIGNLOG. Instructions are in the SCF Reference Manual for the Kernel Subsystem. NOTE: HP recommends that the MISALIGNLOG attribute be left ON (its default setting) so that any process that is subject to rounding of misaligned addresses will generate log entries, facilitating diagnosis and repair of the code. Only if the volume of misalignment events becomes burdensome should this attribute be turned OFF. When a misaligned address causes an exception that RVUs prior to G06.17 would have rounded down, the tracing facility traces the exception. NOTE: The tracing facility does not count and trace every misaligned address, only those that cause round-down exceptions. Other accesses that use misaligned addresses without rounding them down do not cause exceptions and are not counted or traced. Also, only a periodic sample of the counted exceptions are traced by means of their own EMS event messages. While a process runs, the tracing facility: Counts the number of misaligned-address exceptions that the process causes (the exception count) Records the program address and code-file name of the instruction that causes the first misaligned-address exception Because a process can run for a long time, the tracing facility samples the process (that is, checks its exception data) periodically (approximately once an hour). If the process recorded an exception since the previous sample, the tracing facility records an entry in the EMS log. If the process ends, and any exception has occurred since the last sample, the operating system produces a final Event Management Service (EMS) event. The EMS event includes: The process s exception count Details about one misaligned-address exception, including the program address, data address, and relevant code-file names Sampling is short and infrequent enough to avoid flooding the EMS log, even for a continuous process with many misaligned-address exceptions. One sample logs a maximum of 100 events, and at most one event is logged for any process. If misaligned-address exceptions occur in different periods of a process, the operating system produces multiple EMS events for the same process, and these EMS events might have different program addresses. For more information about EMS events or the EMS log, see the EMS Reference Manual. Misalignment Handling Misalignment handling is determined by the following SCF attributes, which are set system-wide (that is, for all processors in the node) by the persons who configure the system: MISALIGNLOG TNSMISALIGN NATIVEATOMICMISALIGN (applies only to programs running in TNS/R native mode, and therefore, does not apply to the OCAX) MISALIGNLOG enables or disables the tracing facility. TNSMISALIGN applies to all programs running in TNS mode or accelerated mode, but not to programs running in native mode. 24 Preparing Your Program for TNS/X Systems

25 The TNS Misalignment Handling Methods (page 25) table lists and describes the possible settings for TNSMISALIGN. Each setting represents a misalignment handling method. For more information about TNSMISALIGN, see the SCF Reference Manual for the Kernel Subsystem. Table 1 TNS Misalignment Handling Methods Method ROUND (default) 1 FAIL Description After rounding down a misaligned address, the system proceeds to access the address. Instead of rounding down a misaligned address and proceeding to access the target, the operating system considers the instruction to have failed. For a Guardian process, this failure generates an Instruction Failure trap (trap #1). By default, this trap causes the process to go into the debugger, but the program can specify other behavior (for example, process termination or calling a specified trap-handling procedure). For information about trap handling, see the Guardian Programmer s Guide. For an OSS process, this failure generates a SIGILL signal (signal #4). By default, this signal causes process termination, but the program can specify other behavior (for example, entering the debugger or calling a specified signal-handler procedure). The signal cannot be ignored. For information about signal handling, see the explanation of the sigaction() function in the Open System Services System Calls Reference Manual. NOROUND The system uses the operand s given odd address (not rounded down) to complete the operation. If the operation is an atomic operation, atomicity is no longer guaranteed. 1 Use this method on production systems to avoid changing the semantics of old TNS programs. FAIL could cause possibly fatal Instruction Failure traps in faulty TNS programs. NOROUND might change the semantics of some faulty programs. The method that you choose does not apply to every misaligned address, only to those that would have been rounded down in RVUs prior to G NOTE: ROUND and NOROUND misalignment handling are both intended as temporary solutions, not as a substitute for changing your program to ensure that it has only aligned addresses. Programs that depend on NOROUND misalignment handling cannot be safely migrated to all present and future HP NonStop operating system platforms or to systems configured with ROUND or FAIL misalignment handling. Programs that depend on ROUND misalignment handling cannot be safely migrated as is to future HP NonStop operating system platforms or to systems configured with NOROUND or FAIL misalignment handling. Data Alignment in TNS and Accelerated Code 25

26 3 Preparing Programs for Acceleration Most TNS programs written since the C30 RVU of the operating system can be accelerated without modification. Variances between TNS and TNS/X systems that affect accelerated code only, however, might require modification in some programs, particularly low-level TAL programs. This chapter shows you how to prepare your programs for acceleration by OCAX: General Considerations (page 26) discusses software development issues that significantly affect the performance of accelerated code. Variances in Accelerated Code (page 27) discusses the changes you must make to programs because of variances between TNS and TNS/X systems that apply only to accelerated object code. General Considerations The following software development issues significantly affect the performance of accelerated programs. Note that none of these issues is a variance. Run-Time Libraries User Libraries The HP C/C++, HP COBOL85, HP FORTRAN, HP Pascal, TAL run-time libraries, and the Common Run-Time Environment (CRE) library, are configured as part of the system library on D-series, G-series, H-series, J-series, and L-series systems. These run-time library routines have already been accelerated for TNS/X systems. To save time in accelerating your programs and to produce the smallest possible accelerated object files, do not bind the run-time library routines into your programs. In particular, HP recommends that you do not bind COBOL85 run-time library routines into your COBOL85 application programs. At process creation, the operating system resolves external references to run-time library routines. You must continue to bind into programs that contain C/C++ routines the appropriate C/C++ model-dependent library file, such as CLARGE or CWIDE. Refer to the C/C++ Programmer s Guide for details. When you accelerate your user library, supply the UL option. Unlike Accelerator or AXCEL for TNS/R, OCAX does not require the UserLib option when translating programs that use a user library. C Function Prototypes The C/C++ compiler uses function prototypes to determine the return value size for calls to routines declared in separate modules or to routines declared later in the same module. If you do not specify a function protoype, the C/C++ compiler assumes the function returns an INT value. On the TNS architecture, the object code runs correctly if either the function returns an INT value or no value. OCAX generates code that assumes that the function returns an INT value. In most cases, OCAX can process object files compiled without C/C++ function prototypes, but the resulting accelerated object code is often inefficient and makes numerous transitions into executing TNS code. If possible, use C/C++ function prototypes for all of your C/C++ routines. Binder and Inspect Symbols Regions OCAX uses information from the Binder region and the Inspect symbols region of an object file to help perform control-flow analysis and optimizations. It can process most files without this information, but the resulting accelerated object code is often inefficient and makes numerous 26 Preparing Programs for Acceleration

27 transitions into executing TNS code. If possible, accelerate object files that contain the Binder and Inspect symbols regions. After accelerating a program, you can strip the symbols region from it without impacting performance. Variances in Accelerated Code This section describes the variances between TNS and TNS/X systems that apply to accelerated object code. Check your programs for variances in: Trap handlers that use the ENV register Passing parameters in registers The arithmetic left-shift sign bit Non-standard procedure call or return RP values The relationship between the global and local data blocks Procedure name conflicts Trap Handlers Using the ENV Registers The value of ENV.RP is undefined for accelerated programs. For compatibility with TNS processors, your trap handlers must set ENV.RP to 7 if they resume execution from a trap to a global restart point. The condition codes N, Z, and K are undefined for traps that occur when executing accelerated object code. Do not write trap handlers that: Base their decisions on these register values Resume to points that expect these register values to be valid Refer to the Trap Handlers That Use the Register Stack (page 17) for guidelines on writing trap handlers. Detection Guideline Examine your programs to determine if their trap handlers comply with the preceding restrictions. Find trap handlers by looking for calls to the system procedure ARMTRAP with parameters (address of label, address of data area). ARMTRAP specifies an entry point into the application program where execution is to begin if a trap occurs. You do not need to change ARMTRAP (-1,-1) procedures that cause programs to abend on traps. Trap handlers are usually small enough in both size and number to check visually. Required Change Change your programs to comply with the preceding restrictions. Passing Parameters in Registers When processing a TAL program, OCAX assumes that only those registers that contain an explicit value to pass or return hold meaningful values for procedure calls and returns. Procedures can pass values implicitly using TNS registers with CODE and STACK statements or the misuse of USE and DROP statements. A procedure inherits a register if it is passed a register by a calling procedure. A procedure returns a register if it returns a register to a calling procedure. To get a correctly accelerated program in these cases, you must use the INHERITSRn or RETURNSRn options to specify which registers are used to pass parameters to or from a specified procedure. For a discussion of TNS registers, refer to the appropriate system description manual. Variances in Accelerated Code 27

28 Detection Guidelines OCAX emits Warning 15 if it suspects that a procedure uses a register that is implicitly set by another procedure. Warning 15: Procedure procname in file filename inherits a register register-number Warning 15 can be a false warning if: The calling procedure employs a use register and does not drop it before the call. TAL USE and DROP statements are often used to optimize repetitive references to localized expressions or iteration variables. The procedure is not written in TAL. (See Note below for C programs). The procedure calls the Debug process. NOTE: The library function CLIB^EXTFNAME^TO^INTFNAME contains an uninitialized register variable in C30 versions of the HP C library released before 01DEC90. When this is the case, OCAX generates incorrect code; a program might cause a run-time trap or overwrite user variables. To get a correctly accelerated program, you must do either a full or replacement bind of the library and then accelerate the program again. To do a replacement bind, enter the following commands in Binder: 1. ADD * FROM object-file 2. ADD CODE CLIB^EXTFNAME^TO^INTFNAME FROM C-library, DELETE 3. BUILD object-file Required Changes If a called procedure inherits registers from a calling procedure, you must use the INHERITSR option to specify the registers that are passed by the calling procedure. INHERITSRn procedure-name where n = 0, 1, 2,, 7, (the register number) and procedure-name is the name of the called procedure. OCAX emits a warning for called procedures that might inherit registers. If a called procedure returns registers to a calling procedure, you must use the RETURNSRn option to specify the registers that are returned by the called procedure. RETURNSRn procedure-name where n = 0, 1, 2,, 7, (the register number) and procedure-name is the name of the called procedure. Make sure you specify the correct procedure. OCAX emits Warning 15 for calling procedures that might inherit registers that are returned from a procedure they call. You must specify the called procedure in the ReturnsR option. NOTE: HP strongly recommends that you remove this coding practice from your programs because it will not be supported in future software releases. Examples Passing Parameters in Registers (page 29) shows the passing of parameters in registers coded with the USE statement. Procedures can also pass parameters in registers by using TAL CODE statements. For example, the following fragment ending a procedure leaves a value on the register stack, although RP implies that no value is returned. PROC Q;! Lots of code CODE (LOAD L+3);! Loads value on stack from data segment 28 Preparing Programs for Acceleration

29 CODE (STRP 7);! Set RP=7, imply no value returned CODE (EXIT); When the PCAL instruction in the following fragment calls procedure Q, it uses the value left on the register stack. CODE (PCAL Q); CODE (STRP 0);! Set RP=0, use value on stack CODE (STOR L+4);! Stores value on stack to data segment OCAX discards the LOAD L+3 instruction, unless you specify ReturnsR0 Q to tell the OCAX to preserve that value. Figure 6 Passing Parameters in Registers Arithmetic Left-Shift Sign Bit In TNS object code (on both TNS and TNS/X processors), arithmetic left-shift operations preserve the existing sign bit and shift the remaining bits. The operation discards data shifted out from bit one. An arithmetic left-shift operation loses significant bits of the arithmetic value if it tries to change the sign bit (bit zero). This loss of significant bits is a kind of overflow, although the system never traps. In accelerated object code, an arithmetic left-shift operation does not preserve the sign bit. Instead, bit zero is included in the bits being shifted. The results might differ from those of TNS object code, but only if an overflow occurs. It is unlikely that programs knowingly use left-shift operations that overflow. Variances in Accelerated Code 29

30 Detection Guideline Look for arithmetic left-shift operations that overflow. Required Change Example Remove arithmetic left-shift operations that overflow from your programs. In TNS object code, the value of I is 0, while in accelerated object code, I= % INT I; I := % << 1;! Overflow in accelerated object code. Non-Standard Procedure Call or Return RP Values Procedures and subprocedures in TAL and C/C++ can return a different number of words in the register stack than the number declared in the routine s source code. OCAX determines the return value sizes for most of these procedures from information found in the Binder region and its control flow analysis. In some cases, OCAX predicts the return value sizes and emits a run-time check to make sure its predictions are correct. If OCAX makes an incorrect prediction, the program makes a transition into TNS code at that point. OCAX, however, does not determine or predict the return value size when the compiler-declared values in the Binder region conflict with OCAX s control flow analysis. In these rare cases, you must tell OCAX the size of the value returned by a procedure. Required Changes For TAL programs: Recode your program. HP recommends that you remove this coding practice from your programs because it will not be supported in future software releases. Change your programs to pass parameters using the proper TAL syntax, if possible. You can also use the RETURNVALSIZE option. For C/C++ programs: Recompile your C/C++ program if it contains functions that return the type void * and it was compiled with a version of the HP C/C++ compiler released prior to 01DEC90. You can also use the RETURNVALSIZE option. Recompile your C/C++ program if it contains functions that return a struct by value and it was compiled with a version of the HP C/C++ compiler released prior to 15JUN91. You can also use the RETURNVALSIZE option. 30 Preparing Programs for Acceleration

31 Examples For TAL or C programs: Use the OCAX RETURNVALSIZE option to specify the correct return values. For procedures with one return value size, specify: RETURNVALSIZE procedure-name value where procedure-name is the name of the procedure, and value is the number of 16-bit words returned by the procedure. Use this option for functions whose return values cannot be declared in TAL, such as 48-bit integers. You can also use this option for C functions that return the type void * or return a struct by value. Specify 1 word for NOXMEM (small-memory model) and 2 words for XMEM (large-memory model). For procedures with more than one possible return value size (depending on the exit taken from the procedure), specify: RETURNVALSIZE procedure-name UNKNOWN where procedure-name is the name of the procedure, and UNKNOWN tells OCAX to check the return value size for each procedure call. Use this option for functions where the number of words returned is dependent upon run-time logic. The declared size of a function (procedure or subprocedure) return result value in the Binder region must match the actual return size or OCAX generates incorrect code. The following TAL procedure returns three words implicitly and two words explicitly. INT(32) PROC foo;! Actually returns INT48 BEGIN INT tag; INT(32) value; STACK 1;! Put value on stack when not defined?rp=7 RETURN 2d; END;! Lie to TAL, suppress warning! Defined return value, does not match! value returned on the stack This shows how the TAL compiler view of the register stack differs from the actual run-time register stack. The TAL compiler believes that the register stack is empty after the RP directive, while at run time the hardware knows that a value is on the stack. The OCAX option RETURNVALSIZE must be used for this procedure to return the three values correctly: RETURNVALSIZE FOO 3 Function f returns the type void * in this C example. You must either recompile this program with a version of the C/C++ compiler released on or after 01DEC90 or specify a RETURNVALSIZE option. void *f(void) { Variances in Accelerated Code 31

32 return((void *) 0); } main() { char *cp; cp = f(); } Instead of recompiling, you can use the following RETURNVALSIZE option to produce a correctly accelerated program: RETURNVALSIZE 'f' 2 This example shows a function that returns a struct by value. You must either recompile this program with a version of the C /C++ compiler released on or after 15JUN91 or specify a RETURNVALSIZE option. #pragma runnable #include <stdioh> nolist #include <stdlibh> nolist struct TAG { int I; long L; }; struct TAG Foo (void); /* function returns type TAG */ struct TAG Foo (void) { struct TAG *ATagStruct; } ATagStruct = (struct TAG *) malloc ( sizeof (struct TAG)); ATagStruct->I = 1; ATagStruct->L = 2; return *ATagStruct; /* by value */ main () { struct TAG TagStruct; } TagStruct = Foo(); printf ( "TagStruct is %d %ld, should be 1 2\n", TagStruct.I, TagStruct.L); Instead of recompiling, you can use the following RETURNVALSIZE option to produce a correctly accelerated program: RETURNVALSIZE 'Foo' 2 Relationship Between Global and Local Data Blocks Do not assume that global and local data blocks have the same relation to one another on TNS/X systems as they have on TNS systems. For example, on TNS systems it is possible to write TAL code that accesses local variables by indexing global variables. On TNS/X systems, the indexed global variables might not be equivalent to local variables because of register optimization. OCAX does not detect when programs dangerously manipulate values between the global and local data blocks. The accelerated code might execute, but the results would be incorrect. 32 Preparing Programs for Acceleration

33 Required Change Example You must remove this coding practice from all programs. In the following program, the global variable f, an integer, is accessed as an array in the local block of the program. OCAX does not see the address of the array access, f[4], as equivalent to the variable c in the local data block. INT f;! Global variable PROC Test MAIN; BEGIN INT a,b,c,d;! Local variables c := 1; f[4] := c+100;! Undefined on TNS/X systems b := c+3; END; If you execute this program on a TNS system or as TNS code on a TNS/X system, b = 104 at the end of the procedure. If you accelerate this program and then execute it on a TNS/X system, b = 4. Procedure Name Conflicts A program can call several procedures of the same name, as long as each of the procedures resides in a different code space. For example, a program can call a system library procedure named File_Close_ and a user library procedure named File_Close_. Each of these procedures can have a different return value size. OCAX must determine the return value size for all procedures called by a program. When OCAX processes such a program, it resolves the name conflict in favor of the system library procedure. This can result in an incorrectly accelerated program. HP strongly recommends that you do not give your procedures names that conflict with system procedure names. Variances in Accelerated Code 33

34 4 Using OCAX The OCAX program processes TNS object code programs and produces accelerated object code programs. You can run OCAX only from the Guardian environment; OCAX does not support the Open System Services (OSS) environment. This chapter describes: Strategy for Using OCAX (page 34) describes a strategy for using OCAX. Invoking OCAX (page 34) describes how to run OCAX from the Guardian environment. Specifying the Code Space (page 35) describes the OCAX options that affect the code space in which a program runs. Accelerating Programs With Embedded SQL (page 36) explains how to accelerate user libraries and programs that contain embedded NonStop SQL/MP or SQL/MX statements. Using Obey Files (page 36) explains how to use obey files with OCAX. Online Help (page 36) describes the OCAX online help facility. OCAX Listings (page 37) describes OCAX listings. Strategy for Using OCAX This basic strategy shows you how to accelerate a program that runs in user code space, does not contain embedded SQL statements, and does not contain TAL CODE statements. This strategy uses the default OCAX option settings. The option settings provide the OCAX with additional information about the program to be accelerated. For the vast majority of programs, the default settings for these options result in a correctly accelerated program. Either the options are concerned only with performance, or they can be set to the wrong value safely; that is, their misuse is detected and reported by the OCAX, and can be corrected by setting the option and re-running OCAX. 1. Make sure that your program does not contain any of the variances described in Preparing Programs for Acceleration or Preparing Your Program for TNS/X Systems of this manual. 2. Compile and bind your TNS object program. For optimum results, retain both the Binder and Inspect symbols regions. 3. Debug the TNS version of your complete program. 4. Run OCAX. If OCAX issues an error message, it does not produce an output file. Correct the error and re-run OCAX. 5. Examine the OCAX listing. If there are any warning messages, investigate each warning, and fix it if necessary. OCAX issues warning messages to call your attention to possible problems. Refer to Error and Warning Messages for cause, effect, and recovery information about warning messages. 6. Perform final testing on the accelerated program. This is a quick and simple strategy for using OCAX. The following table guides you to the appropriate sections to learn how to perform more advanced OCAX tasks. To: Make it more convenient to accelerate a program Accelerate a program with embedded SQL statements Accelerate code that runs in user library, system code, or system library space Refer to: Using Obey Files (page 36) Accelerating Programs With Embedded SQL (page 36) Specifying the Code Space (page 35) Invoking OCAX OCAX runs as a Guardian process in the Guardian environment. You can invoke OCAX explicitly on L-series and later releases using TNS/X NonStop server. When you invoke OCAX from the 34 Using OCAX

35 command line it takes the name of a type-100 TNS object file as an argument. You can specify one or more OCAX options on the command line, but these are optional. See OCAX Options (page 39) for a listing and description of all OCAX options. Once OCAX translates a TNS object file, you can execute the accelerated type -100 file on an TNS/X system where it immediately executes at full speed. The ocax command invokes OCAX from the Guardian environment. ocax [/ run-options/] input-file, [, ocax-option-list] run-options is zero or more standard run-time options, as described in the TACL Reference Manual. Each option keyword, along with any accompanying arguments, must be separated by a comma from the next. input-file is the name of the file containing the TNS object program that the OCAX is to process. ocax-option-list is zero or more OCAX options. See OCAX Syntax and Option Summary for a detailed description of each option. Each option keyword, along with any accompanying arguments, must be separated by a comma from the next keyword. Partially qualified pathnames are resolved using the current working directory. If you run the OCAX using the gtacl command, pathnames must be fully qualified. See Section 5, OCAX Syntax and Option Summary for instructions on how to invoke OCAX and a detailed description of each OCAX option. OCAX Command Usage Examples The following examples show how the OCAX command is used: OCAX accelerates the object file myobj and generates an accelerated object file named myoca: ocax myobj, OUTPUT_FILE myoca OCAX accelerates the object file test1, generates an accelerated object file named test2, and writes its listing to the file mylist: ocax /OUT mylist/ test1, OUTPUT_FILE test2 Specifying the Code Space A code space is a part of virtual memory reserved for user library code and system library code. For each code space, a compiler generates different code and places different restrictions on the run-time library and language features that can be used. Refer to the appropriate language manuals for details. You can specify to OCAX whether an object file is to be run as user library (UL) or system library (SL). Use the option UL for user library and SL for system library. Note that user library code not identified as such to OCAX cannot be used as a user library or a shared run-time library at execution time. See Translating a System Library (page 40) and Translating a User Library (page 41) for more information. Accelerating User Libraries and Shared Run-Time Libraries To accelerate a user library or a shared run-time library, accelerate the TNS object file as user library code by specifying the UL option. In the following example, the TNS user library MyLib is accelerated and written to the MyLibAx file: ocax MyLib, OUTPUT_FILE MyLibAx, UL OCAX Command Usage Examples 35

36 Accelerating Programs With Embedded SQL To accelerate programs that contain embedded NonStop SQL/MP statements, you must perform the following steps in sequence: 1. Compile 2. Bind 3. Accelerate 4. SQLCOMP If you reaccelerate a program, you must follow by rerunning SQLCOMP. OCAX outputs an accelerated object file that does not have the same file label as the input TNS object file. The file label contains the PROGID attribute that determines the ownership of an executing process for NonStop SQL/MP. OCAX turns off the PROGID attribute of the accelerated object file. To set the PROGID value, use the SQL ALTER PROGRAM statement or the Safeguard security subsystem interface. Refer to the NonStop SQL/MP Reference Manual or the Safeguard Reference Manual for details. Using Obey Files Comments Example In the Guardian environment, you can provide OCAX options on the OCAX command line itself, in a text file whose name is given as a command-line option, or both. The text file is referred to as an obey file. An obey file can include any option that can be given on the command line, including other obey file invocations. Any number of obey files may be invoked within an OCAX command. You specify an obey file as a run-option within the slashes that optionally follow the keyword ocax, as in this example: ocax /in fred/ input-file, output_file output-file or in the ocax-options -list part of the command, following the semicolon: ocax input-file, output_file output-file, obey fred OCAX resolves partially qualified pathnames using the current working directory. Obey files can contain any number of OCAX options. The list of options can be as long as you like, with any number of comma-separated options on each line. Options that take an indefinite number of arguments can be followed by a blank-separated list of such arguments. Each option, together with all its arguments, must appear in its entirety on a single line, and not be continued onto a following line. See Specifying an Obey File (page 41) for more information. You can use comments in obey files to annotate the commands you specify to OCAX. (You cannot use comments on the OCAX command line.) A comment can be on any line. This obey file also directs OCAX to read more options from the obey file MOREOPTS. Online Help The following example displays the contents of an obey file: -- obey file fred inheritscc MYPROC obey moreopts -- get more options from file moreopts To access the OCAX online help facility, enter ocax at a TACL prompt. This displays a brief summary of the OCAX command syntax. The following example illustrates the help text: 36 Using OCAX

37 Example 1 OCAX Online Help Example >OCAX OCAX - T0448H01-01Jan05 - (Dec :27:33) Copyright Hewlett-Packard, OCAX Syntax Summary ocax [/run-options/] input-file [, option-list ] input-file is the name of a fully bound, runnable, type-100 TNS code file. option-list is one or more command line options: OCAX Listings [ { SL } { UL } { OUTPUT_FILE output-file } { IGNORE_IRn proc-name } { INHERITSRn proc-name } { IGNORE_CC proc-name } { INHERITSCC proc-name } { OBEY obey-file-name } At each execution, OCAX produces a listing that reports on the acceleration it has just performed. The following example shows a sample OCAX listing: > ocax fred, output_file fredx OCAX - T0892L01 - (Jul :08:35) Copyright Hewlett-Packard, Option summary: Output_File fredx TNS instructions; bytes X86 instructions; x86 bytes 7.40 inline code expansion factor TNS file name: fred Binder region not present Symbols region not present Mips region not present IPF region not present Accelerated as User Code segment 0 through 5 0 Errors were detected 0 Warnings were issued Accelerated file name: fredx Accelerated for TNS/X on Jul :48:19 OCAX Listings 37

38 38 Using OCAX Acceleration completed on Jul :48:28 CPU Time 0:00: >

39 5 OCAX Syntax and Option Summary This chapter provides detailed information about using OCAX on the command line and how you can use additional options to specify more advanced translation functions. OCAX Syntax (page 39) describes how to run OCAX from the command line. OCAX Options (page 39) details and provides examples for using options that can be placed in the [, ocax-option-list] portion of the command line. Using additional OCAX options is not required. OCAX Syntax To run OCAX from the command line, use the following syntax model: ocax [/ run-options/] input-file [, ocax-option-list] run-options is one or more standard run-time options, as described in the TACL Reference Manual. The most useful option for the OCAX command is: OUT file-name, to specify to which file OCAX is to write its listing. If no file is entered, the listing is written to the specified hometerm. Each option keyword, along with any accompanying arguments, must be separated by a comma from the next. input-file is the name of the file containing the TNS object program that the OCAX is to translate. The file must be fully bound, runnable, and of file code type 100 or 180. The input file may have been previously accelerated; OCAX ignores the TNS/R and IPF regions of the TNS object file if one exists. If you do not enter a OUTPUT_FILE name, OCAX augments the input file with a new region that contains x86 instructions provided the existing file is secured so that the OCAX invoker has permission to replace the existing file. When OCAX augments an existing input file with x86 instructions, it updates the file s timestamp. If OCAX cannot augment an existing file, it tries to create a second file in the same subvolume with a name in the form ZZZZnnnn where n is a placeholder for a number. OCAX displays this file in the listing if it needs to create this second file. ocax-option-list is one or more ocax options, which are listed and described later in OCAX Options (page 40). Each option keyword, along with any accompanying arguments, must be separated by a comma from the next keyword. Note that you cannot use comments on the OCAX command line. If you need to add comments to any OCAX command line options, use an obey file. See Specifying an Obey File (page 41) for more information. OCAX Options OCAX Options (page 40) lists the OCAX options and provides a quick overview for each option. The rest of this section describes each option in detail. Note that: Option keywords are not case-sensitive. Guardian file names are not case-sensitive. Procedure names are case-sensitive. If you plan to supply a large number of options, it is convenient to use an obey file. See the obey command. OCAX Syntax 39

40 Table 2 OCAX Options Option SL UL OUTPUT_FILE output filename OBEY obey filename IGNORE_IRn proc-name INHERITSRn proc-name IGNORE_CC proc-name INHERITSCC proc-name RETURNSRn RETURNVALSIZE proc-name n Purpose Explicitly accelerates the entire non-native portion of the system library Explicitly accelerates a user library Specifies the output code file to a location that is different from the input code file location Specifies the name of an obey file that OCAX should read for further commands Directs OCAX to complete its translation without issuing a warning when it encounters a procedure that inherits a register Directs OCAX to complete its translation without issuing a warning when it encounters a register stack being used to implicitly pass a non-stack parameter to a procedure Directs OCAX to complete its translation without issuing a warning when it encounters a procedure that inherits condition codes Directs OCAX to complete its translation without issuing a warning when it determines a condition code is passed into and used by the routine Tells OCAX which TNS registers are used for implicitly passing parameters from the named procedure Directs OCAX to assume that the named procedure returns the named number of 16-bit words as its return value See Translating a System Library (page 40) Translating a User Library (page 41) Specifying an Output File Name (page 41) Specifying an Obey File (page 41) IGNORE_IRn (page 43) INHERITSRn (page 43) IGNORE_CC (page 43) INHERITSCC (page 44) Determining TNS Register Usage (page 42) Correcting a Function s Return Values Size (page 42) Translating a System Library In the TNS/X environment, the non-native portion of a system library is explicitly accelerated by the system building process. When you invoke OCAX and specify the SL option, this identifies the code undergoing translation as the system library. ocax [/ run-options/] input-file, SL OCAX assumes if you do not use the SL option: That a TNS object file that contains a main program is a user code file That a TNS object file that does not contain a main programs is a user library file 40 OCAX Syntax and Option Summary

41 SL Usage Considerations OCAX does not permit incremental module accelerations before binding them together. You must first use Binder to combine pieces of the system library before using OCAX to accelerate the library. Developers who build system library modules may perform trial accelerations using OCAX. System library components do not require translation before OSBuild. Translating a User Library The UL option allows you to explicitly identify a file undergoing translation as a user library. Specifying the UL options directs OCAX to suppress the warning that appears in the listing file when it finds an inferred user library. ocax [/ run-options/] input-file, UL UL Usage Considerations If you do not supply the UL option, OCAX interprets any ready-to-run object file containing no main program as a user library. You can accelerate a user library explicitly without specifying the UL option. Specifying an Output File Name Use the OUTPUT_FILE option to specify an output code file name whose location is different from the input code file location. When you use the OUTPUT_FILE option, OCAX does not modify or replace the input-file unless the input-file name is the same as the output-file name. ocax [/ run-options/] input-file, OUTPUT_FILE output-file output-file is the name of the file to which the OCAX will write its output: that is, the accelerated object file. input-file and output-file can be the same. If you specify an output file that already exists, OCAX attempts to delete it to make room for a file of the same name. If it cannot delete that older file, it creates a file with a name of the form ZZZZnnnn to use instead, and tells you in the listing that it did so. Specifying an Obey File You can specify additional command line options in a text file called an obey file and then specify the obey file on the OCAX command line using the OBEY option. ocax [/ run-options/] input-file, OBEY obey-file obey-file is the name of the text file that contains additional OCAX command line options. Obey Usage Considerations An obey file can contain any options that can appear on the command line, including a nested OBEY option and each obey file can contain an unlimited number of OCAX options. The list of options in an obey file can be as long as you need and contain any number of comma-separated options on each line. Each option and all of its arguments must appear on a single line; it may not be continued on a separate line. You can insert comments into an obey file to annotate OCAX commands. A comment can be on any line of an obey file, even if that line contains an option. A comment is defined as any string introduced by two dashed (--) and is terminated by the end of a line. OCAX does not recognize the TACL line continuation mark &. OCAX Options 41

42 Determining TNS Register Usage The RETURNSRn option tells OCAX which TNS registers are used for implicitly passing parameters from the named procedure. ocax [/ run-options/] input-file, RETURNSRn proc-name RETURNSRn where the value of n is one of each TNS data register that could be implicitly passing parameters from the named procedure. Values for RETURNSR are: RETURNSR0, RETURNSR1, RETURNSR2, RETURNSR3, RETURNSR4, RETURNSR5, RETURNSR6, or RETURNSR7. proc-name is a procedure name. Procedure names are case sensitive so specify a procedure name using the exact spelling and case as it appears in the Binder region of the object file. OCAX error message display the exact spelling and case for a procedure. Correcting a Function s Return Values Size The RETURNVALSIZE option corrects the misdirected value of RP so that program execution remains in accelerated mode. ocax [/ run-options/] input-file, RETURNVALSIZE proc-name num-bytes proc-name is a procedure name. Procedure names are case-sensitive so specify a procedure name using the exact spelling and case as it appears in the Binder region of the object file. OCAX error message display the exact spelling and case for a procedure. num-bytes is the named number of 16-bit words in the return value. Diagnosing and Managing Register or Condition Code Inheritance In TAL programs you can use the USE, STACK, and CODE statements to write procedures that implicitly pass parameters in the TNS register stack. HP does not recommend this practice. If your programs do pass parameters in TNS registers, you can use the INHERITSRn option to generate correct code, though it is best to modify the source code to eliminate this practice and then reaccelerate the program. Diagnosing Register or Condition Code Inheritance OCAX can falsely warn of register or code condition inheritance. This can be because either: The procedure calls DEBUG. The caller declares a USE variable that was declared, but has not yet been initialized at some procedure or supersedure call. For example the following code sample contains an uninitialized USE variable that is not DROPped before a procedure call: PROC fred; BEGIN USE i; CALL do_something; i := jane DROP i; END; Restructure the code sample to DROP or defer the USE variable before the call: PROC fred; BEGIN USE i; DROP i; 42 OCAX Syntax and Option Summary

43 CALL do_something; i := jane END; If a code (RDE) statement appears to sample an as yet uninitialized ENV.NZ condition code, OCAX can interpret this as a sampling of the caller s condition code. Managing Register or Condition Code Inheritance OCAX warns you if a procedure appears to use a CC or R0..R7 register value before the register is set by that procedure. If a Warning 15 or Warning 16 is displayed it could signify one of a few manageable conditions, including one where the procedure expects to inherit the register from a calling procedure. The following options help you manage conditions when OCAX issues Warning 15 or 16. Warning 15 displays when OCAX detects that a register from the TNS register stack may hold an implicitly passed register value. Warning 16 displays when OCAX detects that the condition codes may be inherited from the calling procedure. These warnings appear rarely and may in fact not reflect register inheritance. Use the following options to suppress these warnings and allow OCAX to complete translation. IGNORE_IRn If you determine that OCAX is issuing Warning 15 falsely, use IGNORE_IRn to suppress further issuance of Warning 15 and allow OCAX to complete procedure translation. ocax [/ run-options/] input-file, IGNORE_IRn proc-name IGNORE_IRn where the value of n is one of each TNS data register that could appear to be inherited. Values for IGNORE_IR are: IGNORE_IR0, IGNORE_IR1, IGNORE_IR2, IGNORE_IR3, IGNORE_IR4, IGNORE_IR5, IGNORE_IR6, or IGNORE_IR7. proc-name is a procedure name. Procedure names are case sensitive so specify a procedure name using the exact spelling and case as it appears in the Binder region of the object file. OCAX error message display the exact spelling and case for a procedure. IGNORE_CC If you determine that OCAX is issuing Warning 16 falsely, use IGNORE_CC to suppress further issuance of Warning 16 and allow OCAX to complete procedure translation. ocax [/ run-options/] input-file, IGNORE_CC proc-name proc-name is a procedure name. Procedure names are case sensitive so specify a procedure name using the exact spelling and case as it appears in the Binder region of the object file. OCAX error message display the exact spelling and case for a procedure. INHERITSRn Use the INHERITSRn option if you determine that OCAX is issuing Warning 15 because a TNS register stack is being used to implicitly pass a non-stack parameter to the procedure. Note that Warning 15 is usually spurious and INHERITSRn should only be used when Warning 15 is not spurious.this option directs OCAX to treat TNS stack register n as live on calls to the named procedure. It also suppresses further issuance of Warning 15 and allows OCAX to complete procedure translation. ocax [/ run-options/] input-file, INHERITSRn proc-name INHERITSRn where the value of n applies to each register that is inherited. Values for INHERITSR are: INHERITSR0, INHERITSR1, INHERITSR2, INHERITSR3, INHERITSR4, INHERITSR5, INHERITSR6, or INHERITSR7. OCAX Options 43

44 proc-name is a procedure name. Procedure names are case sensitive so specify a procedure name using the exact spelling and case as it appears in the Binder region of the object file. OCAX error message display the exact spelling and case for a procedure. INHERITSCC Use the INHERITSCC option if you determine that OCAX is issuing Warning 16 because a condition code is passed into and used by the routine. Note that Warning 16 is usually spurious and INHERITSCC should only be used when Warning 16 is not spurious.this option directs OCAX to treat the condition code (CC) as live on calls to the named procedure. It also suppresses further issuance of Warning 16 and allows OCAX to complete procedure translation. The option INHERITSCC_ON is a synonym for INHERITSCC. ocax [/ run-options/] input-file, INHERITSCC proc-name proc-name is a procedure name. Procedure names are case sensitive so specify a procedure name using the exact spelling and case as it appears in the Binder region of the object file. OCAX error message display the exact spelling and case for a procedure. IGNORE_IRn, IGNORE_CC, INHERITSRn, and INHERITSCC Usage Considerations If you specify a procedure name that does not exist, OCAX ignores the procedure and continues translating without generating a warning. Procedures rarely expect arguments that are passed into TNS registers. Confirm that your procedure uses this calling convention and verify the exact spelling of the procedure name and the TNS register number. Supply a valid INHERITSRn or INHERITSCC option to prevent additional false register inheritance warnings to display about the caller procedure and other procedures it calls. OCAX diagnoses the appearance of inherited registers with a warning assuming the condition is false unless an INHERITS_Rn option is supplied. The IGNORE_IRn option suppresses this warning. 44 OCAX Syntax and Option Summary

45 6 Using OCAX With Other NonStop Tools You can use OCAX with other NonStop products that operate on TNS object files. OCAX and Binder (page 45) OCAX and TNSVUX (page 46) OCAX, OCA and Accelerator (page 46) A TNS object file, after being augmented by both OCAX and OCA, can run fast on both TNS/E and TNS/X machines, as described later in this chapter. You can use Inspect to debug programs accelerated by OCAX. Source-level (symbolic) debugging of accelerated programs is very similar to TNS programs. However, machine-level debugging of accelerated programs is limited, and rarely necessary. For further information about using OCAX with Inspect, see Debugging OCAX Programs. OCAX and Binder CHANGE SHOW OCAX only processes fully bound ready-to-run TNS object files. When you use Binder with OCAX, the Binder strips the TNS/R, IPF, and OCAX regions from a TNS object file and resets the OCAX s attributes in the TNS header, based on what Binder commands you use. See the Binder Manual for further information about how to use the Binder. You can use the following Binder command with OCAX-generated TNS object files: CHANGE SHOW STRIP The CHANGE command allows you to modify the attribute values of an existing TNS object file: CHANGE OCAX ENABLE [ON OFF] IN filename ENABLE controls whether or not OCAX can process a file. [ON OFF] is the Binder default setting for OCAX ENABLE is ON. OCAX does not change the value of this attribute. When OCAX ENABLE is set to OFF, OCAX may not operate on the object file; file execution occurs in TNS mode. The SHOW command displays the current values for the attributes of an existing TNS object file. SHOW {OCAX ENABLE [FROM filename] } {INFO [FROM filename] } OCAX ENABLE displays whether or not OCAX can accelerate the TNS object file specified in the FROM portion of this command. INFO displays the attributes for the TNS object file specified in the FROM portion of this command. SHOW command output also displays OCAX information when the program has been accelerated using OCAX. OCAX and Binder 45

46 STRIP The STRIP command allows you to selectively remove the Binder, Inspect, TNS/R, IPF, or OCAX regions from the named TNS object file. If you enter STRIP filename at the command line without any additional options, Binder strips only the Binder and Symbols regions and retains the TNS/R, IPF, and OCAX regions (if any) in the file. If you specify the SYMBOLS, AXCEL, OCA, or OCAX options, only those named attributes are removed from the file. STRIP filename [, SYMBOLS, AXCEL, OCA, OCAX] filename is the name of the TNS object file from which you want to remove the Binder, Inspect, TNS/R, IPF, or OCAX region. SYMBOLS removes the Inspect region from the TNS object file. The Inspect region contains debugger symbol tables from the TNS object file. AXCEL removes the TNS/R region from the TNS object file. The TNS/R region contains Accelerator-generated TNS/R code. OCA removes the IPF region from the TNS object file. The IPF region contains OCAgenerated Itanium code. OCAX removes the OCAX region from the TNS object file, containing OCAX-generated x86 code. OCAX and TNSVUX TNSVUX is an interactive tool that browses a static, type-100 TNS object file, including the OCAX region generated by the Object Code Accelerator for TNS/X (OCAX). Using TNSVUX, you can display a variety of information about a file s contents such as: General or detailed information about one or more procedures Names of millicode routines Contents of the TNS or OCAX region headers Names of system or library routines called TNS and x86 instruction sequences TNS instruction addresses and the TNS/X addresses of the equivalent x86 code sequences See the TNSVUX Manual for further information. OCAX, OCA and Accelerator The TNS Object Code Accelerator for TNS/X (OCAX) translates TNS instructions to equivalent x86 instructions. It augments the type-100 TNS object file with a new region containing these x86 instructions: the OCAX region. These augmented TNS object files execute significantly faster on TNS/X machines than do unaugmented, interpreted TNS object files. TNS application programs that have been translated by OCAX execute with increased performance on TNS/X, much like programs that have been augmented by the Accelerator for TNS/R and programs that have been augmented by the OCA for TNS/E execute with increased performance on their respective machines. We refer to files translated by OCAX as having been accelerated, and acceleration for TNS/X is the act of translation via OCAX. 46 Using OCAX With Other NonStop Tools

47 Figure 7 The OCAX Translation Process The TNS/X native linker does not accept TNS object files as input. OCAX accelerates fully linked, readyto-run, type-100 TNS object files for complete applications and complete libraries. No tool (like XLLink for Accelerator-generated files) exists to link together OCAX-generated x86 code. You can use Binder to combine TNS code files, then use OCAX to accelerate the complete application. Accelerating for Multiple Platforms The Accelerator (Axcel) and OCA process TNS object files to produce accelerated object files that run significantly faster on TNS/R and TNS/E, respectively, than do plain TNS objects. The accelerated object file contains both the original TNS instructions and the logically equivalent optimized native instructions. You can run OCAX on a TNS object file that has already been augmented by Accelerator or OCA or both. OCAX adds a new region to the object file. You can accelerate your TNS object file with any combination of OCAX and OCA, in any order, and the resultant object file runs fast on the machines for which it was accelerated. Figure 8 Translating Using Accelerator, OCA and OCAX See the L-Series Application Migration Guide for TNS/X for further information about using OCAX. OCAX, OCA and Accelerator 47

48 Figure 9 Translating Using OCA and OCAX A TNS object file, after being augmented by both OCAX and OCA, can run fast on both TNS/E and TNS/X machines. The Accelerator for TNS/R does not tolerate object files that have been previously accelerated by OCAX for TNS/X. To create an object file that contains both a MIPS region and an OCAX region, you must accelerate for TNS/R first, then accelerate for TNS/X. OCA version 75 and later is able to preserve an OCAX region. OCAX and NonStop Debugging Tools You can use either Visual Inspect or Native Inspect to debug programs accelerated by OCAX. Source-level (symbolic) debugging of accelerated programs is very similar to TNS programs. However, machine-level debugging of accelerated programs is limited, and rarely necessary. See Debugging OCAX Programs for further information about using OCAX with Visual Inspect and Native Inspect. 48 Using OCAX With Other NonStop Tools