migrating vos applications to continuum (r407-00)

8/20/2019 Migrating VOS Applications to Continuum (r407-00)

1/122

R407-00

Stratus Computer, Inc.

Migrating VOS Applications to Continuum Systems


2/122

Notice

The information contained in this document is subject to change without notice.

UNLESS EXPRESSLY SET FORTH IN A WRITTEN AGREEMENT SIGNED BY AN AUTHORIZED REPRESENTATIVE OF STRATUS

COMPUTER, INC., STRATUS MAKES NO WARRANTY OR REPRESENTATION OF ANY KIND WITH RESPECT TO THE

INFORMATION CONTAINED HEREIN, INCLUDING WARRANTY OF MERCHANTABILITY AND FITNESS FOR A PURPOSE. Stratus

Computer, Inc., assumes no responsibility or obligation of any kind for any errors contained herein or in connection with the furnishing,

performance, or use of this document.

Software described in Stratus documents a) is the property of Stratus Computer, Inc., or the third party, b) is furnished only under license, and

c) may be copied or used only as expressly permitted under the terms of the license.

This document is protected by copyright. All rights are reserved. No part of this document may be copied, reproduced, or translated, either

mechanically or electronically, without the prior written consent of Stratus Computer, Inc.

Stratus, Continuous Processing, StrataNET, FTX, and the Stratus logo are registered trademarks of Stratus Computer, Inc.

Continuum, XA, XA/R, StrataLINK, RSN, SINAP, and the SQL/2000 logo are trademarks of Stratus Computer, Inc.

IBM is a registered trademark of International Business Machines Corporation.

MC68000 is a registered trademark of Motorola, Incorporated.

i860 is a trademark of Intel Corporation.

PA-RISC is a tradmark of Hewlett-Packard, Incorporated.ORACLE7 is a trademark of Oracle Corporation.

Manual Name: Migrating VOS Applications to Continuum Systems

Part Number: R407

Revision Number: 00

VOS Release Number: 13.0

Printing Date: March 1995

Stratus Computer, Inc.

55 Fairbanks Blvd.

Marlboro, Massachusetts 01752

© 1995 by Stratus Computer, Inc. All rights reserved.


3/122

Migrating VOS Applications to Continuum Systems (R407) iii

Preface

The Purpose of This Manual

The manual Migrating VOS Applications to Continuum Systems (R407) documents how to

migrate applications from XA2000-series modules or XA/R-series modules to

Continuum-series modules.

Audience

This manual is intended for application programmers and system administrators who aremigrating applications to Continuum systems.

Before using the manual Migrating VOS Applications to Continuum Systems (R407), you

should be familiar with the VOS Commands Reference Manual (R098) and the VOS

Subroutines manuals.

Revision Information

This is the first edition of this manual. For information on which release of the software this

manual documents, see the Notice page.

Manual Organization

This manual consists of 11 chapters and 2 appendixes.

Chapter 1 summarizes the Continuum features affecting migration.

Chapter 2 is a step-by-step guide to the migration process, from initial planning through

implementation, including some separate procedures for migrating applications from 68K

systems and i860 systems.

Chapter 3 discusses data alignment, including how to specify data alignment for an entire

source module and for individual data elements, and how to handle various data alignment

issues you are likely to encounter while migrating applications to Continuum systems.

Chapter 4 explains how to correct programs that may have worked on earlier Stratus hardware

platforms despite non-standard programming practices but may produce errors on

Continuum-series modules due to the larger number of registers.

Chapter 5 explains a number of coding practices that jeopardize the portability of programs

and describes how to correct the code.


4/122

Preface

iv Preface

Chapter 6 describes how to improve memory access by specifying the memory pool to which

a process is assigned.

Chapter 7 explains how to use the high-performance cache on a Continuum-series module

efficiently.

Chapter 8 explains how to upgrade to the machine-independent locking mechanism availablewith VOS Release 13 and later releases.

Chapter 9 explains how to set virtual memory limits for a process or command, and how to

set module default command limits.

Chapter 10 gives instructions on upgrading to the microjiffy Time-of-Day clock.

Chapter 11provides information on troubleshooting paging space problems, performance

problems, and problems related to process or command virtual memory limits.

Appendix A describes how to migrate Forms Management System (FMS) applications to

Continuum systems.

Appendix B discusses several commands and VOS System Analysis subsystem requests for

finding and diagnosing runtime alignment faults.

Notation Conventions

This manual uses the following notation conventions.

• Monospace represents text that would appear on your display screen (such as

commands, subroutines, code fragments, and names of files and directories).

For example:

In VOS COBOL, you can specify the longmap or shortmap attribute for arecord with the using longmap or using shortmap clause.

• Monospace italic represents terms that are to be replaced by literal values. In the

following example, the user must replace the monospace-italic term number with a

literal value.

If you use the update_disk_label command to increase paging space, give

the command with the -pagepart_size number argument.

• Monospace bold represents user input in examples and figures that contain both user

input and system output (which appears in monospace). For example:

as: where 8208

00008208 at customer_accounts+208, line 48

• Italics introduces or defines new terms. For example:

Accesses to local memory can be up to three times as fast as accesses to remote

memory, the physical memory on another logical CPU/memory board.


5/122

Preface

Migrating VOS Applications to Continuum Systems (R407) v

• Boldface emphasizes words in text. For example:

In VOS PL/I, for example, longmapped structures must only begin on a

boundary congruent to the size of the largest element (up to mod-8). In VOS

Standard C, the structure must begin and end on such a boundary.

Key Mappings for VOS FunctionsVOS provides several command-line and display-form functions. Each function is mapped to

a particular key or combination of keys on the terminal keyboard. To perform a function, you

press the appropriate key(s) from the command line or display form. For an explanation of

the command-line and display-form functions, see the Introduction to VOS (R001).

The keys that perform specific VOS functions vary depending on the terminal. For example,

on a V102 terminal, you press the and keys simultaneously to perform theINTERRUPT function; on a V103 terminal, you press the and keys simultaneouslyto perform the INTERRUPT function.

Note: Certain applications may define these keys differently. Refer to the

documentation for the application for the specific key mappings.

The following table lists several VOS functions and the keys to which they are mapped on

commonly used Stratus terminals and on an IBM® or IBM-compatible personal

computer (PC) that is running the Stratus PC/Connect-2 software. (If your PC is running

another type of software to connect to a Stratus host computer, the key mappings may be

different.) For information about the key mappings for a terminal that is not listed in this

table, refer to the documentation for that terminal.

† Keypad character

VOS Function V101 V102

V103

ASCII

V103

EPC

IBM or IBM-

Compatible PC

CANCEL * † * †

CYCLE -

CYCLE BACK - - - -

DISPLAY FORM - † - †

HELP - - - - -

INSERT DEFAULT - - - - -

INSERT SAVED

INTERRUPT - - - - -

NO PAUSE - - -* † -


6/122

Preface

vi Preface

Related Manuals

Refer to the following Stratus manuals for related documentation.

• VOS Commands Reference Manual (R098)

• VOS Standard C User’s Guide (R364)

• VOS PL/I Language Manual (R009)

• VOS Subroutines manualsVOS PL/I Subroutines Manual (R005)

VOS COBOL Subroutines Manual (R019)

VOS Pascal Subroutines Manual (R021)

VOS C Subroutines Manual (R068)

• VOS Forms Management System manuals

VOS PL/I Forms Management System (R016)

VOS COBOL Forms Management System (R035)

VOS Pascal Forms Management System (R039)

VOS C Forms Management System (R070)

Online DocumentationYou can find additional information by viewing the system’s online documentation in

>system>doc. The online documentation contains the latest information available,

including updates and corrections to Stratus manuals and a master glossary of terms.

A Note on the Contents of Stratus Manuals

Stratus manuals document all of the subroutines and commands of the user interface. Any

other operating-system commands and subroutines are intended solely for use by Stratus

personnel and are subject to change without warning.

Ordering Manuals

You can order manuals in the following ways.

• If your system is connected to the Remote Service Network (RSN), issue the

maint_request command at the system prompt. Complete the on-screen form with

all of the information necessary to process your manual order.

• Call the Stratus Customer Assistance Center (CAC) at (800) 221-6588 or

(800) 828-8513, 24 hours a day, 7 days a week. Your manual order will be forwarded

to Order Administration.

If you have questions about the ordering process, contact the CAC.

How to Comment on This ManualYou can comment on this manual by using the command comment_on_manual or by

completing the customer survey that appears at the end of this manual. To use the

comment_on_manual command, your system must be connected to the RSN. If your system

is not connected to the RSN, you must use the customer survey to comment on this manual.

The comment_on_manual command is documented in the manual VOS System

Administration: Administering and Customizing a System (R281) and VOS Commands


7/122

Preface

Migrating VOS Applications to Continuum Systems (R407) vii

Reference Manual (R098). There are two ways you can use this command to send your

comments.

• If your comments are brief, type comment_on_manual, press or , andcomplete the data-entry form that appears on your screen. When you have completed

the form, press .

• If your comments are lengthy, save them in a file before you issue the command. Type

comment_on_manual followed by -form , then press or . Enter thismanual’s part number, R407, then enter the name of your comments file in the

-comments_path field. Press the key that performs the CYCLE function to change the

value of -use_form to no and then press .

Note: Ifcomment_on_manual does not accept the part number of this manual (which

may occur if the manual is not yet registered in the manual_info.table file), you

can use the mail request of the maint_request command to send your comments.

Your comments (along with your name) are sent to Stratus over the RSN.

Stratus welcomes any corrections and suggestions for improving this manual.


8/122

Preface

viii Preface


9/122

Migrating VOS Applications to Continuum Systems (R407) ix

Contents

1. Continuum Features Affecting Application Migration . . . . . . . . . . . . . . . . . 1-1

Data Alignment Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Number of Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Memory on Each CPU/Memory Board . . . . . . . . . . . . . . . . . . . . . . . 1-3

The Virtually Indexed Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Increased Paging Space Requirements . . . . . . . . . . . . . . . . . . . . . . . 1-3

The Machine-Independent Locking Mechanism . . . . . . . . . . . . . . . . . . . 1-4

Process and Command Memory Limits . . . . . . . . . . . . . . . . . . . . . . . 1-4

Time-of-Day Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

ORACLE7 Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

2. Migrating Applications: a Step-by-Step Summary . . . . . . . . . . . . . . . . . . . 2-1

Preparing to Migrate Your Applications . . . . . . . . . . . . . . . . . . . . . . 2-1

Setting Up Your Environment . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Assuring Adequate Paging Space . . . . . . . . . . . . . . . . . . . . 2-1

Checking the Default Mapping Rules Value . . . . . . . . . . . . . . . . 2-2

Checking and Setting Process Command Limits . . . . . . . . . . . . . . 2-3

Deciding on a Data Alignment Strategy . . . . . . . . . . . . . . . . . . . . 2-3

Choosing between Longmap and Shortmap for Migrating MC68000 Applications . 2-4Choosing between Longmap and Shortmap for Migrating i860 Applications . . . 2-4

Choosing Features Newly Available with Continuum-Series Modules . . . . . . . . 2-5

Revising Your Source Modules . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

Correcting Incorrect or Inefficient Coding . . . . . . . . . . . . . . . . . . . 2-6

Revising Code to Implement New Features . . . . . . . . . . . . . . . . . . . 2-6

Compiling and Binding Applications for Continuum-Series Modules . . . . . . . . . . . 2-7

Migrating ORACLE Databases to Continuum-Series Modules . . . . . . . . . . . . . . 2-9

3. Addressing Alignment Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Understanding Shortmap and Longmap Data Alignment . . . . . . . . . . . . . . . . 3-2

Longmap and Shortmap Alignment Examples . . . . . . . . . . . . . . . . . . 3-2Language-Specific Alignment Differences . . . . . . . . . . . . . . . . . . . 3-4

Specifying Data Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Using the -mapping_rules Argument . . . . . . . . . . . . . . . . . . . . 3-5

Using Compiler Directives . . . . . . . . . . . . . . . . . . . . . . . . . 3-5

Using Shortmap and Longmap Attributes . . . . . . . . . . . . . . . . . . . 3-6

VOS Standard C Usage . . . . . . . . . . . . . . . . . . . . . . . . 3-6

VOS COBOL Usage . . . . . . . . . . . . . . . . . . . . . . . . . 3-8


10/122

Contents

x Contents

VOS Pascal Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

VOS PL/I Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

VOS FORTRAN Usage . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Determining What Must Be Shortmap-Aligned. . . . . . . . . . . . . . . . . . . . 3-9

Checking Structures Passed to Operating System Subroutines . . . . . . . . . . . 3-9

Retaining Shortmap Alignment for Pre-Defined Data Structures . . . . . . . . . 3-10

Correctly Aligning Structures in Communications-Based Applications . . . . . . . 3-10Handling Mixed Shortmap and Longmap Data . . . . . . . . . . . . . . . . . . . 3-11

Understanding Alignment Inheritance among Structures and Structure Elements . . . 3-11

VOS Standard C and VOS Pascal Usage . . . . . . . . . . . . . . . . 3-11

VOS PL/I Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12

Using the like Attribute . . . . . . . . . . . . . . . . . . . . 3-12

Using the type Attribute . . . . . . . . . . . . . . . . . . . . 3-13

Correcting Alignment Mismatches in Subroutine Arguments . . . . . . . . . . . 3-14

Ensuring Alignment Compatibility Between Arguments and Parameters . . . . . . 3-15

Avoiding Common Alignment Errors in VOS PL/I . . . . . . . . . . . . . . . . . 3-16

Ensuring Compatible Alignment of Based Storage Locations Referenced by Pointers . 3-16

Ensuring Correct Alignment of String Data . . . . . . . . . . . . . . . . . . 3-17

Ensuring Correct Alignment in Untyped Storage Sharing . . . . . . . . . . . . 3-18

Rearranging Structure Elements to Minimize Alignment Padding . . . . . . . . . . . 3-18

Correctly Aligning Simulations of dec 15 and dec 18 Data Types . . . . . . . . . . . 3-19

4. Correcting Programs to Work with a Large Register Set . . . . . . . . . . . . . . . . 4-1

Ensuring That Shared Data is Referenced Consistently . . . . . . . . . . . . . . . . . 4-1

Ensuring That Programs Access the Current Copy of Shared Data . . . . . . . . . . 4-2

Using the volatile Attribute to Inform the Compiler that Data Is Shared . . . . 4-2

Restricting Your Programming to Ensure that Programs Access Current Data . . . 4-3

Ensuring That Only One Program at a Time Updates Shared Data . . . . . . . 4-4

Compiling with the -table or -production_table Argument . . . . . . . . . . 4-5

Modifying VOS Standard C setjmp and longjmp Function Calls . . . . . . . . . . . . 4-6Using the VOS PL/I defined Storage Class. . . . . . . . . . . . . . . . . . . . . 4-7

Using Alternatives to Defined Overlays . . . . . . . . . . . . . . . . . . . . 4-7

Using Alternatives to Defined Pointers . . . . . . . . . . . . . . . . . . 4-8

Using Untyped Storage Sharing . . . . . . . . . . . . . . . . . . . . . 4-8

Modifying Routines That Directly Access the Stack . . . . . . . . . . . . . . . . . . 4-8

5. Correcting Coding Practices That Jeopardize Portability . . . . . . . . . . . . . . . . 5-1

Working with Highly Optimized Code . . . . . . . . . . . . . . . . . . . . . . . 5-1

Recoding Loops the Compiler Might Eliminate. . . . . . . . . . . . . . . . . . . . 5-2

Revising Code That Depends on Unreferenced Variables . . . . . . . . . . . . . . . . 5-2

Revising Code for Compatibility of Floating-Point Precision . . . . . . . . . . . . . . 5-2Handling and Debugging Floating-Point Exceptions . . . . . . . . . . . . . . . . . . 5-3

Checking for Uninitialized Variables . . . . . . . . . . . . . . . . . . . . . . . . 5-3

Checking Function Calls to and from VOS FORTRAN . . . . . . . . . . . . . . . . 5-4


11/122

Contents

Migrating VOS Applications to Continuum Systems (R407) xi

6. Improving Memory Access by Specifying Memory Pools . . . . . . . . . . . . . . . . 6-1

Memory Access on a Continuum-Series Module . . . . . . . . . . . . . . . . . . . 6-1

Controlling Which Memory Pool a Process Uses . . . . . . . . . . . . . . . . . . . 6-2

Revising s$start_process Calls to s$start_new_process Calls . . . . . . . . 6-2

Evaluating s$clone Subroutine Calls . . . . . . . . . . . . . . . . . . . . . 6-3

Specifying Memory Pool Assignment in Command Macros . . . . . . . . . . . . 6-3

Getting Information on Memory Pool Assignment . . . . . . . . . . . . . . . . . . 6-4Using the s$get_process_info and s$get_processes_info Subroutines . . . . 6-4

Using the list_users Command . . . . . . . . . . . . . . . . . . . . . . 6-4

7. Efficiently Using Continuum-Series Caches . . . . . . . . . . . . . . . . . . . . . 7-1

Improving Performance with Caches . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Determining Cache Line Boundaries . . . . . . . . . . . . . . . . . . . . . 7-2

Minimizing Data Sharing Among Processors . . . . . . . . . . . . . . . . . . 7-3

Fully Utilizing Each Cache Line . . . . . . . . . . . . . . . . . . . . . . . 7-4

Avoiding Problems with the Instruction Cache . . . . . . . . . . . . . . . . . 7-5

Understanding Memory-Ordering, Caching Policies, and Locking . . . . . . . . . . . . 7-5

Caching Policies that Support Memory-Ordering . . . . . . . . . . . . . . . . 7-5Exclusive Non-Sequential and Shared Non-Sequential Caching Policies . . . . . . . 7-6

8. Upgrading to Machine-Independent Locks . . . . . . . . . . . . . . . . . . . . . . 8-1

Choosing a Locking Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Using the Machine-Independent Lock Interfaces . . . . . . . . . . . . . . . . . . . 8-1

9. Restricting the Memory Used by Programs or Processes . . . . . . . . . . . . . . . . 9-1

Understanding Program Address Space Changes . . . . . . . . . . . . . . . . . . . 9-1

Limiting Virtual Memory Allocation for a Program or Command . . . . . . . . . . . . 9-3

Additional bind Command Arguments for Managing Address Space . . . . . . . . . . . 9-5

Bind Directives for Creating a Shared Virtual Memory Database . . . . . . . . . . . . . 9-5

10. Upgrading to the Microjiffy Time-of-Day Clock . . . . . . . . . . . . . . . . . . 10-1

The Time-of-Day Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

Using the Interfaces to the Time-of-Day Clock . . . . . . . . . . . . . . . . . . . 10-1

11. Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

Diagnosing and Correcting Paging Space Problems . . . . . . . . . . . . . . . . . 11-1

Avoiding Inefficient Cache Usage . . . . . . . . . . . . . . . . . . . . . . . . 11-3

Checking for Alignment Faults Causing Uneven Performance . . . . . . . . . . . . . 11-3

Correcting Problems Related to Process and Program Limits . . . . . . . . . . . . . 11-4Setting Limits Too High . . . . . . . . . . . . . . . . . . . . . . . . . 11-4

Setting Limits Too Low . . . . . . . . . . . . . . . . . . . . . . . . . 11-4

Setting Inconsistent Limits . . . . . . . . . . . . . . . . . . . . . . . . 11-5

Running Programs on Modules with Insufficient Default Limits. . . . . . . . . . 11-5


12/122

Contents

xii Contents

Appendix A. Migrating Forms Management System (FMS) Applications . . . . . . . . . A-1

Choosing the Appropriate Forms Editor. . . . . . . . . . . . . . . . . . . . . . A-1

Editing and Recompiling FMS Files . . . . . . . . . . . . . . . . . . . . . . . A-1

Using the Form Options Form . . . . . . . . . . . . . . . . . . . . . . A-2

Using a Command Macro to Edit the Forms . . . . . . . . . . . . . . . . . A-3

Binding Applications Compiled with nls_edit_form . . . . . . . . . . . . . . . A-4

Appendix B. Finding and Correcting Runtime Alignment Faults. . . . . . . . . . . . . B-1

Using the set_alignment_fault_mode Command . . . . . . . . . . . . . . . . B-2

Using the profile Command . . . . . . . . . . . . . . . . . . . . . . . . . B-3

Using the VOS System Analysis Subsystem . . . . . . . . . . . . . . . . . . . . B-4

Logging Alignment Fault Information . . . . . . . . . . . . . . . . . . . . B-5

Displaying Alignment Fault Information . . . . . . . . . . . . . . . . . . . B-6

Determining Which Program to Analyze . . . . . . . . . . . . . . . . . . . B-7

Using analyze_system from the Same Process That Ran the Program . . . . B-7

Using analyze_system from a Process That Did Not Run the Program . . . B-8

Analyzing a Non-Running Program . . . . . . . . . . . . . . . . . . . . . B-9

Examining Assembly Language Code . . . . . . . . . . . . . . . . . . . . B-10Using Information in the .list File . . . . . . . . . . . . . . . . . . . . . . . B-11

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1


13/122

Migrating VOS Applications to Continuum Systems (R407) xiii

Figures

Figure 9-1. Program Address Space on Continuum-Series Modules . . . . . . . . . . . . . 9-2


14/122

xiv Tables

Tables

Table 7-1. Cache Sizes on Continuum-Series Models . . . . . . . . . . . . . . . . . . . 7-2

Table 8-1. Additional Access Modes for Connecting a Process’s Virtual Memory to a File . . . . 8-2


15/122

Migrating VOS Applications to Continuum Systems (R407) 1-1

Chapter 1:

Continuum Features Affecting Application Migration 1-

This chapter describes the features of a Continuum-series module and its PA-RISC™

processor that affect what users or system administrators must do to migrate applications to

the Continuum platform. The following features affect application migration.

• data alignment rules that, for optimal performance, require a data item to be aligned on

a boundary congruent to its size

•

a larger number of registers than other processors used by previously released Stratusmodules

• the absence of extended precision registers, causing the results of some complex

floating point calculations to differ in the low-order bits from identical calculations on

a processor in the MC68000® processor family

• memory residing on each CPU/memory board rather than on separate memory boards,

and an interface that allows you to specify which memory a process uses

• a high-speed, direct map (virtually indexed) cache

• a requirement for more paging space than was necessary for the MC68000 processor

family

• reliance on machine-independent locking instructions that replace hardware-based

StrataBUS-style locks

• an interface that lets you restrict the virtual memory allowed for a program or process

• a Time-of-Day Clock that provides greater accuracy than previous Stratus clocks

Data Alignment Rules

The PA-RISC processor, like the i860™ processor, requires more stringent data alignment

than the MC68000 processor family. Whenever possible, a data item should lie on a boundary

congruent to its size: 2-byte items on mod2 boundaries, 4-byte items on mod4 boundaries,

and so forth up to mod8. Stratus calls such alignment longmap alignment.

The PA-RISC processor allows misaligned accesses, but at a performance cost. If the

compiler detects misalignment, there is a significant performance degradation per storage

access. If the compiler cannot detect the misalignment, the operating system fault handler


16/122

Number of Registers

1-2 Chapter 1: Continuum Features Affecting Application Migration

performs the access at a much greater performance penalty than if the compiler had

performed it.

If the application was written, compiled, and bound for one of the MC68000 family of

processors (one of the XA2000-series models), check for and correct alignment problems, as

described in Chapter 3, ‘‘Addressing Alignment Issues.”

If the application you are migrating was written, compiled, and bound for an i860 processor,

it should already have correct data alignment for recompilation, with longmap alignment

rules, so you should not need to address alignment issues.

If the application you are migrating was originally an MC68000-based application that was

subsequently migrated to the i860 platform, recompile it with longmap alignment rules if it

was recompiled with longmap for the i860 migration. However, you may have recompiled the

application for the i860 platform using shortmap alignment rules and then corrected only

those misalignments that seriously impacted performance. In this case, you can migrate the

application to the Continuum platform in either of the following ways:

•

Recompile the application again, using shortmap alignment rules and addressingmisalignments that significantly degrade performance.

• Recompile the application using longmap alignment rules, fully addressing alignment

issues necessary to use longmap and therefore taking full advantage of the performance

gains that using longmap entails.

See Chapter 2, ‘‘Migrating Applications: a Step-by-Step Summary,” for information on

choosing an alignment strategy and Chapter 3, ‘‘Addressing Alignment Issues,” for more

information on data alignment issues.

Number of Registers

Since the PA-RISC processor has many more registers than any processor in the MC68000

processor family, the compilers can keep the values of more variables in registers than they

could on the MC68000 processors. Keeping variables in registers reduces accesses to main

memory when a program needs to reference a variable. Fewer accesses to memory means a

performance gain.

Some improperly coded applications that worked without error on processors in the

MC68000 family may not work on the PA-RISC processor because the values of more

variables are kept in registers. In some cases, an application fails because it accesses a

variable in a register, but the variable’s value has been changed in memory by another process

or device. In other cases, when you use VOS PL/I based storage inappropriately, an

application fails because it uses a value in memory, but a new value in a register has not beenflushed to that memory address.

Furthermore, because of the large number of registers, when a program calls a subroutine,

parameters are generally passed in registers rather than on the stack. Therefore, any routine

that directly accesses the stack or has knowledge of stack frame data layouts must be

modified.


17/122

Memory on Each CPU/Memory Board


See Chapter 4, ‘‘Correcting Programs to Work with a Large Register Set,” for information on

how to check for and modify your applications to avoid problems resulting from the PA-RISC

processor’s large register set.

Memory on Each CPU/Memory Board

On Continuum-series modules, physical memory resides on each CPU/memory board ratherthan on separate memory boards. However, as with earlier Stratus hardware platforms,

physical memory is divided among memory boards, and any CPU can access any memory.

Memory is divided into pools, one associated with each logical CPU/memory board. On a

Continuum-series module with more than one logical CPU/memory board, Pool 0 is the local

memory on the same CPU/memory board on which the module booted, and Pool 1 is the

remote memory on the other CPU/memory board or boards. (A Continuum-series module

with only one logical CPU/memory board has only one memory pool, Pool 0.) Since accesses

to memory on the same board as a CPU need not travel over the system bus, accesses to such

local memory can be up to three times faster than accesses to remote memory.

Chapter 6, ‘‘Improving Memory Access by Specifying Memory Pools,” discusses thesubroutines and commands you can use to manage physical memory. These subroutines and

commands enable you to determine what memory pool a process is using and let you specify

which memory pool you want a new process to use so that you can minimize memory access

over the bus. You can also use these subroutines and commands to ensure that two processes

run either on the same CPU/memory board or on different CPU/memory boards.

The Virtually Indexed Cache

Each Continuum-series CPU/memory board contains a large, high-performance, external

direct map cache, i.e. a cache that is virtually indexed. The high-performance cache greatly

improves performance if you use caching efficiently. See Chapter 7, ‘‘Efficiently UsingContinuum-Series Caches,” for information on making the best use of the cache, and see

‘‘Avoiding Inefficient Cache Usage’’ in Chapter 11 for information on avoiding caching

problems.

Increased Paging Space Requirements

When you are compiling a program to run on a module with a PA-RISC processor, the module

on which you are compiling must have enough paging space available to avoid running out

of virtual memory. For each simultaneous large compilation, the module needs approximately

16,000 pages of paging space. (This estimate also applies to i860XR and i860XP processors.)

You also need to allow an additional number of pages per user on the module. That number

is site-specific, depending on what applications users are running and how much virtualmemory those applications are known to use. You will need one page of paging partition for

every page of virtual memory used by a process, excluding pages containing executable code.

In some cases you may need to increase the paging capacity, especially for modules used

heavily for application development. Use the display_paging_usage command or the

s$get_paging_usage subroutine to retrieve information on the current paging usage and

the available paging space on a module. See Chapter 11, ‘‘Troubleshooting,’’ for information

on how to increase the paging space on a module by using the add_paging_file command


18/122

The Machine-Independent Locking Mechanism


to add paging files without a module reboot, or by using the -pagepart_size argument of

update_disk_label command to increase the paging partition size of a non-boot disk at

the next module reboot.

The Machine-Independent Locking Mechanism

Beginning with Release 13.0, VOS uses a machine-independent locking mechanism ratherthan the StrataBUS locking mechanism. Chapter 8, ‘‘Upgrading to Machine-Independent

Locks,” explains how to upgrade your applications to use this more efficient locking

mechanism. It also describes the subroutines available to initialize, locate, lock, unlock, or

check the status of a lock in shared virtual memory.

An emulation of the StrataBUS locking mechanism is still available for compatibility with

existing programs. However, the emulation is carried out by a fault handler and entails a

performance penalty that is approximately equivalent to that of an alignment fault. Therefore,

Stratus recommends that you upgrade your applications to use the machine-independent

locking mechanism.

Note: Simply recompiling your applications on a Continuum-series module does not implement the machine-independent locking mechanism. Code that is recompiled for

use on Continuum-series modules uses StrataBUS lock emulation unless you follow

the instructions in Chapter 8.

Process and Command Memory Limits

Beginning with Release 13.0, VOS increases the total virtual memory available for user

processes to 1 GB, although the default virtual memory size for a process will continue to be

64 MB.

The increase in virtual memory potentially available to applications makes it possible for a

programming error to cause a program to recursively use large quantities of memory before

failing. Therefore, VOS 13.0 and later releases provide commands and subroutines that

enable you to determine current process and command limits and set limits to the amount of

virtual memory a process or command can use.

• The commands list_process_cmd_limits and update_process_cmd_limits

enable you to list and set memory limits for your own processes, or, if you are a

privileged user, for other processes.

• Arguments added to the bind command enable you to specify such limits on a

per-program basis.

• The system administration commands list_default_cmd_limits and

update_default_cmd_limits enable you to list and set default virtual memory

limits for all processes and commands that run on the module.

• A program can use the s$set_current_cmd_limit and

s$get_current_cmd_limit subroutines to manage its current command limits.


19/122

Time-of-Day Clock


See Chapter 9, ‘‘Restricting the Memory Used by Programs or Processes,” for more

information on these commands and subroutines. For full command descriptions, see the VOS

Commands Reference Manual (R098) for the general user commands and VOS System

Administration: Administering and Customizing a System (R281) for the system

administration commands. For full subroutine descriptions, see the VOS Subroutines

manuals.

Time-of-Day Clock

Continuum-series modules have a Time-of-Day clock that is more precise than clocks on all

previous Stratus modules except the XA/R Model 300. While previous clocks measured time

to the precision of a jiffy, which is 1/65,536 of a second, the Continuum-series and XA/R

Model 300 clocks measure time to the precision of a microjiffy, which is 1/65,536 of a jiffy.

Two subroutines, s$read_clock and s$clock_date_time, provide the user interface to

the Time-of-Day clock. See Chapter 10, ‘‘Upgrading to the Microjiffy Time-of-Day Clock ,”

for more information on these subroutines, and see the VOS Subroutines manuals for full

subroutine descriptions. You can use these subroutines on any Stratus platform, but the

precision of the date/time values they return will depend on the precision of the platform’s

clock.

ORACLE7 Support

Continuum-series modules support ORACLE7™ databases, but no earlier releases of

ORACLE. For information on migrating ORACLE Release 6 database files to

Continuum-series modules, see ‘‘Migrating ORACLE Databases to Continuum-Series

Modules’’ in Chapter 2.


20/122

ORACLE7 Support



21/122


Chapter 2:

Migrating Applications: a Step-by-Step Summary 2-

This chapter provides a step-by-step description of the tasks you perform to migrate

applications to the PA-RISC architecture. It refers you to other chapters in this manual and to

other manuals for detailed information on particular tasks.

Read through the entire chapter for an overview of the migration procedure. Then follow the

steps, referring to the cross-referenced information as needed.

Preparing to Migrate Your Applications

This section describes how to set up your environment for a successful migration, choose

among several approaches to data alignment, and upgrade your application to use new

features available with the Continuum platform.

Setting Up Your Environment

In setting up your environment, check and make changes to the following, if necessary:

• the available paging space

• the default mapping rules (alignment rules) for your module

•

the default process maximum command limits for your module

Assuring Adequate Paging Space

When a PA-RISC module is installed, by default the boot disk has 6000 pages of paging

partition, and the other disks have none. The system administrator must expand paging space

available on the module based on the projected usage of the module.

To avoid running out of virtual memory on a module with a PA-RISC processor, the system

administrator must ensure that the total paging space available on the module is adequate both

for the compilation of programs and for the running of user processes and applications.

For each simultaneous large compilation, the module needs approximately 16,000 pages of

paging space. Therefore, 32,000 pages of paging space allows the compiling of two largeapplications or a large application and a number of small applications simultaneously. (This

estimate also applies to i860XR and i860XP processors.)

For user processes and applications, the number of pages needed is site-specific, depending

on what applications users are running and how much virtual memory those applications are

known to use.You will need one page of paging partition for every page of virtual memory

used by a process, excluding pages containing executable code.


22/122


2-2 Chapter 2: Migrating Applications: a Step-by-Step Summary

To display information about current paging space on one or more modules, use the

display_paging_usage command. The display_paging_usage command reports

paging space in blocks (units of physical disk space 4096 bytes in size). The number of

physical blocks of paging space is equivalent to the number of pages (units of virtual memory,

also 4096 bytes in size). The output is similar to the following.

Paging usage for module %s1#m2: 16174 blocks out of 110000 (14%)

The output shows total paging space, paging space currently in use, and the percentage of

usage for each specified module. Paging space usage is shown for the paging partitions and

also for any dynamic paging files that were allocated with the add_paging_file command.

Note: The display_disk_info command with the -long argument displays a list

of the disks on the current module and the size of their partitions, including their paging

partitions. However, this command does not provide information on paging space

available in dynamic paging files allocated with the add_paging_file command.

See Chapter 11, ‘‘Troubleshooting,” for information on how to use either

add_paging_file to add dynamic paging files without a reboot or update_disk_label to increase the paging partition size on a disk at the next reboot. For complete command

descriptions of these two commands, see the manual VOS System Administration: Disk and

Tape Administration (R284).

Checking the Default Mapping Rules Value

For VOS Release 13 and later releases, the default mapping rules (alignment rules) for

compiling programs is set to shortmap data alignment, unless your system administrator

has changed that default. If your site has previously upgraded its applications to use

longmap data alignment when migrating from the MC68000 to the i860 platform, your

system administrator may find it useful to change the default mapping rules.

Caution: Recompiling a working program with the default mapping rules set to avalue you did not intend can require a significant amount of work to correct your

error.

Default mapping rules determine the data alignment of a program if you do not specify

longmap or shortmap alignment rules, as described in Chapter 3, ‘‘Addressing Alignment

Issues,” or if you use the default or default/check value for the -mapping_rules

argument of one of the compiler commands.

If you are not sure whether the system administrator has reset the default mapping rules, type

the following command and press .

display_error m$default_mapping

The command returns a message code and a one-word message indicating whether the default

mapping rules are shortmap or longmap. For example:

Code 4991. shortmap


23/122



Checking and Setting Process Command Limits

VOS Release 13 and later releases provide both system administrators and general users a

way to control how much virtual memory a process or program can use. Setting virtual

memory limits minimizes the effect of a runaway process that could potentially use all

available virtual memory on the module through unintended recursion.

By default, unless changed by a system administrator, the default command limits on aContinuum-series module are as follows:

• 268,435,456 bytes (256 MB) for total virtual memory used by a process, 134,217,728

bytes (128 MB) for a process’s total heap space, and 134,217,728 bytes (128 MB) for

a process’s total stack space

• 67,108,864 bytes (56 MB) for the initial total virtual memory limits for a command (a

program module), 67,108,864 bytes (56 MB) for the heap and 8,388,608 bytes (8 MB)

for the stack. You can use subroutine calls within a program to reset these limits up to

the maximum for your process.

As you plan to recompile applications for the PA-RISC platform, you may want to check tobe sure a system administrator has not reset the default command limits for the module. To

check these limits, use the list_default_cmd_limits command.

If you find the current default command limits for the module too restrictive, and you are a

system administrator, you can change these limits with the command

update_default_cmd_limits. To avoid possible problems when running the same

programs on different modules, see ‘‘Running Programs on Modules with Insufficient

Default Limits’’ in Chapter 11.

For more information on default command limits, see Chapter 9, ‘‘Restricting the Memory

Used by Programs or Processes.”

You can manage process command limits with VOS commands and subroutines. You can use

VOS commands to display and set process maximum command limits and process initial

command limits from command level or from within a command macro. You can use VOS

subroutines to set and get the calling program’s maximum and current command limits while

a program runs. See Chapter 9 for information on these commands and subroutines. For

information on avoiding problems caused by the stack size restricting the dynamic allocation

of heap space, see ‘‘Setting Inconsistent Limits’’ in Chapter 11.

Deciding on a Data Alignment Strategy

To take full advantage of the performance improvement available with the PA-RISC

processor, Stratus recommends recompiling with longmap alignment rules when migrating an

application to the PA-RISC processor. Ideally, all data elements that do not have to be

shortmapped for a specific reason should be longmap-aligned for optimal performance. The

compilers consider shortmapped data to be misaligned. Therefore, the compilers must

generate additional instructions to handle shortmapped data. In some cases, a compiler does

not recognize that the data is misaligned, so the misaligned data causes a fault handler to be

invoked at runtime, resulting in a much greater performance penalty.


24/122



However, you can make an application compiled with shortmap data alignment work

effectively on a PA-RISC processor. Using shortmap data alignment, you will not benefit

fully from the performance advantage of the PA-RISC processor. But after you diagnose and

fix the major instances of misaligned data affecting performance, in most cases, the

performance penalty for choosing shortmap alignment will not be noticeable.

Choosing between Longmap and Shortmap for Migrating MC68000 ApplicationsUse the following guidelines to choose a data alignment strategy for migrating

MC68000-based applications to the PA-RISC processor.

If you developed your application on a processor in the MC68000 processor family and used

it only on that platform, it is currently shortmap aligned. In this case, do the following:

• For an understanding of the tasks you must perform to convert the application to

longmap alignment, read all of Chapter 3, ‘‘Addressing Alignment Issues,” and

Appendix B, ‘‘Finding and Correcting Runtime Alignment Faults.” Appendix B

provides a summary of the options and tools available for tracking and correcting

alignment faults that may noticeably slow the performance of your application.

• For an understanding of the tasks you must perform if you compile the application

using shortmap alignment rules, read ‘‘Understanding Shortmap and Longmap Data

Alignment” and ‘‘Specifying Data Alignment’’ in Chapter 3. Alignment faults are

uncommon in shortmap-aligned applications. If, however, you plan to use compiler

directives to specify certain data elements as longmap, but compile using shortmap

alignment rules, you must understand how mixed data alignment is handled. Read

‘‘Handling Mixed Shortmap and Longmap Data’’ in Chapter 3 for information on how

to avoid data misalignment when using shortmap and longmap in the same application.

If you do encounter alignment faults at runtime, refer to Appendix B, ‘‘Finding and

Correcting Runtime Alignment Faults.”

• Choose the alignment strategy best suited to your current needs. Remember, yourdecision is reversible. Keep copies of your original source modules. If you decide to

compile all your applications using shortmap alignment rules to complete the migration

work quickly, you can later decide to upgrade applications to longmap on a

case-by-case basis over time to further improve performance.

Choosing between Longmap and Shortmap for Migrating i860 Applications

Use the following guidelines to choose a data alignment strategy for migrating i860-based

applications to the PA-RISC processor.

If you originally developed your application on an i860 processor with longmap data

alignment, you should experience very few or no instances of misaligned data when

recompiling for the PA-RISC platform. In this case, definitely choose longmap dataalignment for the migration to PA-RISC.

If you developed your application on one of the MC68000-based processors and subsequently

migrated it to an i860 processor, do the following:

• If you selected longmap data alignment for the MC68000 to i860 migration, you should

experience very few or no instances of misaligned data when recompiling for the

PA-RISC platform. In this case, definitely choose longmap data alignment for the


25/122

Revising Your Source Modules


migration to PA-RISC, since most of your work with regard to data alignment is already

done.

• If you selected shortmap data alignment for the MC68000 to i860 migration and

thoroughly tracked and fixed instances of misaligned data at that time, you can either

retain the shortmap alignment or upgrade to longmap for the i860 to PA-RISC

migration. Retaining shortmap alignment should work without causingalignment-related performance problems, since you fixed most instances of misaligned

data in the previous MC68000 to i860 migration. However, Stratus recommends that

you upgrade to longmap data alignment to take full advantage of the performance gains

of the PA-RISC processor, either at the time of your initial application migration to

PA-RISC, or on an application-by-application basis over time.

Choosing Features Newly Available with Continuum-Series Modules

No matter what prior platform you are migrating your application from, consider

implementing the features that are newly available with Continuum-series modules

beginning with VOS Release 13. Stratus strongly recommends the use of these features. The

work involved in implementing them is minimal.

The following list summarizes the new features and indicates where they are documented.

• Memory pool specification is documented in Chapter 6, ‘‘Improving Memory Access

by Specifying Memory Pools.” Controlling a process’s memory pool assignment can

improve application performance by eliminating needless memory accesses across the

bus and by ensuring, for example, that programs sharing the same virtual memory are

assigned to the same memory pool.

• Machine-independent locks are documented in Chapter 8, ‘‘Upgrading to

Machine-Independent Locks.” Six subroutines for using the machine-independent

locking mechanism replace the existing spin lock operating system library routines andprovide improved performance and some new capabilities.

• General user commands and subroutines for setting process initial virtual memory

limits and process maximum command virtual memory limits are documented in

Chapter 9, ‘‘Restricting the Memory Used by Programs or Processes.” You can set and

manage such limits by using VOS subroutines in your source module, bind command

options when you bind a program, and VOS commands at command level or within

command macros.

• The new Time-of-Day clock that measures time in microjiffies is documented in

Chapter 10, ‘‘Upgrading to the Microjiffy Time-of-Day Clock .”


This section briefly describes the steps to take in revising a source module when migrating

an application to the PA-RISC platform.


26/122



Correcting Incorrect or Inefficient Coding

If you developed and ran your application only on the MC68000 platform, check the source

module for incorrect coding that may fail when you migrate the application to the PA-RISC

platform. Program failures often occur because of the large number of registers with the

PA-RISC platform, which allows variables to be stored more frequently in registers rather

than written to memory. With incorrect coding, the wrong value for the variable may be used:either the register value when the value in memory should be used, or the value in memory

when the register value should be used. See Chapter 4, ‘‘Correcting Programs to Work with

a Large Register Set,” for information on the coding practices to search for in order to find

and correct these errors.

If you developed your application on the i860 platform or previously migrated your

application from the MC68000 to the i860 platform, instances of application failure due to

accessing the wrong value for a variable, as described in the preceding paragraph, should not

occur when you migrate the application to the PA-RISC platform. However, Chapter 4,

‘‘Correcting Programs to Work with a Large Register Set,” contains some new information,

not documented in Migrating VOS Applications to the Stratus RISC Architecture (R288),

about coding corrections and improvements you should make. This new information isrelevant for migrating i860-based programs as well as MC68000-based programs to the

PA-RISC platform and includes the following:

• alternatives to using defined storage in VOS PL/I in certain cases, avoiding the frequent

memory accesses required by defined storage

• changes in how to use VOS Standard C functions that access variable length argument

lists

• instructions on replacing the now obsolete VOS PL/I arglistptr built-in function

Before migrating any MC68000 or i860 application to the PA-RISC platform, read Chapter 5,

‘‘Correcting Coding Practices That Jeopardize Portability.” Since the problematic coding

practices described in Chapter 5 are not related to data alignment, read the chapter regardless

of whether you plan to use longmap or shortmap alignment rules in migrating your

application. If you already migrated your application from the MC68000 platform to the i860

platform, you probably already encountered and corrected the programming errors and

inefficiencies described in Chapter 5. However, the chapter provides some new information,

not documented in Migrating VOS Applications to the Stratus RISC Architecture (R288), on

alternative coding to correct the practices described. Therefore, the information may be

helpful in further improving the performance of your applications.

Revising Code to Implement New Features

Revise the source modules and/or command macros of your application to implement any ofthe new features available with the PA-RISC platform and briefly described in ‘‘Choosing

Features Newly Available with Continuum-Series Modules” earlier in this chapter.

To specify how new processes are assigned to memory pools, replace s$start_process

calls with s$start_new_process calls in source modules and use the new

-memory_pool argument to the start_process command in command macros. See

Chapter 6, ‘‘Improving Memory Access by Specifying Memory Pools,” for more


27/122

Compiling and Binding Applications for Continuum-Series Modules


information. Also see the VOS Subroutines manuals for full subroutine descriptions, and the

VOS Commands Reference Manual (R098) for a full description of the start_process

command.

To implement the machine-independent locking mechanism available on the PA-RISC

platform, recode calls to s$connect_vm_region with new access_mode values, and

replace the existing spin lock routines with the new virtual memory locking subroutines. SeeChapter 8, ‘‘Upgrading to Machine-Independent Locks,” for descriptions of the access

modes and brief descriptions of the new subroutines and their purposes.

Note: If you do not explicitly implement the machine-independent locking

mechanisms, your application will invoke a fault handler at every instance of one of the

existing spin lock routines in order to emulate the now obsolete StrataBUS-style

locking mechanism.

For full descriptions of the new virtual memory locking subroutines and the usage changes to

s$connect_vm_region, see the VOS Subroutines manuals.

To manage the program or process limits of your application, use the VOS subroutiness$set_current_cmd_limit and s$get_current_cmd_limit in your application’s

source modules, and the command update_process_cmd_limits in your application’s

command macros. You can also manage program and process limits at bind time with options

to the bind command, and you can monitor program and process command limits from VOS

command level with the command list_process_cmd_limits . Chapter 9, ‘‘Restricting

the Memory Used by Programs or Processes,” summarizes these subroutines and commands.

For full descriptions of the subroutines, see the VOS Subroutines manuals, and for full

descriptions of the commands, see the VOS Commands Reference Manual (R098).

In any context where time accuracy to the microjiffy level (1/65,536 of a jiffy or 232.83

picoseconds) would be useful, replace your application’s calls to the subroutines

s$int_date_time and s$jiffy_date_time with calls to s$clock_date_time. Alsoreplace calls to s$read_jiffy_clock with calls to s$read_clock. See Chapter 10,

‘‘Upgrading to the Microjiffy Time-of-Day Clock ,” for information on using these

subroutines to access the Continuum-series Time-of-Day clock that measures time in

microjiffies. For full descriptions of the subroutines, see the VOS Subroutines manuals.


To choose between recompiling an application using longmap data alignment or shortmap

data alignment, see ‘‘Deciding on a Data Alignment Strategy” earlier in this chapter. Note

that Stratus recommends longmap alignment rules to take full advantage of the high

performance available with the Continuum platform.

See the VOS Commands Reference Manual (R098) for command descriptions of all

commands referenced in this section.

If you are recompiling an application with longmap alignment rules, perform the following

tasks, which are described in detail in Chapter 3, ‘‘Addressing Alignment Issues.”


28/122



1. For the compiler command you are using, choose the longmap/check value for the

-mapping_rules argument, and use the -cpu_profile argument (or, for VOS

Standard C, the -qc argument).

2. Where compiler messages indicate that padding has been added to correct misaligned

data, reorganize data structures where possible to place the longest data elements first,

thereby reducing the padding required.

3. Where padding remains necessary, add the padding explicitly in your source module

rather than letting the compiler add the padding. Explicitly added padding makes a

program easier to understand and therefore easier to maintain.

4. Explicitly declare as shortmap any data elements that must remain shortmap, such as

structures that contain elements longer than two bytes and that are passed to operating

system subroutines, user-interface structures of many VOS Communications Software

products, and data structures or records that overlay existing shortmapped database

records.

5. If you want the application to recompile with longmap data alignment for all futurerecompilations, insert a longmap compiler directive (or in VOS COBOL, a language

statement) in the source module. Such directives override any value specified with the

-mapping_rules argument.

6. Rebind your application, using the -profile_alignment_faults argument of the

bind command and any arguments (or equivalent binder control file directives) you

choose to control program, stack, heap and fence size.The -size,

-max_program_size, -load_point, -stack_size, -stack_fence_size,

-max_stack_size, and -max_heap_size arguments (or equivalent binder control

file directives) control overall address space and stack and heap growth for your

program module. Controlling stack and heap growth is a safety measure, especially for

processes that contain recursive algorithms that can use much stack or heap space. Theresult of such uncontrolled growth can be an application failure or module interruption.

See the description of the bind command in the VOS Commands Reference

Manual (R098) for information on how these arguments or directives interact and when

to use them rather than rely on default values.

7. Run the application. The system generates a program_name.profile file.

8. Use the profile command to generate a file named program_name.plist.

9. Check the ALIGN FLTS column in the .plist file for the number of alignment faults

per second. If the .plist file indicates more than one hundred alignment faults per

second, look for major problem areas and fix their alignment. If you have between 10and 100 alignment faults per second and the program performance is satisfactory, you

may decide to leave the remaining misaligned data, realizing that you are not taking full

advantage of the high performance of the PA-RISC platform. If your alignment faults

are 10 or fewer per second, any further minor performance gain you could achieve is

probably not worth the effort necessary to find and correct the faults. These guidelines

are general and are recommendations only. Your own experience with your application

is your best guide.


29/122

Migrating ORACLE Databases to Continuum-Series Modules


Note: The alignment fault level for an application varies according to which lines

of code are executing. Therefore, factors such as transaction type and even time

of day may affect the number of alignment faults and consequently the

application’s performance. If performance is unsatisfactory in particular

circumstances, you may want to use the profile command to generate a new

program_name.plist file so that you can check the alignment fault level

again.

10. See Appendix B, ‘‘Finding and Correcting Runtime Alignment Faults,” for

information on tools to track, diagnose, and correct runtime alignment faults. These

include analyze_system requests that locate alignment faults and display alignment

fault information and the command set_alignment_fault_mode that stops your

program’s execution, for debugging purposes, at each runtime alignment fault.

11. Correct alignment faults until you succeed in reducing the number to an acceptable

level that does not noticeably degrade application performance. You may want to

recompile, rebind, and run the application again, as described earlier in this list, so that

you can recheck the number of alignment faults per second to help you decide when

you have corrected enough of the runtime alignment faults.

If you are recompiling an application with shortmap alignment rules, perform the following

tasks:

1. Compile your code with shortmap alignment rules, using the -cpu_profile

argument for the compiler command or, for VOS Standard C, the -qc argument.

2. Bind your application using the -profile_alignment_faults argument of the

bind command and any arguments you select to control program, stake, heap, and

fence size. (See step 6 in the preceding list for information on the arguments for

controlling program, stack, heap, and fence size.)

3. Run the application. The system generates a file named program_name.profile.

4. Use the profile command to generate a file named program_name.plist.

5. Check the ALIGN FLTS column in the .plist file for the number of alignment faults

per second. It is unlikely that a shortmap-aligned program will have a large number of

alignment faults. However, if the .plist file indicates 10 or more alignment faults per

second, follow the recommendations in step 9 in the preceding list for longmap data

alignment. If you decide to find and correct the faults, perform steps 10 and 11 from the

preceding list.

Migrating ORACLE Databases to Continuum-Series ModulesAlthough ORACLE releases earlier than ORACLE7 are not supported on Continuum-series

modules, you can migrate ORACLE Release 6 database files to Continuum. However, you

cannot use the ORACLE Migration Utility to migrate the files, since that utility requires a

version of ORACLE Release 6 to be running on the target module.

To migrate ORACLE Release 6 database files to Continuum-series modules, follow these

steps:


30/122

Migrating ORACLE Databases to Continuum-Series Modules


1. Run the ORACLE Export Utility (EXP) on the XA2000-series or XA/R-series module

on which the ORACLE Release 6 database files reside.

2. Run the ORACLE Import Utility (IMP) on your Continuum-series module to

repopulate the database files for your ORACLE7 database.

Do not attempt to move an ORACLE database from an XA2000-series or XA/R-seriesmodule to a Continuum-series module except by using the EXP and IMP utilities. Attempting

to move the files directly from one module to another, rather than by means of the dump file

created by the EXP utility, will fail unless the full path names of the database files and the

module name itself on both modules are identical.

For information on using the IMP and EXP utilities, see the Oracle Corporation manual,

ORACLE7 Server Utilities User’s Guide (R3602-70-1292), and the Stratus manual,

ORACLE7 Administration and Tools Guide (R401).


31/122


Chapter 3:

Addressing Alignment Issues 3-

This chapter briefly explains shortmap and longmap data alignment, discusses how to specify

data alignment for entire source modules and for individual data elements, and addresses

important alignment issues.

Use the information in this chapter in any of the following circumstances:

• You are migrating an MC68000 application to the PA-RISC platform.

• You are migrating an i860 application to the PA-RISC platform and have not previously

recompiled it with longmap alignment rules. If you previously migrated the program

from the MC68000 platform by using shortmap alignment and correcting alignment

problems that had the most effect on performance, consider upgrading to longmap data

alignment now to take full advantage of the improved performance available with

PA-RISC.

• You are revising an application and need a summary of data alignment issues for the

new coding.

The following data alignment issues are addressed in the chapter.

• determining what data elements must remain shortmap-aligned

• understanding how alignment is handled when you define structures or structure

members as elements of other structures

• avoiding or correcting alignment problems when mixing longmap and shortmap

alignment in the same program and when passing arguments to subroutines

• ensuring correct alignment of based variables when using pointers in VOS PL/I.

• ensuring correct alignment when using untyped storage sharing

• ensuring correct alignment of aligned string data

• rearranging structure elements to minimize alignment padding when converting to

longmap alignment

• ensuring correct alignment when simulating, in VOS Standard C or VOS Pascal, the

VOS PL/I dec 15 or dec 18 data types for passing arguments to certain subroutines


32/122

Understanding Shortmap and Longmap Data Alignment

3-2 Chapter 3: Addressing Alignment Issues


The PA-RISC processor, like the i860 processor, requires more stringent data alignment than

the MC68000 family of processors for applications to run at their best performance. For a data

item to be correctly aligned, it must be aligned on a boundary congruent to its size, that is, it

must be longmap-aligned. The PA-RISC processor, like the i860 processor, allows misaligned

accesses, but at a performance cost. If the compiler detects misalignment, several additionalinstructions are generated per storage access. The resulting performance penalty is

significantly worse for floating-point data. If the compiler cannot detect the misalignment, the

VOS fault handler performs the access at a much greater performance penalty, generating

hundreds or sometimes thousands of additional instructions to handle the fault.

The compilers allow you to choose how data is aligned. The choices are as follows:

• longmap. Data items are aligned on boundaries congruent to their size. Two-byte items

are aligned on mod2 boundaries (that is, addresses divisible by 2), four-byte items on

mod4 boundaries (addresses divisible by 4), and so forth, up to mod8.

•

shortmap. The compilers generally align data elements two bytes or longer on two-byteboundaries. Shortmap alignment is the default for the compilers for compatibility with

existing programs, although your system administrator can change this setting, as

described in the manual VOS System Administration: Administering and Customizing

a System (R281).

Longmap and Shortmap Alignment Examples

Following are several examples showing longmap and shortmap data alignment. The first and

second examples show the same VOS PL/I structure declared as longmap and shortmap. The

third example shows the longmap structure with its elements rearranged to eliminate the need

for padding. The use of the alignment specifiers for longmap and shortmap are described in

subsequent sections. See ‘‘Rearranging Structure Elements to Minimize Alignment Padding”

later in this chapter for more information on reducing or eliminating padding in longmap

structures.

Example

The following example shows a structure aligned as longmap.

declare 1 longmapped_struct longmap,

2 model fixed bin (15),

2 value float dec (8),

2 size fixed bin (31);

The structure itself is aligned on a mod8 boundary because longmapped structures must begin

on a boundary congruent to the size of the largest element (up to mod8). The size of the entirestructure is 20 bytes, and 6 bytes of padding are introduced between

longmapped_struct.model and longmapped_struct.value.


33/122



The members are stored as follows:

Example

The following example shows the same VOS PL/I structure shown in the first example, but

with the alignment declared as shortmap.

declare 1 shortmapped_struct shortmap,

2 model fixed bin (15),


2 size fixed bin (31);

The structure itself is aligned on a mod2 boundary. The size of the entire structure is 14 bytes.


Example

The following example shows the same VOS PL/I longmap structure shown in the first

example, but with the structure members rearranged to eliminate the padding.

declare 1 longmapped_struct longmap,


2 size fixed bin (31),

2 model fixed bin (15);

The structure itself is aligned on a mod8 boundary. The size of the entire structure is 14 bytes,

and no padding is introduced.

Variable Alignment Offset Size

model mod2 0 bytes 2 bytes

value mod8 8 bytes 8 bytes

size mod4 16 bytes 4 bytes






34/122

Specifying Data Alignment



Language-Specific Alignment Differences

The way data items are aligned and composite data elements such as structures are padded is

the same for all supported VOS programming languages, except for VOS Standard C. In VOS

PL/I, for example, longmapped structures must only begin on a boundary congruent to the

size of the largest element (up to mod8). In VOS Standard C, the structure must begin and

end on such a boundary. The compiler adds padding to the end of the structure to accomplish

this. For example, in VOS Standard C the following longmapped structure, equivalent to the

VOS PL/I structure shown in the preceding examples, would have a size of 24, not 20, bytes.

struct $longmap longmapped_struct

{

short int type;

double value;

long int size;

};

The offsets of the individual elements would be the same as shown for the VOS PL/I example

in the preceding section. However, there would be an additional 4-byte pad at the end of the

structure.

For more information on data elements, their sizes, and alignment issues, see the user’s guide

for the VOS programming language you are using.


You can specify longmap or shortmap data alignment in any of the following ways.

• Use the -mapping_rules compiler argument to specify the alignment for an entire

source module.

• Use compiler directives (or, in VOS COBOL, language statements) to specify the

alignment for an entire source module. A compiler directive or language statementoverrides the -mapping_rules argument.

• Use the longmap and shortmap attributes (or, in VOS Standard C, $longmap and

$shortmap) to specify in the source module the alignment for individual data

elements. Using these attributes to specify alignment for individual elements overrides,

for those elements, any alignment specified for the entire source module.






35/122



Using the -mapping_rules Argument

Each compiler command has the argument -mapping_rules alignment that you use to

specify whether the source code is to be compiled using longmap or shortmap data alignment

rules.

The possible values for alignment are default, default/check, shortmap,

shortmap/check, longmap, and longmap/check. When VOS is installed on your

module, the values for default and default/check are set to the same as shortmap and

shortmap/check, but the value is site-settable by your system administrator. To determine

if your system administrator has changed the settings for default and default/check on

the current module, give the display_error command, as follows:

display_error m$default_mapping

The command displays a message code number followed by the default setting on the current

module. For example, if the settings of default and default/check are the same as

shortmap and shortmap/check, the command has the following output.

4991. shortmap

For VOS Standard C, VOS COBOL, VOS Pascal, VOS PL/I, or VOS FORTRAN, if you

specify one of the alignment/check values, the compiler issues messages when it inserts

padding in an aggregate to satisfy alignment requirements. For example, if you compile a

VOS Standard C program containing the structure shown in ‘‘Language-Specific Alignment

Differences” earlier in this chapter, and you specify -mapping_rules longmap/check,

the compiler issues the following messages:

2096 8: A gap of 6 bytes has been found between "value" and the

previous member within "struct(longmapped_struct)"

structure.

2010 8: Extra "4" bytes have been allocated forstruct(longmapped_struct) due to alignment requirements.

Note that if you specify a compiler directive (or, in VOS COBOL, the object-computer

paragraph), only the specified alignment attribute is overridden, not the checking for

alignment padding. See the next section, ‘‘Using Compiler Directives,” for more information.

Using Compiler Directives

Each language has a compiler directive or, in VOS COBOL, a language statement, that you

can use in a source module to specify the alignment rules to apply to the compilation of that

source module.

In VOS Standard C, the syntax is:

#pragma longmap;


36/122



In VOS COBOL, the syntax is:

environment division.

configuration section.

object-computer.stratus

using longmap.

In VOS Pascal, the syntax is:

%options longmap

In VOS PL/I, the syntax is:

%options longmap;

In VOS FORTRAN, the syntax is:

%options longmap

VOS PL/I and VOS Standard C each have a compiler directive that causes the compiler towarn you about every structure that has not been explicitly declared as shortmap or longmap.

In VOS PL/I, the compiler directive is %options no_default_mapping, and in VOS

Standard C, the compiler directive is #pragma no_default_mapping. You can use this

directive to make sure you have examined all structures in a program.

Using Shortmap and Longmap Attributes

You can specify the shortmap/longmap attributes for aggregate data types in any VOS

programming language, but for scalar data types only in VOS Standard C and VOS PL/I.

For each VOS programming language supported on Continuum-series modules, this section

gives usage rules and examples of the shortmap/longmap attributes.

VOS Standard C Usage

You can indicate the alignment rules for a particular object or function return type by

specifying the $shortmap or$longmap attribute in the declaration of the object or function.

With two exceptions, the $shortmap and $longmap attributes follow the same syntax rules

that apply to the const and volatile type qualifiers. The two exceptions are as follows:

• In the declaration of a function type, the alignment attribute applies to the function’s

return type and not to the function itself.

• In the declaration of a structure, union, or enumeration tag, the alignment attribute

applies to the tag. In declarations that specify the tagged type for a structure, union, or

enumeration object, the object inherits the alignment rules associated with the tag.

With a structure, union, or enumerated type, specify the $shortmap or $longmap attribute

after the struct, union, or enum keyword and before the tag, if one exists, in the

declaration. It is invalid to specify an alignment attribute other than after the type keyword

and before the tag.


37/122



The following examples illustrate correct and incorrect usage of the $longmap attribute in

the declaration of a union tag and union object.

union $longmap u_type1

{

.

.

.

} union1;

union u_type1 union2; /* union2 inherits longmap alignment from tag */

union $shortmap u_type1 union3; /* INVALID: alignment associated */

/* with a tag cannot be changed */

Once the u_type1 tag is declared, all subsequent union declarations that use the u_type1

tag are aligned according to longmap rules. Thus, union3 cannot be redefined as shortmap.

To indicate the alignment rules for a function return type or an object other than a structure,

union, or enumeration, specify the $shortmap or $longmap attribute anywhere before thedeclarator.

With a pointer type, an alignment specifier can be within the declarator. When you use an

alignment specifier with a pointer type, the syntax and semantics are similar to those used for

type qualifiers. The following examples illustrate how to use the $shortmap specifier in the

declaration of a pointer type.

int $shortmap *i_ptr; /* Example 1 */

int * $shortmap i_ptr1; /* Example 2 */

In Example 1, i_ptr is declared to be a pointer to an int. The int, not the pointer, is aligned

using the shortmap alignment rules. In Example 2, i_ptr1 is also declared to be a pointer toan int. However, in this case, the pointer, not the int, is aligned using the shortmap

alignment rules.

You cannot specify the $shortmap or $longmap attribute in a typedef unless it is a type

definition for a structure, union, or enumeration type, and the contents of struct, union, or

enum are defined within the type definition. For example, the following is invalid:

typedef SM_LONG_INT $shortmap long int; /* INVALID */

If you specify an alignment attribute for a bit field or a function that returns void, the

compiler ignores the attribute.

For more information and examples on specifying data alignment in VOS Standard C, see the

VOS Standard C Reference Manual (R363).


38/122



VOS COBOL Usage

In VOS COBOL, you can specify the longmap or shortmap attribute for a record with the

using longmap or using shortmap clause. For example:

data division.

working-storage section.

01 record1 using longmap.

02 x usage is comp-4.

02 y usage is comp-2.

02 z usage is comp-5.

For more information and examples on specifying data alignment in VOS COBOL, see the

VOS COBOL Language Manual (R010).

VOS Pascal Usage

In VOS Pascal, you can specify the longmap or shortmap attributes for any array, record,

set, or file.

For example, the following shows a record declared with the longmap attribute.

type a_record_type = longmap record

fieldone: integer;

fieldtwo: real;

end;

For more information and examples on specifying data alignment in VOS Pascal, see the VOS

Pascal Language Manual (R014).

VOS PL/I Usage

To specify the alignment for a particular data item in VOS PL/I, you can use the longmap or

shortmap attribute. If either attribute is specified for a structure, then all members for which

neither attribute is specified inherit that attribute. The following examp

migrating vos applications to continuum (r407-00)

Documents