Migrating VOS Applications To Continuum (r407-00)

R407-00
Migrating VOS Applications to Continuum Systems
Stratus Computer, Inc.
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.
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 are
migrating 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.
Migrating VOS Applications to Continuum Systems (R407)
iii
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 available
with 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 a
record 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.
iv
Preface
Preface
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 Functions

VOS 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 <SHIFT> and <F22> keys simultaneously to perform the
INTERRUPT function; on a V103 terminal, you press the <Shift> and <F20> keys simultaneously
to 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.
V101
V102
V103
ASCII
V103
EPC
IBM or IBMCompatible PC
CANCEL
<F17>
<F20>
<F18>
CYCLE
<F16>
<F19>
<F17>
<F12>
<Alt>-<C>
<SHIFT>-<F16>
<F16>
<Shift>-<F17>
<Shift>-<F12>
<Alt>-<B>
<F18>
<F21>
<F19>
HELP
<SHIFT>-<F8>
<SHIFT>-<F8>
<Shift>-<F8>
<Shift>-<F2>
<Shift>-<F2>
INSERT DEFAULT
<SHIFT>-<F11>
<SHIFT>-<F11>
<Shift>-<F11>
<Shift>-<F10>
<Shift>-<F10>
<F11>
<F11>
<F11>
<F10>
<F10>
INTERRUPT
<CTRL>-<F0>
<SHIFT>-<F22>
<Shift>-<F20>
<Shift>-<Delete>
<Alt>-<I>
NO PAUSE
<SHIFT>-<F17>
<F17>
<Shift>-<F18>
<Shift>-*
<Alt>-<P>
VOS Function
CYCLE BACK
DISPLAY FORM
INSERT SAVED
Keypad character
Preface
Related Manuals
Refer to the following Stratus manuals for related documentation.
VOS Commands Reference Manual (R098)

VOS Standard C Users Guide (R364)
VOS PL/I Language Manual (R009)
VOS Subroutines manuals
VOS 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 Documentation
You can find additional information by viewing the systems 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 Manual

You 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
vi
Preface
Preface
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 <Enter> or <Return>, and
complete the data-entry form that appears on your screen. When you have completed
the form, press <Enter>.
If your comments are lengthy, save them in a file before you issue the command. Type
comment_on_manual followed by -form, then press <Enter> or <Return>. Enter this
manuals 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 <Enter>.
Note: If comment_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.
vii
Preface
viii
Preface
Contents
1. Continuum Features Affecting Application Migration

Data Alignment Rules. . . . . . . . . . . . .
Number of Registers . . . . . . . . . . . . .
Memory on Each CPU/Memory Board . . . . . .
The Virtually Indexed Cache . . . . . . . . . .
Increased Paging Space Requirements . . . . . .
The Machine-Independent Locking Mechanism . .
Process and Command Memory Limits . . . . . .
Time-of-Day Clock. . . . . . . . . . . . . .
ORACLE7 Support. . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1-1
1-1
1-2
1-3
1-3
1-3
1-4
1-4
1-5
1-5
2. Migrating Applications: a Step-by-Step Summary . . . . . . . . . . . . . . . . . .

Preparing to Migrate Your Applications . . . . . . . . . . . . . . . . . . . . .
Setting Up Your Environment . . . . . . . . . . . . . . . . . . . . . . .
Assuring Adequate Paging Space . . . . . . . . . . . . . . . . . . .
Checking the Default Mapping Rules Value . . . . . . . . . . . . . . .
Checking and Setting Process Command Limits . . . . . . . . . . . . .
Deciding on a Data Alignment Strategy . . . . . . . . . . . . . . . . . . .
Choosing between Longmap and Shortmap for Migrating MC68000 Applications
Choosing between Longmap and Shortmap for Migrating i860 Applications . .
Choosing Features Newly Available with Continuum-Series Modules . . . . . . .
Revising Your Source Modules . . . . . . . . . . . . . . . . . . . . . . . . .
Correcting Incorrect or Inefficient Coding . . . . . . . . . . . . . . . . . .
Revising Code to Implement New Features . . . . . . . . . . . . . . . . . .
Compiling and Binding Applications for Continuum-Series Modules . . . . . . . . . .
Migrating ORACLE Databases to Continuum-Series Modules . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-1
2-1
2-1
2-1
2-2
2-3
2-3
2-4
2-4
2-5
2-5
2-6
2-6
2-7
2-9
3. Addressing Alignment Issues. . . . . . . . . . . .

Understanding Shortmap and Longmap Data Alignment
Longmap and Shortmap Alignment Examples . .
Language-Specific Alignment Differences . . .
Specifying Data Alignment . . . . . . . . . . .
Using the -mapping_rules Argument . . . .
Using Compiler Directives . . . . . . . . .
Using Shortmap and Longmap Attributes . . .
VOS Standard C Usage . . . . . . . .
VOS COBOL Usage . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
3-1
3-2
3-2
3-4
3-4
3-5
3-5
3-6
3-6
3-8
ix
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
VOS Pascal Usage . . . . . . . . . . . . . . . . . . . . . . . .

VOS PL/I Usage . . . . . . . . . . . . . . . . . . . . . . . . .
VOS FORTRAN Usage . . . . . . . . . . . . . . . . . . . . . .
Determining What Must Be Shortmap-Aligned . . . . . . . . . . . . . . . . . .
Checking Structures Passed to Operating System Subroutines . . . . . . . . .
Retaining Shortmap Alignment for Pre-Defined Data Structures . . . . . . . .
Correctly Aligning Structures in Communications-Based Applications . . . . . .
Handling Mixed Shortmap and Longmap Data . . . . . . . . . . . . . . . . . .
Understanding Alignment Inheritance among Structures and Structure Elements . .
VOS Standard C and VOS Pascal Usage . . . . . . . . . . . . . . .
VOS PL/I Usage . . . . . . . . . . . . . . . . . . . . . . . . .
Using the like Attribute . . . . . . . . . . . . . . . . . . .
Using the type Attribute . . . . . . . . . . . . . . . . . . .
Correcting Alignment Mismatches in Subroutine Arguments . . . . . . . . . .
Ensuring Alignment Compatibility Between Arguments and Parameters . . . . .
Avoiding Common Alignment Errors in VOS PL/I . . . . . . . . . . . . . . . .
Ensuring Compatible Alignment of Based Storage Locations Referenced by Pointers
Ensuring Correct Alignment of String Data . . . . . . . . . . . . . . . . .
Ensuring Correct Alignment in Untyped Storage Sharing . . . . . . . . . . .
Rearranging Structure Elements to Minimize Alignment Padding . . . . . . . . . .
Correctly Aligning Simulations of dec 15 and dec 18 Data Types . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3-8
3-8
3-9
3-9
3-9
3-10
3-10
3-11
3-11
3-11
3-12
3-12
3-13
3-14
3-15
3-16
3-16
3-17
3-18
3-18
3-19
4. Correcting Programs to Work with a Large Register Set . . . . . . . . . . . . . .

Ensuring That Shared Data is Referenced Consistently . . . . . . . . . . . . . . .
Ensuring That Programs Access the Current Copy of Shared Data . . . . . . . .
Using the volatile Attribute to Inform the Compiler that Data Is Shared . .
Restricting Your Programming to Ensure that Programs Access Current Data .
Ensuring That Only One Program at a Time Updates Shared Data . . . . .
Compiling with the -table or -production_table Argument . . . . . . . .
Modifying VOS Standard C setjmp and longjmp Function Calls . . . . . . . . . .
Using the VOS PL/I defined Storage Class. . . . . . . . . . . . . . . . . . .
Using Alternatives to Defined Overlays . . . . . . . . . . . . . . . . . .
Using Alternatives to Defined Pointers . . . . . . . . . . . . . . . .
Using Untyped Storage Sharing . . . . . . . . . . . . . . . . . . .
Modifying Routines That Directly Access the Stack . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-1
4-1
4-2
4-2
4-3
4-4
4-5
4-6
4-7
4-7
4-8
4-8
4-8
5. Correcting Coding Practices That Jeopardize Portability . .

Working with Highly Optimized Code . . . . . . . . .
Recoding Loops the Compiler Might Eliminate. . . . . .
Revising Code That Depends on Unreferenced Variables . .
Revising Code for Compatibility of Floating-Point Precision
Handling and Debugging Floating-Point Exceptions . . . .
Checking for Uninitialized Variables . . . . . . . . . .
Checking Function Calls to and from VOS FORTRAN . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5-1
5-1
5-2
5-2
5-2
5-3
5-3
5-4
Contents
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents
6. Improving Memory Access by Specifying Memory Pools . . . . . . . . . . . .

Memory Access on a Continuum-Series Module . . . . . . . . . . . . . . .
Controlling Which Memory Pool a Process Uses . . . . . . . . . . . . . . .
Revising s$start_process Calls to s$start_new_process Calls . . . .
Evaluating s$clone Subroutine Calls . . . . . . . . . . . . . . . . .
Specifying Memory Pool Assignment in Command Macros . . . . . . . .
Getting Information on Memory Pool Assignment . . . . . . . . . . . . . .
Using the s$get_process_info and s$get_processes_info Subroutines
Using the list_users Command . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
6-1
6-1
6-2
6-2
6-3
6-3
6-4
6-4
6-4
7. Efficiently Using Continuum-Series Caches . . . . . . . . . . . . . .

Improving Performance with Caches . . . . . . . . . . . . . . . . .
Determining Cache Line Boundaries . . . . . . . . . . . . . .
Minimizing Data Sharing Among Processors . . . . . . . . . . .
Fully Utilizing Each Cache Line . . . . . . . . . . . . . . . .
Avoiding Problems with the Instruction Cache . . . . . . . . . .
Understanding Memory-Ordering, Caching Policies, and Locking . . . . .
Caching Policies that Support Memory-Ordering . . . . . . . . .
Exclusive Non-Sequential and Shared Non-Sequential Caching Policies
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7-1
7-1
7-2
7-3
7-4
7-5
7-5
7-5
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 . . . . . .
Understanding Program Address Space Changes . . . . . . . . .
Limiting Virtual Memory Allocation for a Program or Command . .
Additional bind Command Arguments for Managing Address Space .
Bind Directives for Creating a Shared Virtual Memory Database . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
9-1
9-1
9-3
9-5
9-5
10. Upgrading to the Microjiffy Time-of-Day Clock . . . . . . . . . . . . . . . . . .

The Time-of-Day Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Interfaces to the Time-of-Day Clock . . . . . . . . . . . . . . . . . . .
10-1
10-1
10-1
11. Troubleshooting . . . . . . . . . . . . . . . . . . . . . .
Diagnosing and Correcting Paging Space Problems . . . . . . . .
Avoiding Inefficient Cache Usage . . . . . . . . . . . . . . .
Checking for Alignment Faults Causing Uneven Performance . . . .
Correcting Problems Related to Process and Program Limits . . . .
Setting Limits Too High . . . . . . . . . . . . . . . .
Setting Limits Too Low . . . . . . . . . . . . . . . .
Setting Inconsistent Limits . . . . . . . . . . . . . . .
Running Programs on Modules with Insufficient Default Limits.
11-1
11-1
11-3
11-3
11-4
11-4
11-4
11-5
11-5
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xi
Contents
Appendix A. Migrating Forms Management System (FMS) Applications

Choosing the Appropriate Forms Editor. . . . . . . . . . . . .
Editing and Recompiling FMS Files . . . . . . . . . . . . . .
Using the Form Options Form . . . . . . . . . . . . .
Using a Command Macro to Edit the Forms . . . . . . . .
Binding Applications Compiled with nls_edit_form . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
A-1
A-1
A-1
A-2
A-3
A-4
Appendix B. Finding and Correcting Runtime Alignment Faults . . . . . . . . . .

Using the set_alignment_fault_mode Command . . . . . . . . . . . . .
Using the profile Command . . . . . . . . . . . . . . . . . . . . . .
Using the VOS System Analysis Subsystem . . . . . . . . . . . . . . . . .
Logging Alignment Fault Information . . . . . . . . . . . . . . . . .
Displaying Alignment Fault Information . . . . . . . . . . . . . . . .
Determining Which Program to Analyze . . . . . . . . . . . . . . . .
Using analyze_system from the Same Process That Ran the Program .
Using analyze_system from a Process That Did Not Run the Program
Analyzing a Non-Running Program . . . . . . . . . . . . . . . . . .
Examining Assembly Language Code . . . . . . . . . . . . . . . . .
Using Information in the .list File . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. B-1
. B-2
. B-3
. B-4
. B-5
. B-6
. B-7
. B-7
. B-8
. B-9
. B-10
. B-11
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1
xii
Contents
Figures
Figure 9-1. Program Address Space on Continuum-Series Modules . . . . . . . . . . . . .
9-2
xiii
Tables
Table 7-1. Cache Sizes on Continuum-Series Models . . . . . . . . . . . . . . . . . . .
Table 8-1. Additional Access Modes for Connecting a Processs Virtual Memory to a File . . . .
xiv
Tables
7-2
8-2
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 Stratus
modules
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
1-1
Number of Registers
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 addressing
misalignments 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 variables 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 been
flushed 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.
1-2
Chapter 1: Continuum Features Affecting Application Migration
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
processors large register set.
Memory on Each CPU/Memory Board

On Continuum-series modules, physical memory resides on each CPU/memory board rather
than 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 the
subroutines 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 Using
Continuum-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 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.
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
1-3
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 rather
than 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.
1-4
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 platforms
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.
1-5
ORACLE7 Support
1-6
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 large
applications 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.
2-1
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 a
value 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 <Return>.
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
2-2
Chapter 2: Migrating Applications: a Step-by-Step Summary
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 a
Continuum-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 processs total heap space, and 134,217,728 bytes (128 MB) for
a processs 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 to
be 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 programs 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.
2-3
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 Applications
Use 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, your
decision 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 data
alignment 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
2-4
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 causing
alignment-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 processs 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 and
provide 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.
2-5
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 is
relevant 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 of
the 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
2-6
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. See
Chapter 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 subroutines
s$set_current_cmd_limit and s$get_current_cmd_limit in your applications
source modules, and the command update_process_cmd_limits in your applications
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 applications calls to the subroutines
s$int_date_time and s$jiffy_date_time with calls to s$clock_date_time. Also
replace 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.
2-7
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 future
recompilations, 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. The
result 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 10
and 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.
2-8
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
applications 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
programs 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.

Although 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:
2-9
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-series
module 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 Users Guide (R3602-70-1292), and the Stratus manual,
ORACLE7 Administration and Tools Guide (R401).
2-10
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
3-1

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 additional
instructions 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-byte
boundaries. 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 entire
structure is 20 bytes, and 6 bytes of padding are introduced between
longmapped_struct.model and longmapped_struct.value.
3-2
Chapter 3: Addressing Alignment Issues
The members are stored as follows:

Variable
Alignment
Offset
Size
model
mod2
0 bytes
2 bytes
value
mod8
8 bytes
8 bytes
size
mod4
16 bytes
4 bytes
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,
The structure itself is aligned on a mod2 boundary. The size of the entire structure is 14 bytes.
Variable
Alignment
Offset
Size
model
mod2
0 bytes
2 bytes
value
mod2
2 bytes
8 bytes
size
mod2
10 bytes
4 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.
3-3
Specifying Data Alignment

Variable
Alignment
Offset
Size
value
mod8
0 bytes
8 bytes
size
mod4
8 bytes
4 bytes
model
mod2
12 bytes
2 bytes
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 users 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 statement
overrides 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.
3-4
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 for
struct(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;
3-5
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 to
warn 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 functions
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.
3-6
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 the
declarator.
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;
int * $shortmap i_ptr1;
/*
/*
Example 1
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 to
an 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).
3-7
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
02
x
02
y
02
z
using
usage
usage
usage
longmap.
is comp-4.
is comp-2.
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 example illustrates a simple
use of the longmap attribute.
declare 1 struct longmap,
The structure itself is aligned on a mod8 boundary. The size of the entire structure is 20 bytes,
and 6 bytes of padding are introduced between struct.model and struct.value.
For more information and examples on specifying data alignment in VOS PL/I, see the VOS
PL/I Language Manual (R009)
3-8
Determining What Must Be Shortmap-Aligned
VOS FORTRAN Usage

To specify the alignment of a structure in VOS FORTRAN, use the (shortmap) or
(longmap) attribute. The following example illustrates a simple use of the (longmap)
attribute:
common
1
2
3
/ struct(longmap) /
model,
value,
size

Ideally, everything that can be longmap-aligned should be longmap-aligned for a program to
perform at its best in all environments. However, some things must remain shortmap-aligned
for the following reasons.
Programs running on Continuum-series modules must interchange data with other

systems and applications, some of which may use data in a format that cannot be
changed.
The operating system subroutines must remain compatible with existing applications,
and thus must accept shortmapped structures.
Many of the user-interface structures of communications-based applications require

shortmap alignment for data compatibility.
If you specify longmap alignment when recompiling your source modules, you must first
ensure that the following structures or records remain shortmap-aligned.
structures that contain elements longer than two bytes and are passed to operating
system subroutines
structures or records that are already defined as shortmap externally to the program,
such as structures that overlay existing shortmap-aligned database records
many of the user-interface structures in communications-based applications, as

indicated in the manuals for those VOS communications software products
There may also be uncommon instances where other data should follow shortmap alignment
rules, such as frequently recurring arrays of very small structures where the padding would
be excessive with longmap alignment.
Checking Structures Passed to Operating System Subroutines

To remain compatible with existing programs, all system subroutines (s$ calls) accept
structures whose elements are aligned according to shortmap alignment rules. When you
compile a program and specify longmap alignment rules, any structure argument containing
data elements longer than two bytes must be shortmapped so that the compiler does not add
padding to the structure. The performance impact of specifying that these structures remain
shortmapped is minimal because the subroutine copies the shortmapped elements to
longmap-aligned variables.
3-9
With VOS Standard C, VOS COBOL, VOS Pascal, VOS PL/I, or VOS FORTRAN, one way
to determine whether a structure needs to be shortmapped is to compile the program with the
value longmap/check for the -mapping_rules argument. When you specify
longmap/check, the compiler warns you when it adds padding to any structures. If the
structures for which warnings are issued are being passed to system subroutines, declare the
structures to follow shortmap alignment rules.
Optionally, you can specify the shortmap attribute for all system subroutine structures. For
system subroutine structures for which padding would not be added under longmap alignment
rules, adding the shortmap attribute has no effect.
In VOS Release 11.0 and later releases, the VOS Subroutines manuals show which subroutine
structures must remain shortmapped, and the include files in >system>include_library
have been updated to use shortmap alignment where required.
The requirement for shortmap alignment applies only to subroutine structure arguments.
The operating system subroutines take several types of scalar argument, and these can be
longmap- or shortmap-aligned, depending on the alignment rules you are using to compile
your program. Chapter 1 of each of the VOS Subroutines manuals provides tables listing the
scalar data types that occur as system subroutine arguments and showing the alignment and
amount of storage space the compiler allocates for longmap and for shortmap alignment of
each of those data types.
Retaining Shortmap Alignment for Pre-Defined Data Structures

If you are using a structure that corresponds to records whose format cannot be changed,
specify shortmap alignment for the structure. For example, suppose you have a large file that
contains disk records corresponding to the following VOS PL/I structure:
declare 1 record
2 name
2 idnum
,
char(22),
fixed bin(31);
Each disk record is 26 bytes long: 22 bytes for the name and 4 bytes for the ID number.
However, if you compile the program with longmap alignment rules, the compiler inserts a
2-byte pad before the idnum field to align it on a mod4 boundary. You can no longer read and
write this structure by overlaying it with a char(26) buffer because the structure no longer
corresponds to the record format on disk. Therefore, you must specify shortmap for this
structure.
Correctly Aligning Structures in Communications-Based Applications

User-interface structures in many communications-based applications must be shortmap
aligned. For any VOS communications software product, always check the latest revision of
the products manual for information on any product changes and on how to declare any of
its structures. The Software Release Bulletin for the current VOS Release gives the latest
revision numbers for all VOS manuals.
Also see the directory >system>include_library for include files for some VOS
communications software products. Where an include file exists for the structures you need
in your application, use the include file rather than typing the structure declarations into your
source module. For communications-based as well as non-communications-based products,
3-10
Handling Mixed Shortmap and Longmap Data
using the include files supplied by Stratus ensures that your application always has the latest
updates to structures.

When you mix shortmap and longmap elements in the same program, the following
circumstances may require special attention.
controlling alignment inheritance when specifying a containing structure and a

substructure that have different data alignment or when declaring a structure that is to
take the attributes of another structure
passing shortmapped data elements to subroutines that expect longmapped parameters

in VOS PL/I, passing arguments to parameters when the argument and parameter
alignment does not match
Understanding Alignment Inheritance among Structures and Structure Elements

This section provides information and examples on how alignment inheritance is handled in
VOS Standard C and VOS Pascal when you define structures or structure members as
elements of other structures, and in VOS PL/I when you use the like or type attributes in a
structure declaration.
VOS Standard C and VOS Pascal Usage
In this description, the VOS Standard C term structure also applies to a record (the
corresponding term in VOS Pascal).
In VOS Standard C or VOS Pascal, you can define a structure and then use a data item of that
structure type as an element of another structure. If you define a longmapped structure, that
structure is always aligned as longmap, even if included as part of a shortmapped structure.
Similarly, if you define a shortmapped structure, it remains shortmapped, even if included as
part of a longmapped structure.
Example
In VOS Standard C, suppose you define the following structure to follow longmap alignment
rules:
struct $longmap struct_1
{
unsigned short a;
unsigned long b;
unsigned short c;
};
3-11
You can define another structure that includes an element of type struct struct_1:
struct $shortmap struct_2
{
unsigned short one;
unsigned long two;
struct struct_1 three;
};
The containing structure is defined as $shortmap, so no error or padding occurs for element
two, a 32-bit variable defined on a mod2 boundary. However, the compiler inserts two bytes
of padding before element three because struct_1 is defined as a longmap structure. A
longmap structure must start on a mod4 boundary, since a structure is aligned on the boundary
determined by the member with the most stringent boundary requirement, in this case a long
int. A structure defined as longmap always is aligned as longmap, even if used in a structure
defined as shortmap, and the longmapped structure remains longmap-aligned internally. In
this example, element b is located on a mod4 boundary, with two bytes of padding before it.
Example
If you define a structure to follow shortmap alignment rules and then include it as part of a
structure defined as longmap, the shortmapped structure remains shortmap-aligned.
struct $shortmap struct_1
{
unsigned short a;
unsigned long b;
unsigned short c;
};
struct $longmap struct_2
{
unsigned short one;
unsigned long two;
struct struct_1 three;
};
In this example, element three remains shortmapped. Element b, for example, remains at an
offset of two from the beginning of the struct_1 structure. The structure three itself is
located at a mod2 offset, since the alignment requirement of a structure is determined by the
maximum alignment of any element, in this case mod2 because the structure is shortmapped.
Internally, element three remains shortmapped, and no padding is inserted before three.b,
which remains mod2- aligned.
VOS PL/I Usage
In VOS PL/I, by using the like or the type attribute, you can explicitly mix structure
elements with different data alignment or have the alignment of one data structure or element
inherit the alignment of another. The following rules and restrictions apply.
Using the like Attribute
You can define a structure template and then define other data elements (including
substructures) based on that template using the like attribute. If you define a template and
3-12
include an alignment attribute as part of that template, the specified alignment is maintained
unless you explicitly override it for the element declared using like. This behavior is
non-standard for PL/I.
The following example illustrates how alignment attributes work with like.
%options longmap;
declare 1 struct1 shortmap based,
2
a
fixed bin(15),
2
b
fixed bin(31);
declare 1 struct2,
2
one
fixed bin(15),
2
two
like struct1; /* two remains shortmapped */
declare 1 struct3 longmap,
2
one
fixed bin(15),
2
two
like struct1; /* two remains shortmapped */
declare 1 struct4,
2
one
fixed bin(15),
2
two
like struct1 longmap; /* two becomes longmap */
In this example, the data elements are aligned as follows:
The substructure two remains shortmapped in both struct2 and struct3 because
the alignment for that substructure is not explicitly overridden.
The longmap specification of struct3 does not override the internal alignment in the
substructure two, which remains shortmapped.
For struct4, the alignment for the substructure two is explicitly declared as
longmap, so the compiler adds two bytes of padding before substructure two and adds
two bytes of padding after element a within substructure two.
In mixing shortmap and longmap data alignment in VOS PL/I, also be aware that the size as
well as the alignment of structure members may change when you change the alignment
specification of the member you declare using like. For example, the size of bit(16)
aligned data is 2 bytes when declared as shortmap, but 4 bytes when declared as longmap.
For more information, see the tables showing alignment and size for VOS PL/I data types
with longmap and with shortmap alignment in the chapter Data Types in the VOS PL/I
Language Manual (R009).
Using the type Attribute
VOS PL/I also provides a type attribute that enables you to declare a user-defined data type
by referencing the type of another structure or member. A structure or member declared with
the type attribute inherits the size and most of the attributes of the referenced structure or
member, including the shortmap or longmap attribute. Only the internal, external,
builtin, automatic, static, based, and defined attributes are not inherited. In the
3-13
following example, struct2 inherits the shortmap alignment of test_struct, even if you
compile the source module using longmap alignment rules.
declare 1 test_struct shortmap based,
2 a
fixed bin(15),
2 b
char(30);
declare struct2
type (test_struct);
If you declare a typed structure or member with an alignment attribute different from the
referenced variable, the alignment attribute declared for the typed structure or member
overrides the one declared for the referenced structure or member, and the compiler issues a
warning. In the following example, the longmap attribute specified for the typed structure
struct2 overrides the shortmap attribute of the referenced structure test_struct.
declare 1 test_struct shortmap based,
2 a
fixed bin(15),
2 b
char(30);
declare struct2
type (test_struct) longmap;
The compiler issues the following message, indicating the mismatch and informing you that
it is using the specified longmap attribute for struct2.
ERROR 2664 SEVERITY 2 BEGINNING ON LINE n
The explicitly specified mapping attributes of struct2 and
the type reference symbol do not match.
(Using the newly specified attribute.)
Correcting Alignment Mismatches in Subroutine Arguments

In VOS Standard C or VOS PL/I, if you pass a shortmapped data element to a subroutine that
is expecting a longmapped element, the compiler warns you if there is a possibility of an
alignment violation. This alignment mismatch can occur, for example, when you are passing
an element of a shortmapped structure to a subroutine in a program that is compiled with
longmap rules. You can correct the problem by assigning the data element to a temporary
variable, or, in VOS PL/I, by handling the argument value as an expression if the argument is
being used strictly as an input parameter.
If compiled with longmap rules, the following VOS PL/I program passes a shortmapped data
element as an argument to a subroutine that is expecting a longmapped data element.
declare
declare
my routine
entry (fixed bin(31));
1 my_struct shortmap,
2a
fixed bin(15),
2b
fixed bin(31);
call my_routine(my_struct.b);
3-14
Because the argument and the corresponding parameter are not compatibly aligned, the
compiler generates the following warning, indicating that the argument is being passed by
value, not by reference.
WARNING 94 SEVERITY 1 BEGINNING ON LINE line_number
"b" has been passed by-value because its
attributes did not match those of the corresponding parameter.
Enclose the argument in parentheses to suppress this warning.
If the parameter is being used strictly as an input parameter, enclose the argument in
parentheses to eliminate the warning message. When enclosed in parentheses, the argument
is treated as an expression, which is always passed by value.
call my_routine((my_struct.b));
If the parameter is to return a value, eliminate the warning message by declaring a temporary
variable and assigning my_struct.b to it before calling my_routine:
declare
temp
fixed bin(31);
temp = my_struct.b;
call my_routine(temp);
my_struct.b = temp;
The program now compiles with no warning messages and no alignment violations.
See the discussion of parameters and arguments in Chapter 3, Procedures and Blocks, in
the VOS PL/I Language Manual (R009) for more information
Ensuring Alignment Compatibility Between Arguments and Parameters

In VOS PL/I, you can pass an argument to a parameter in the following cases even if the
alignment of the argument and parameter is mismatched.
An argument aligned using longmap rules can be passed to a parameter aligned using
shortmap rules, if both the argument and the parameter are nonstructure data types and
not arrays of aligned strings, or if both the argument and the parameter are structure
data types of the same size and shape.
An argument aligned using shortmap rules can be passed to a parameter that is aligned
using longmap rules without generating a compiler warning if the data type of both the
argument and the parameter is fixed bin(15), bit (an unaligned bit string only),
char (an unaligned character string only), or char varying.
3-15
Avoiding Common Alignment Errors in VOS PL/I
The following example shows an attempt to pass a structure as a argument when there is an
alignment mismatch.
main: procedure;
declare 1 struct1
shortmap,
2 s_1
fixed bin(15),
2 t_1
fixed bin(31);
.
.
.
call w(struct1);
w: procedure(struct2);
declare 1 struct2
longmap,
2 s_2
fixed bin(15),
2 t_2
fixed bin(31);
.
.
.
end w;
end main;
In the preceding example, struct2 is declared with the longmap attribute and is expected to
be on a mod4 boundary as required by its largest member; of its members, s_2 is expected to
be on a mod2 boundary and t_2 is expected to be on a mod4 boundary, so there are two bytes
of padding between s_2 and t_2. The two structures do not have the same data alignment
and therefore are not compatible, so the compiler issues a warning.
For more information on arguments and parameters, see Chapter 3, Procedures and Blocks,
in the VOS PL/I Language Manual (R009).

The following sections explain how to avoid common alignment errors in VOS PL/I when
using based storage locations referenced by pointers, aligning string data, and using untyped
storage sharing.
Ensuring Compatible Alignment of Based Storage Locations Referenced by Pointers

To reference storage, a VOS PL/I program needs the address of the storage location and a
data-type description of the storage. This information enables the program to locate and
interpret storage. You can use a pointer value, which is a storage address, together with a
based variable, which is a data type description, to reference storage. The locator qualifier
symbol (->) associates a pointer with a based variable. For example, if p is a pointer and y is
a based variable, the syntax for the locator qualifier symbol is as follows:
p -> y
You can assign an address of a storage location to a pointer by using the addr built-in
function or the allocate statement.
3-16
However, an alignment mismatch can cause the program to fail. If the declaration of the based
variable uses an alignment specification that does not match the alignment of the storage
address, the program compiles with errors. In the following example, the addr built-in
function returns the address of a variables storage and assigns that address to a pointer.
declare
declare
declare
p
pointer;
x(5) float bin(24) shortmap;
y
float bin(24) based longmap;
.
.
.
p = addr(x(k));
p -> y ...
In the preceding example, the addr built-in function returns the address of x(k) and assigns
it to the pointer p. The second assignment statement uses the locator qualifier symbol to
associate the pointer p with the based variable y. However, because the storage address
returned by addr is shortmap-aligned and the based variable y is longmap-aligned, the
program will not run correctly, although it may compile without error.
Ensuring Correct Alignment of String Data

In VOS PL/I, a string variable is declared with an extent in the range 0 to 32,767 as the
maximum length in bits (for bit strings) or in bytes (for characters strings) of values the
variable can hold. Except for character strings with the varying attribute, if a value of less
than the specified extent size is assigned to a string variable, the value is right-padded. If a
value of more than the specified extent size is assigned, the value is truncated on the right.
You can use the aligned attribute to force a string to be allocated on a particular storage
boundary that depends on whether shortmap or longmap alignment rules are in effect. Under
shortmap rules, the string is mod2-aligned and the storage allocation is a multiple of two
bytes. Under longmap rules, the string is mod4-aligned and the storage allocation is a multiple
of four bytes. Due to alignment padding added by using the aligned attribute, a bit-string
value of length n might occupy more than n bits, or a character-string value of length n might
occupy more than n bytes. Even though that larger storage allocation does not increase the
maximum size of values that can be stored in the variable or affect operations performed on
the variable, the attribute is considered part of the data type for purposes of sharing storage
or matching arguments with parameters. For example, in the case of a string overlay, the
sharing variables must be all nonvarying unaligned character strings or all unaligned bit
strings, since such strings contain no gaps or extraneous data.
The compiler issues advice if you attempt to reference a bit string contained in a structure that
is either based or a parameter and that contains only unaligned bit strings or unaligned
character strings. To avoid this advice, if the bit string is a structure member, insert a dummy
variable with the attributes char(0) aligned or bit(0) aligned. The dummy variable
ensures that the bit string will begin on an even byte boundary if the program uses shortmap
rules, or on a mod4 boundary if the program uses longmap rules, making your program more
efficient.
Note: You should insert the dummy variable only if the actual storage generation
begins on the appropriate boundary.
3-17
Rearranging Structure Elements to Minimize Alignment Padding
Ensuring Correct Alignment in Untyped Storage Sharing

If you use untyped storage sharing, all data must be properly aligned. Unaligned nonvarying
character strings and pictured data must be byte-aligned; all other data, excluding unaligned
bit strings, must be aligned according to the shortmap or longmap alignment rules that are in
effect.
The followingVOS PL/I program compiles and executes on an XA2000-series module but
does not compile on a Continuum-series module.
untyped_ex: procedure options(main);
declare 1 struct1
2 st1_a
2 st1_b
,
bit(8),
char(4);
/* Aligned on even byte */

/* Offset: 0 bytes
*/
/* Offset: 1 byte
*/
declare 1 struct2
2 st2_a
defined (st1_b),
fixed bin(31);
st2_a = 5;
if st2_a > 0
then put skip list ('st2_a');
end untyped_ex;
In the preceding program, the storage of st1_b, and hence of st2_a, is aligned on an odd
byte. XA2000-series compilers allow odd boundary addressing, but Continuum-series
modules disallow it in most cases, including this case, in which a misaligned variable is used
in a relational expression. On Continuum-series modules, the reference to st2_a causes an
addressing error, and the error condition is signaled. To avoid this type of error, correct the
declaration of struct_2 so that st2_a is no longer aligned on an odd byte.
See Using Untyped Storage Sharing in Chapter 4 of this manual for information on using
untyped storage sharing and for some constraints on its use. In the VOS PL/I Language
Manual (R009), see Chapter 4, Data Types, and Appendix B, Internal Storage, for the
alignment requirements of each data type, and Chapter 6, Storage Classes, for a discussion
of storage sharing.
Rearranging Structure Elements to Minimize Alignment Padding

You can avoid excessive structure padding when converting to longmap by rearranging the
elements of the structure so that the longest elements appear first in the structure. Consider
the following example:
struct $longmap bad_order
{
char a_char;
double a_double; /* must be aligned on a mod8 boundary */
long int an_int; /* must be aligned on a mod4 boundary */
};
3-18
Correctly Aligning Simulations of dec 15 and dec 18 Data Types
If compiled using longmap alignment, this structure begins on a mod8 boundary and uses 24
bytes. The char data element uses 1 byte, followed by 7 bytes of padding. The double data
element uses 8 bytes, and the long int data element uses 4 bytes. At the end of the structure,
the compiler adds 4 bytes of padding, since in VOS Standard C the structure must also end
on a mod8 boundary. In VOS PL/I, a structure with similarly-sized data elements uses 20
bytes because the padding at the end is not needed.
If compiled using shortmap alignment, the VOS Standard C structure would use 14 bytes:
1 byte for the char data element, 1 byte of padding so that the next data element begins on a
word boundary, 8 bytes for the double data element, and 4 bytes for the long int data
element.
If the VOS Standard C structure is rearranged to place the double element first and the long
int element second, it uses only 16 bytes:
struct $longmap good_order
{
double a_double;
long int an_int;
char a_char;
};
In some cases, you may not be able to rearrange the elements of a structure. In such cases,
explicitly add pad elements:
struct $longmap with_padding
{
char achar;
char pad1[3];
long int longint; /* must start on a mod4 boundary */
};
Also, do not rearrange elements of a structure if the rearrangement destroys the logical
ordering of the structure and saves only several bytes of memory. For example, if a structure
has several logical substructures, moving elements among the substructures could make the
code much harder to maintain. However, within each substructure, you may want to rearrange
elements so that the largest element is first.
If the elements of a structure or union cannot be rearranged, pad the structure or union
explicitly, rather than allowing the compiler to pad it. The resulting code will be the same, but
the contents of structures, unions, and arrays of structures will be obvious for the purpose of
debugging and maintaining the program.

Some subroutines, such as s$read_jiffy_clock, s$read_clock,
s$init_random_value and s$get_random_value, have arguments that are declared as
15-digit or 18-digit fixed-decimal integers. Since there are no 15-digit or 18-digit
fixed-decimal-integer scalar data types in VOS Standard C or VOS Pascal, in these two
languages you need to simulate those data types for such argument data.
3-19
When you create a structure or record simulating one of these two data types, and the structure
or record is not a member or a containing structure or record declared as shortmap-aligned,
you must do the following to avoid the occurrence of an alignment violation at compilation.
In VOS Standard C, include the structure in a union that contains a data element of the
type double.
In VOS Pascal, include in the record a field of the type real, or use a variant record
with a variant field of the type real.
Unions, structures, and records are aligned according to the data item having the most
stringent alignment requirements. Therefore, the double data element (in VOS Standard C)
or the real field (in VOS Pascal) causes the entire structure or record to be aligned on a mod8
boundary, avoiding an alignment violation.
The following examples show VOS Standard C and VOS Pascal usage.
VOS Standard C Usage

This example shows the declaration of a structure and union simulating the 15-digit
fixed-decimal scalar data type required by the s$read_jiffy_clock subroutine to which
it will be used to pass argument data.
struct decimal_15_tag
{
short int pad;
unsigned long int high;
unsigned short int low;
};
union dec_15_aligned
{
struct decimal_15_tag time;
double for_alignment_only;
};
In this example, the union dec_15_aligned type contains the structure and a double,
forcing the structure to be aligned on a mod8 boundary. Otherwise, an alignment fault may
result.
For more information, see Chapter 1, Using the Operating System Subroutines, in the VOS
C Subroutines Manual (R068).
3-20
VOS Pascal Usage

This example shows the declaration of a record simulating the 18-digit fixed-decimal scalar
data type required by the s$init_random_value subroutine to which it will be used to pass
argument data.
type
decimal_18_type = record
high: integer;
low: integer
end;
aligned_dec_18 = record
seed1: decimal_18_type;
for_alignment_only : real
end;
var seed: aligned_dec_18;
In this example, the aligned_dec_18 record contains a record (seed1) and a real, forcing
seed (and seed1) to be aligned on a mod8 boundary. Otherwise, an alignment fault may
result.
For more information on this approach to simulating the 18-digit fixed-decimal scalar data
type, see Chapter 1, Using the Operating System Subroutines, in the VOS Pascal
Subroutines Manual (R021).
To use a variant record instead, see the information on variant records in Chapter 3, Data
Types, in the VOS Pascal Language Manual (R014).
3-21
3-22
Chapter 4:
Correcting Programs to Work with a Large Register Set
4-
Continuum-series modules, with their PA-RISC processors, have a much larger set of
registers than XA2000-series modules have. Therefore, when an application runs on a
Continuum-series module, values that would be flushed frequently to memory on a XA2000
module are often kept in registers instead. This chapter explains how to correct coding in
applications that may not run correctly on Continuum-series modules because of the large
register set.
This chapter applies mainly to migrating applications from the MC68000 platform to the
PA-RISC platform, but contains some information relevant to i860 to PA-RISC migration. If
you already migrated your applications from the MC68000 platform of XA2000-series
modules to the i860 platform of XA/R-series modules, you should have already encountered
and corrected the errors described in this chapter. However, this chapter provides some new
information, not documented in Migrating VOS Applications to the Stratus RISC
Architecture (R288), on ways to correct the coding practices described, including some
changes required for VOS Release 13.0 and later releases.
Ensuring That Shared Data is Referenced Consistently

You can have multiple programs running simultaneously in different processes on different
CPUs but accessing the same region of virtual memory. This VOS feature lets programs share
anywhere from a few kilobytes to hundreds of megabytes of data in an efficient manner,
enabling you to construct fast and powerful applications. However, if the programs do not
access the data properly, data inconsistencies can occur that are very difficult to reproduce
and debug.
On XA2000-series as well as on Continuum-series modules, the compilers try to keep the
values of a programs frequently referenced variables in registers, thus reducing accesses to
main memory when the program needs to reference a variable. But because of the smaller
register set on XA2000-series modules, an application using variables in shared virtual
memory may run correctly on those modules even if its programming practices do not fully
ensure consistency in accessing shared data. However, when you migrate an application to
the Continuum platform with its larger register set, the chance that the values of such
variables will be kept in registers increases. The application may therefore fail because it does
not detect a modified value.
For example, if a program contains a variable called counter, the compiler may read the
variable once from memory, then store it in a register. However, if the variable is then
modified in memory in some way that the compiler cannot detect, the value of counter in
the register is no longer correct. Similarly, if one of the programs sharing that data modifies
4-1

counter, and the modified value is not written to memory before another program accesses
the value, that other program access a value in memory that is no longer correct.
For shared data to be accessed consistently by simultaneously running programs, you must
ensure two things:
that the programs use and modify the current copy of the shared data
that only one program at a time can change the shared data
The following sections explain two separate methods for ensuring that programs do not
access outdated copies of shared data and describe two locking policies for ensuring that only
one program at a time can change shared data. Stratus recommends and supports only these
methods.
Ensuring That Programs Access the Current Copy of Shared Data

When the compiler of any VOS programming language optimizes code to improve the
execution speed of programs, it also introduces the possibility of programs using shared data
that is not current.
At optimization level 1 or higher, the compiler eliminates unnecessary loading of data from
memory, and at optimization level 3 or higher, it eliminates unnecessary writing of data to
memory. It determines what loading and storing of data to eliminate based on the following
assumptions:
that storage is not shared among processes

that the compilation unit being compiled is part of the only program able to reference
the data
that only well-known programming language constructs (such as call statements or

signals) or the effects of various storage classes account for all references to and
modifications of the programs data
Based on these assumptions, the compiler uses the following criteria to eliminate redundant
loading and storing of data. The compiler eliminates redundant loading when it concludes that
the value in storage cannot have been changed. The compiler eliminates redundant storing
when it is able to keep the value in a register and concludes that no other program can use the
outdated copy in storage.
However, sharing virtual memory among processes changes the programming model. Values
in storage can be referenced or changed at any point. Therefore, you must either inform the
compiler of which variables are in shared virtual memory so that it changes its assumptions
about those variables, or you must program in a restricted manner to ensure that you get
correct results.
Using the volatile Attribute to Inform the Compiler that Data Is Shared
You use the volatile attribute to inform the compiler about data that can be used or
modified asynchronously in ways that the compiler cannot detect. Such modification can
occur in asynchronous exception handling, i. e. the BREAK condition, or when multiple
processes or devices modify the contents of a shared region of virtual memory.
4-2
Chapter 4: Correcting Programs to Work with a Large Register Set
Declaring a variable as volatile ensures that the value in memory and not the value in a
register is always referenced. Use the volatile attribute to instruct the compiler to read a
variable from memory whenever it needs its value, and to store the current value in memory
whenever that value is modified by the program.
Note: The way type qualifiers apply to pointer types changed beginning in VOS
Release 11. Their use now follows the ANSI standard. The position of the qualifier
determines the object that it qualifies. For example, in the two VOS Standard C
declarations that follow, the volatile qualifier modifies the int type specified, not the
pointer.
volatile int *ptr;
int volatile *ptr;
In contrast, in the following VOS Standard C declaration, ptr is declared as a volatile

pointer to a non-volatile int type.
int * volatile ptr;
An advantage of declaring shared virtual memory variables as volatile is that such

declarations makes it clear to the reader of a program exactly which variables or structures
are in shared memory and which are not. Those that are in shared memory use the volatile
attribute; the others do not.
The disadvantage of this method is that it eliminates many forms of optimization that would
otherwise be possible on expressions containing the shared data.
Note: To ensure that the programs accessing a region of shared virtual memory read
and update the entire set of variables consistently, you must use one of the two locking
policies described in Ensuring That Only One Program at a Time Updates Shared
Data later in this chapter. Declaring variables as volatile without using one of the
locking policies cannot guarantee that a set of variables is referenced or modified as a
unit.
Restricting Your Programming to Ensure that Programs Access Current Data
This section describes a method of restricted programming that relies on careful use of
existing programming language constructs to ensure that the shared data is referenced or
modified consistently and that outdated copies of data are not kept. By using this method, you
can achieve the effect of the volatile attribute without using the attribute. You can use this
alternative to the volatile attribute because the VOS compilers do not perform
interprocedural optimizations on separately compiled procedures, and because several of the
programming language storage classes have properties similar to volatile.
The advantage of this method is that the compilers can optimize expressions that reference
variables in shared virtual memory, but the disadvantage is that you must follow the following
techniques exactly. Any deviation can result in failure to achieve the desired results.
4-3
To use this method, do not declare shared data as volatile, but instead ensure that shared
data is declared only as one of the following storage types:
an external variable in any VOS programming language

a COMMON variable in VOS FORTRAN
a defined variable, or a base-reference of a defined variable, in VOS PL/I
a based variable (a variable referenced via a pointer) in VOS Standard C, VOS Pascal,
VOS PL/I, or VOS COBOL
a union in VOS Standard C

a member of an EQUIVALENCE group in VOS FORTRAN
a variant record in VOS Pascal
a variable declared as based, defined, or parameter in VOS PL/I
a variable in the Linkage Section in VOS COBOL
However, never use based storage for overlaying one data type on another incompatible type
in VOS PL/I. See the section,Using the VOS PL/I defined Storage Class, later in this
chapter, for more information.
In addition to restricting shared virtual memory data to the storage classes in the preceding
list, also use locking subroutines.
Note: To ensure that the programs accessing a region of shared virtual memory read
and update the entire set of variables consistently, you must also use one of the two
locking policies described in the following section, Ensuring That Only One Program
at a Time Updates Shared Data. Even the restricted programming practices described
in this section, when used without one of the locking policies, cannot guarantee that a
set of variables is referenced or modified as a unit.
Use calls only to external locking subroutines and not any form of in-line or internal locking.
The VOS compilers know that an external procedure can reference or modify data in any of
the storage classes listed earlier in this section, and only in those storage classes. Because the
VOS machine-independent locking subroutines, for example, are external calls, data of the
specified storage classes is treated as volatile at the time of the call but not at other times.
The compiler flushes the current values of such data to memory prior to the external
subroutine call that locks a region of shared virtual memory and reloads such data subsequent
to that subroutine call. Similarly, the compiler flushes the values of the shared data to memory
subsequent to the external subroutine call that unlocks a region of shared virtual memory.
Ensuring That Only One Program at a Time Updates Shared Data
To ensure that only one program at a time modifies a set of data in shared virtual memory,
you must use locking subroutines. You can either use the VOS machine-independent locking
subroutines described in Chapter 8, Upgrading to Machine-Independent Locks, which
implement an exclusive-use locking policy, or you can write your own locking subroutines
to implement a multiple-reader/one-writer policy. Either of these policies serializes updates
4-4
to shared data. Stratus does not recommend attempting to reference or update shared data
without using one of these two locking policies.
The exclusive-use locking policy allows only one program at a time to reference or modify
shared data in a region of virtual memory. References to shared data are collected into
regions. Each region is preceded by a call to either s$lock_vm_lock or s$try_vm_lock
and followed by a call to s$unlock_vm_lock. By using the subroutine s$lock_vm_lock
or s$try_vm_lock, the calling program acquires a lock, and can proceed to use and modify
the protected shared data. On the first reference to any shared virtual memory variable in the
locked region, the compiler loads the variable from memory. Subsequent references may
again use a copy in a register. When the computation is complete, the program calls
s$unlock_vm_lock, which stores in physical memory any shared virtual memory variables
from the locked region and releases the virtual memory lock. For efficiency, VOS supports
multiple locks, so that each particular class of data can have its own lock.
The multiple-reader/one-writer locking policy allows multiple programs to simultaneously
read shared data, but allows only one program at a time to modify the shared data. VOS does
not provide subroutines to implement this policy. To use this policy on VOS, you must
provide your own locking subroutines.
A third locking policy, implemented by StrataBUS-style locks, is documented in
>system>doc>spin_lock.doc, but is no longer recommended by Stratus. Because this
mechanism depends on the bus hardware of XA2000-series and XA/R-series modules, it is

available on Continuum-series module only by emulation via a fault handler at a significant
performance penalty. See Chapter 8, Upgrading to Machine-Independent Locks, for
information on upgrading your applications to replace StrataBUS-style locks.
Compiling with the -table or -production_table Argument

As you debug your application during the migration process, you can compile using the
-table argument to ensure that, in most cases, your application will reference the intended
values of variables and, therefore, run correctly. The -table argument ensures that a variable
that would normally be stored in a register is allocated and kept in memory, as if it were
declared as volatile.
The -table argument sets the maximum optimization level to 1. At higher optimization
levels, the compiler eliminates what appears to be unnecessary flushing of a variable to
memory, instead storing the value in physical memory only when the variable or its
containing structure or record is read. If another procedure or task accesses the value of the
variable by means of a pointer instead, however, the compiler does not detect the access and
does not flush the value to memory. As a result, the procedure or task might not reference the
most up-to-date value of the variable.
Note: No interstatement code optimization occurs with optimization level 1, but the
compiler does eliminate what appear to be unnecessary flushing of a variable to
memory within the statement containing the variable.
Although compiling with the -table argument generally avoids the problem of variables not
being declared as volatile, there is a performance penalty. With the -table argument, the
compiler does not perform certain types of object code optimization, such as interstatement
4-5
Modifying VOS Standard C setjmp and longjmp Function Calls
code optimization. In addition, the resulting executable program must access physical
memory more frequently when referencing variables.
Compiling a program with the -table argument (consequently at optimization level 1)
should be an interim step, used in debugging your application during the migration process.
The performance of a program compiled with optimization level 1 is not at a level suitable to
be used in a production environment.
Instead, use the -production_table compiler argument to produce executable code that
is suitable for a production environment but also can be debugged using the VOS Symbolic
Debugger. The -production_table argument sets the optimization level to 3 by default,
resulting in code that executes more quickly than code compiled with the -table argument.
However, code optimized at level 3 may not reload registers for every statement, so the set
and continue requests of the debug command may produce unpredictable results.
Additionally, at optimization level 3 on Continuum-series module, many values will remain
in registers rather than be stored in memory, especially for local automatic variables, so the
debugger may give unpredictable output for these values.
See the description of the cc, cobol, pascal, or pl1 command in the VOS Commands
Reference Manual (R098) for more information on the -table and -production_table
arguments. See also the debug command description in that same manual.
Modifying VOS Standard C setjmp and longjmp Function Calls

In VOS Standard C, a goto statement can transfer control only within the same function. To
allow transfer of control to another function, VOS Standard C provides the setjmp and
longjmp functions.
Existing applications that use the VOS Standard C setjmp and longjmp functions may
work correctly on MC68000-based modules, but not on i860-based or PA-RISC-based
modules. On MC68000-based modules, these applications can rely on the automatic variables
in the function that make a setjmp call being in the same state as when the calling function
was last active, but this is not guaranteed by the ANSI standard.
On PA-RISC and i860-based modules, if you use longjmp to return control from one
function to another, any automatic variable in the function to which control is returned (the
function which made the corresponding setjmp call) is indeterminate if all the following
conditions exist.
the variable is local to the function containing the invocation of the corresponding
setjmp call
the variable does not have volatile-qualified type

the value of the variable has been changed between the setjmp call and the longjmp
call
Therefore, on PA-RISC and i860 modules, if your application relies on the values of the
automatic variables in a function that makes a setjmp call, declare those variables as
volatile rather than assuming that their values will be unchanged after the longjmp
function restores the calling environment saved by setjmp. Declaring such automatic
4-6
Using the VOS PL/I defined Storage Class
variables as volatile not only currently ensures correct operation of an application that
relies on them, but also safeguards the application from future problems if the coding is
revised in a way that changes the value of one or more automatic variables between the
setjmp and longjmp calls.
Using the VOS PL/I defined Storage Class

You may find that existing programs use based storage instead of defined storage for data
overlays of one data type over another data type that is incompatible, although this use of
based storage violates the language rules of VOS PL/I. Such programs may have worked
correctly on XA2000-series modules, which have processors with fewer registers and
compilers that perform fewer optimizations. However, it is likely that the code will not work
correctly on a Continuum-series module with its PA-RISC processor and highly optimizing
compilers. With based storage, only variables of the same type are flushed to memory; thus,
the program may not see a change in a variables value if it references the value that is still in
a register.
Using the VOS PL/I defined storage class, not the based storage class, for all overlays of
one data type over an incompatible type, corrects the problem. (See Chapter 6, Storage
Classes, in the VOS PL/I Language Manual (R009) for more information on what data types
can be overlaid and how they can be overlaid.) When a variable is declared as defined, the
compiler flushes to memory all registers that could be aliased when you modify one possibly
aliased value. This ensures that your program will reference the correct value if it references
the variable using one of the aliases.
For example, suppose you are using based storage to overlay a 32-bit floating-point value and
a 32-bit bit string. Operations on the floating-point value are performed in the processors
floating-point registers, and operations on the bit string in the integer registers. If you perform
an operation on the bit string, and then perform a floating-point operation, the operation on
the bit string may not be reflected, since the floating-point registers will not have been flushed
to memory. However, if you use defined storage for the overlay, the floating point registers
are flushed, and you get the correct result.
Using Alternatives to Defined Overlays

Although using defined storage solves the problem of referencing incorrect variable values,
it does so at a significant performance penalty. Consider the following typical declarations.
dcl
dcl
dcl
dcl
dcl
dcl
p pointer;
k fixed bin(31);
i fixed bin(15);
fb31 fixed bin(31) defined p;
bit32 bit(32) aligned defined k;
char2 char(2) defined i;
With these declarations, the compiler requires every reference to p, k, and i to access
memory as if p, k, and i had been declared as volatile. This negates much of the
performance gain of having a large register set on a PA-RISC processor.
In many cases, you can avoid the performance penalty by using alternatives to defined
overlays.
4-7
Modifying Routines That Directly Access the Stack
Using Alternatives to Defined Pointers

Often a pointer is declared as fixed bin and defined to perform arithmetic tests or other
operations, but you can usually perform these operations in other ways. For example, you can
perform a relational comparison directly on two pointer values. Since relational comparisons
are performed using unsigned arithmetic, the returned value is unsigned. You can also use
the rel built-in function to convert pointers to fixed bin(31)values for comparisons.
Since rel returns a signed value, use direct comparisons (equal or not equal) instead
of relational comparisons in this situation to prevent unexpected behavior.
Using Untyped Storage Sharing
Instead of defining bit field overlays, you can use the unspec pseudovariable and built-in
function instead. Pseudovariables are expressions that appear on the left side of an
assignment statement. Assuming that nothing intervenes to change the value, the converted
value assigned to a pseudovariable is returned by a subsequent reference to the built-in
function of the same name. The unspec function returns a string containing the internal
storage of a variable.
You can use the unspec function with the unspec pseudovariable to facilitate untyped
storage sharing. An assignment to the unspec pseudovariable assigns a bit-string value to the
storage of a variable without regard for data type. See the description of the unspec built-in
function in the VOS PL/I Language Manual (R009) for more information.
Another alternative to defined overlays in VOS PL/I is the untyped_storage_sharing
compiler option. If you specify %options untyped_storage_sharing at the beginning
of a compilation unit, variables of any combination of data types can share the same storage
as long as the variables do not violate the alignment constraints of the target processor. For
example, you can then overlay a character string on a binary integer of the same size. See
Chapter 11, PL/I Preprocessor Statements, in the VOS PL/I Language Manual (R009) for
more information and an example. The untyped_storage_sharing option is also
especially useful when porting non-VOS PL/I code to the VOS environment.
Note: Because storage methods are not standardized, any untyped storage sharing
generally makes the resulting program implementation-dependent.

Because of the large number of registers on the PA-RISC processor, parameters are generally
passed in registers rather than on the stack. Therefore any routine that directly accesses the
stack must be modified.
In VOS Standard C, the arguments in the varying part of a parameter list must be accessed
by using the macros va_arg, va_end, and va_start in the stdarg.h header file. Using
these macros is the correct procedure even before Release 13.0. Using &(this arg)+1 to
find the next argument will not work. See Chapter 11, VOS Standard C Library Functions,
in the VOS Standard C Reference Manual (R363) for more information on using the va_arg,
va_end, and va_start macros.
In VOS PL/I, use the built-in function paramptr for accessing parameters in varying length
parameter lists. The paramptr built-in function is available in Release 11.0 and later
releases, and replaces the VOS PL/I arglistptr built-in function, which is not available on
4-8
Continuum-series modules. See Chapter 13, Built-in Functions, in the VOS PL/I Language
Manual (R009) for more information on the paramptr built-in function.
4-9
4-10
Chapter 5:
Correcting Coding Practices That Jeopardize Portability
5-
This chapter describes some coding practices that may produce working code on the Stratus
MC68000 platform, but which may cause errors when an application is migrated to the
PA-RISC platform.
If you already migrated your applications from the MC68000 platform to the i860 platform,
you should have already encountered and corrected these errors. However, this chapter
provides some new information on alternative coding that may be helpful in further
improving the performance of your applications.
Working with Highly Optimized Code

The compilers available with VOS Release 13.0 and later releases highly optimize code,
which may cause working applications to fail because the compilers strictly enforce the
language rules. A programmer may have written incorrect or inefficient code that worked
with older compilers, but which will not work when compiled at the default optimization
level with the latest compilers.
In most cases, your application will run correctly despite the coding practices described in
this chapter if you compile your application at an optimization level of 2 or lower. However,
code compiled at optimization level 3 (the default for the compilers) is more efficient and
results in better performance than code compiled at lower optimization levels. For the best
performance, therefore, find and correct the problems described in this chapter, and recompile
at optimization level 3.
While debugging your application during the migration process, you can use either the
-table or -production_table compiler argument. However, note the following facts
and limitations:
Code compiled with the -table argument runs more slowly than is suitable for a
production environment, and the -table argument creates a symbol table, for use by
the VOS Symbolic Debugger, that greatly increases the size of the object module. The
-table argument also sets the optimization level to 1.
Code compiled with the -production_table compiler argument can be debugged

with the VOS Symbolic Debugger, runs more efficiently than code compiled with the
-table argument, and is suitable for a production environment. The
-production_table argument produces a symbol table, but only those variables
referenced in the program are placed in the table. The default optimization level for
-production_table is 3, but you can set it to a lower level. Unlike the -table
5-1
Recoding Loops the Compiler Might Eliminate
argument, the -production_table argument does not suppress interstatement code

optimization. Therefore, the set and continue requests of the debug command can
lead to unpredictable results. Also, at optimization level 3 on Continuum-series
modules, many values may remain in registers and not be stored in memory, especially
for local automatic variables, making debugger output unpredictable for such values.
See the description of the cc, cobol, fortran, pascal, pl1, and debug commands for
more information on compiling and debugging at each of the different optimization levels.
These commands are documented in the VOS Commands Reference Manual (R098).
Recoding Loops the Compiler Might Eliminate

If it appears that a loop does nothing, the compiler issues a warning and optimizes the loop
out of existence if you compile the application at optimization level 3. Therefore, check your
applications for loops that the compiler may eliminate and make the recommended
corrections.
For example, if your program delays a task by looping for a specified number of cycles, use
the s$sleep subroutine instead. The s$sleep subroutine suspends a process for a specified
period of time.
If the only action in a loop is to reference a variable that has not been declared as volatile,
such as looping to check the status of a non-volatile lock word, at optimization level 3 the
compiler may assume that the loop does nothing and remove the loop. To check the status of
a lock and acquire ownership of the lock as soon as it is available, use the s$lock_vm_lock
subroutine, described briefly in this manual in Chapter 7, Efficiently Using
Continuum-Series Caches, and documented fully in the VOS Subroutines manuals.
Revising Code That Depends on Unreferenced Variables

At optimization level 3 (the default) or higher, the compiler removes unreferenced variables,
i.e. dead assignments. This can cause certain programs that may have run successfully on
XA2000-series modules to fail on Continuum-series modules. You can compile at a lower
optimization level to avoid the problem, but to maintain efficient code, it is better to find and
correct the coding practice that causes the failure.
For example, some programs try to force a zero divide condition using a statement such as
x = a/0. Unless x is referenced again, such coding will not work if you compile at
optimization level 3 or higher.
You can prevent the compiler from removing unreferenced variables by declaring those
variables as volatile.
Revising Code for Compatibility of Floating-Point Precision

If you are migrating an application from an XA2000-series module, note that the MC68000
family of processors on XA2000-series modules have extended floating-point registers, but
PA-RISC processors on Continuum-series modules do not. The absence of extended
floating-point registers means that intermediate values in floating-point calculations on a
PA-RISC processor, as on an i860 processor, are rounded.
5-2
Chapter 5: Correcting Coding Practices That Jeopardize Portability
Handling and Debugging Floating-Point Exceptions
You cannot specify extended precision variables or constants on either platform, but the
extended floating-point registers of the MC68000 family of processors allow VOS compilers
to store intermediate values of a calculation in extended floating point precision. Because
such intermediate values are rounded on a PA-RISC processor, the result of a complicated
floating point calculation in a program may differ in the low-order bits, depending on whether
the program is compiled on an XA2000-series module or a Continuum-series module. If the
result of a complicated floating point calculation is then used as input to other calculations,
an insignificant difference in result may be magnified by those subsequent calculations.
If it is important that complicated floating-point calculations yield absolutely identical results
when your application is compiled and run on each of the two platforms (MC68000 and
PA-RISC), you may need to revise your source code. You can ensure the rounding of
intermediate values in calculations by breaking up big expressions into smaller ones and
assigning intermediate values to variables.
Handling and Debugging Floating-Point Exceptions

The PA-RISC processor does not immediately detect the occurrence of a floating-point
exception, such as overflow resulting from a calculation. It does not signal a fault until the
next floating-point operation occurs. Occasionally, this can cause one of the following two
problems.
If you enable an exception handler for the fault and disable the exception handler soon
after the floating-point calculation that causes the exception, the exception handler may
not catch the fault.
If the default exception handler catches the fault, and you invoke the debug command
to investigate it, the floating-point exception may appear to have occurred later in the
code than where it actually occurred.
It is very difficult to avoid entirely programming practices that cause floating-point
exceptions, so you probably will have to rely on the default exception handler or an exception
handler that you enable. An exception handler you enable can be for the floating-point
exception itself or for the error condition generated by the floating-point exception. To assure
that the exception handler catches and handles the fault when it occurs and does not defer the
signalling of the fault, store all floating-point results before you either exit the procedure with
the handler or you disable the handler. Assigning a floating-point value to an external
variable, based variable, or reference parameter is the best way to accomplish this storing, and
such an assignment cannot be removed by the optimizer.
Alternatively, you can avoid these problems by compiling at an optimization level of 2 or
lower, but applications compiled at optimization levels lower than 3 (the default) generally
do not have the best performance possible.
Checking for Uninitialized Variables

An incorrect program may execute as intended even when uninitialized variables are used, if
such variables happen to have an initial value of zero or some other value appropriate to your
program logic. Such incorrect coding can cause applications to fail or provide erroneous
results when you migrate applications to a new processor, upgrade modules to a new VOS
5-3
Checking Function Calls to and from VOS FORTRAN
release, or even when you run the same application at different times on the same VOS release
as process or task memory usage varies.
If you specify the -check_uninitialized argument when compiling your program at an
optimization level of 3 or higher, the compiler issues a warning for every uninitialized
variable. The -check_uninitialized argument in some cases also issues warnings where
no problem exists, for example, when a program may take multiple paths of execution before
using a variable, and in at least one of those paths the variable has not been set.
Compiling at optimization level 3 or higher without the -check_uninitialized argument
also checks for uninitialized variables, but skips checking variables that are in conditional
code paths. Therefore, when using this default checking for uninitialized variables, you can
be certain that every warning concerning an uninitialized variable is a valid warning, but you
can not be sure that you have found every uninitialized variable.
Certain system subroutines require their arguments to be initialized. For example,
s$write_device requires certain fields in its bcs_write_device_info argument to be
initialized to zero values. The compiler, however, does not detect input-output arguments that
are uninitialized when they are passed to subroutines or functions. You must check to make
sure that you are adhering to all interface requirements documented in the subroutine
descriptions in the VOS Subroutines manuals.

The PA-RISC processor introduces restrictions on passing arguments of string-valued
functions between VOS FORTRAN programs and programs in other VOS programming
languages. In VOS FORTRAN on Continuum-series modules, the address of the return value
for a CHARACTER or STRING function is passed, regardless of the maximum length of that
return value. In other VOS programming languages on Continuum-series modules,
string-valued functions for short return values are handled differently from how they are
handled in VOS FORTRAN.
Therefore, the following practices will not work when passing a return value to VOS
FORTRAN from another VOS programming language, or to another VOS programming
language from VOS FORTRAN:
using a VOS FORTRAN CHARACTER function with a return value whose maximum
length is less than or equal to 8 characters
using a VOS FORTRAN STRING function with a return value whose maximum length
is less than or equal to 6 characters
using a string-valued function in another VOS programming language, when the

maximum length of that functions return value is less than 8 characters for a
non-varying character string, or less than 6 characters for a varying character string
If the application you are migrating to the Continuum platform relies on function calls
between VOS FORTRAN and another VOS programming language, check your source code
before migrating the application to the Continuum platform. Check the maximum length
declared for return values of CHARACTER and STRING functions in the VOS FORTRAN
source code, and the maximum declared length for return values of string-valued functions in
5-4
the source code of the other programming language. If the maximum length of a return value
is less than the required length, cited earlier in this section, for interoperability of VOS
FORTRAN with other VOS programming languages, you must do one of the following:
Revise your application to avoid the short maximum return value.

Revise your source code so that the function call and the function itself are both in VOS
FORTRAN or both in other VOS programming languages.
5-5
5-6
Chapter 6:
Improving Memory Access by Specifying Memory Pools
6-
This chapter explains how to maximize performance on a Continuum-series module by using

VOS subroutines and commands to manage how memory is allocated.
Memory Access on a Continuum-Series Module

Continuum-series modules are the first Stratus modules in which the CPU and memory are
on one board, called the CPU/memory board. As with previous Stratus hardware platforms,
on Continuum-series modules, physical memory is divided between boards, and any CPU can
access any memory. However, accesses to memory on the same board as the CPU, called
local memory, do not need to use the system bus. 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, which must be accessed across the system bus.
On a module with two logical CPU/memory boards, memory is divided into pools, one
associated with each logical CPU/memory board and referred to as pools 0 and 1. Each CPU
regards these memory pools as either local or remote. Each board, in turn, can contain up to
two CPUs. Each CPU can access both the local memory pool on its own board and the remote
memory pool on the other board.
On Continuum-series modules, VOS balances memory usage between memory pools and
maximizes the use of local memory in the following ways.
When any process is created, VOS associates it with a particular memory pool by
assigning it to a CPU/memory board. For its duration, the process runs only on CPUs
on that board.
When a user creates a process, if the user specifies no memory pool, VOS assigns the
process to the memory pool with the most free physical memory.
To optimize CPU cache usage, whenever possible VOS assigns a process to run on the
CPU on which it most recently ran.
In each memory pool, VOS keeps a copy of all code being executed on that board.
VOS attempts to allocate all kernel data memory used by or on behalf of a process from
the same memory pool as the process. (All non-kernel data, except data in shared
virtual memory, is always allocated from the same memory pool as the process.)
6-1
Controlling Which Memory Pool a Process Uses

The default behavior of VOS with regard to memory pool assignment, as described in the
preceding section, is designed to provide the best performance in most cases. Therefore, in
migrating your applications to the Continuum platform, you probably need to make few, if
any, changes to existing code to ensure the most efficient use of memory.
For situations in which you do want to control how a new process is assigned to a memory
pool, VOS provides several subroutines and commands to specify memory pool assignment
and obtain information about a processs memory pool usage. On Continuum-series modules
with two logical CPU/memory boards, you might want to control memory pool assignment,
for example, in the following cases:
Several related applications share the same regions of virtual memory. Assign such
applications to the same memory pool for best performance.
You are creating a server process and a requestor process and want them to run on
different CPUs. Specifying a different memory pool for each of the two processes
created ensures that they will run on separate CPU/memory boards.
You want to balance the CPU load by not having two large applications run on the same
CPU. Specifying a different memory pool for each of the two applications ensures that
they will run on separate CPU/memory boards regardless of which board has the most
available memory at the time they are started.
Revising s$start_process Calls to s$start_new_process Calls

On a Continuum-series module with two logical CPU/memory boards, by default VOS starts
a new process on the CPU/memory board that has the most free memory. This assignment of
a memory pool occurs for processes started with the existing s$start_process subroutine,
which provides no means for specifying a memory pool.
However, VOS Release 13.0 and later releases provide the s$start_new_process
subroutine, which has all of the functionality of s$start_process and adds the capability
of specifying a memory pool to associate with the new process.
Even in situations in which you do not want to assign a new process to a particular memory
pool, Stratus recommends that you upgrade the s$start_process calls in your
applications to s$start_new_process calls. The s$start_new_process subroutine
replaces s$start_process as the recommended way of starting a new process because its
interface can be changed compatibly in the future. Therefore, any future enhancements will
be made to s$start_new_process, not to s$start_process.
The s$start_new_process subroutine creates and starts a process that executes the
commands in a given command line. On a Continuum-series module with two logical
6-2
Chapter 6: Improving Memory Access by Specifying Memory Pools
CPU/memory boards, you can use the memory_pool element of the new_process_info
structure to specify that the process will be assigned to a memory pool in any one of the
following ways:
to the memory pool you specify by number, either 0 or 1

to the memory pool that currently has the most free memory
to the same memory pool that is associated with the calling process
On a Continuum-series module with one logical CPU/memory board, you can specify any of
the preceding memory pool assignments except an assignment to memory pool 1. However,
the actual assignment will always be to memory pool 0. A source module in which you
specify a value for memory_pool will also run on XA2000- and XA/R-series modules when
compiled and bound on any of those modules, except if you specify memory pool 1.
Note: The new_process_info structure, of which the memory_pool element is a
member, must be declared as longmap.
For a complete description of the s$start_new_process subroutine, see the VOS
Evaluating s$clone Subroutine Calls

The s$clone subroutine, which starts an interactive subprocess, does not provide a way to
specify a memory pool. Therefore, a process started with s$clone on a Continuum-series
module with two CPU/memory boards is assigned to the memory pool that currently has the
most free memory. If the process your application is starting does not need to be an interactive
process, consider using s$start_new_process instead. If an interactive process is
required, you can continue to use the s$clone subroutine with no coding change required
for migration to a Continuum-series module.
Specifying Memory Pool Assignment in Command Macros

VOS provides a command interface you can use to specify the memory pool assignment of a
process you are starting either as a subprocess via the login command or as a new process
with the start_process command. If your application uses either of these commands in
command macros, revise those command macros for cases in which you want to specify
either the local or remote memory pool for the process being started.
By default, the -memory_pool argument of the start_process command or the
subprocess login command causes VOS to assign the subprocess or new process to the
memory pool with the most available memory. If this default assignment meets the needs of
your application, there is no need to revise your command macros.
To assign the process being started to a particular memory pool, add the -memory_pool
argument to the command line of the start_process command or the subprocess login
command in a command macro, with a value of 0 or 1.
Note: If you specify -memory_pool 1 for the login command or start_process
command in a command macro, the command will not execute when you run the
command macro on a Continuum-series module with only one CPU/memory board or
on an XA2000 or XA/R-series module. Instead, the command macro returns the
6-3
Getting Information on Memory Pool Assignment
following error message: Invalid format in argument. 1 not allowed for

string.
For more information on the subprocess login command and the start_process
command, see the VOS Commands Reference Manual (R098).
Getting Information on Memory Pool Assignment

By using the s$get_process_info or s$get_processes_info subroutine, your
application can get information on the memory pool assignment of processes. Also, you can
use the list_users command from VOS command level to list the memory pool
assignment of processes.
Using the s$get_process_info and s$get_processes_info Subroutines

To determine the memory pool to which a process, or each process in a set of processes, is
assigned, use the s$get_process_info or the s$get_processes_info subroutine. In
VOS Release 13.0 and later releases, these two subroutines return memory pool information.
The s$get_process_info subroutine returns information about a specified process. The
process_info structure passed to the subroutine includes a memory_pool element. On a
Continuum-series module with two logical CPU/memory boards, the value returned in
memory_pool indicates the memory pool, 0 or 1, associated with the specified process. On
a module other than a Continuum-series module, the value returned in memory_pool is
always 0 because there is only one pool. Note that the process_info structure must be
declared as shortmap.
The s$get_processes_info subroutine returns information about a set of processes. The
set of processes is defined by a set of users, a set of process names, and a module name. The
processes_info structure passed to the subroutine includes a memory_pool element. On
a Continuum-series module with two logical CPU/memory boards, the value returned in
memory_pool for each process defined indicates the memory pool, 0 or 1, associated with
that process. On a module other than a Continuum-series module, the value returned in
memory_pool is always 0 because there is only one pool. Note that the processes_info
structure must be declared as shortmap.
See the VOS Subroutines manuals for complete descriptions of the subroutines
s$get_process_info and s$get_processes_info.
Using the list_users Command

From VOS command level, to determine the memory pool assignment of each process on a
Continuum-series module, use the list_users command. In VOS Release 13.0 and later
releases, the output of the list_users command displays, under the column heading M, the
memory pool number, 0 or 1, for each process. See the VOS Commands Reference
Manual (R098) for more information on the list_users command.
6-4
Chapter 6: Improving Memory Access by Specifying Memory Pools
Chapter 7:
Efficiently Using Continuum-Series Caches
7-
This chapter describes how to use Continuum-series caches efficiently.

On Continuum-series modules, each CPU/memory board contains a large, high-performance
direct map (virtually indexed) data cache. The cache is a high-speed buffer storage area
between main memory and the processor. The cache increases effective memory transfer rates
and processor speed, providing improved performance over previous models of Stratus
computers. However, in a multiprocessor environment, you must use the caches efficiently to
minimize bus contention and cache misses, which are references to data that is in a cache on
another CPU/memory board or is not in a cache at all but in main memory. Data is cached in
32-byte units of storage called cache lines.
This chapter provides information on the following topics:
minimizing data sharing among processors

identifying cache line boundaries
packing cache lines to reduce bus usage
identifying your programs current caching and locking policies and upgrading those
policies to ones that are supported on Continuum-series modules
Improving Performance with Caches

Data that is cached can be referenced much faster than data that is not cached. Loading a
cache line from main memory requires use of the bus, and, particularly in a multiprocessor
environment where bus traffic may be high, keeping cache-line loading to a minimum ensures
the best performance.
Cache usage is most effective in improving the performance of an application when the data
in the cache is referenced many times for each time it is loaded. It is least effective when it is
referenced only once for each time it is loaded. Such frequent loading of the cache can
noticeably affect the performance of your application.
To optimize CPU cache usage on Continuum-series modules, whenever possible VOS
assigns a process to run on the CPU on which it most recently ran. This strategy is one of
several ways in which VOS, by default, increases the efficiency of memory usage and reduces
bus traffic. See Memory Access on a Continuum-Series Module in Chapter 6 for
information on other ways VOS increases the efficiency of memory by balancing memory
usage between memory pools and maximizing the use of local memory.
You can further reduce bus traffic and improve performance by minimizing cache line
loading in the ways described in the following sections.
7-1
Determining Cache Line Boundaries

To efficiently use Continuum-series caches, you need to know the following information:
Cache lines are 32 bytes in size.The virtual address space of a process on

Continuum-series modules is 2GB (1GB for the system and 1 GB for the user).
Therefore, the number of cache lines per process is equal to 65,536,000 (2GB/32
bytes).
Data caches are either 256 KB or 1 MB in size. Therefore, the number of cache lines
per cache is 8192 for a 256 KB cache (256KB/32 bytes) or 32,768 for a 1MB cache
(1MB/32 bytes). See Table 7-1 for the cache size on each Continuum-series model.
1
Table 7-1. Cache Sizes on Continuum-Series Models

Model
Number of Slots
Number of
Logical CPUs
CPU Type
Cache Size
per CPU
Model 610S
72MHz PA-7100
256KB
Model 610
72MHz PA-7100
256KB
Model 620
72MHz PA-7100
256KB
Model 1210
12
72MHz PA-7100
256KB
Model 1215
12
96MHz PA-7100
1MB
Model 1225
12
96MHz PA-7100
1MB
Model 1245
12
96MHz PA-7100
1MB
Cache lines start at addresses that are 0 mod 32, and each cache line continues for 32 bytes.
Therefore, the first cache line begins at address 00000000, the second at address 00000020,
the third at address 00000040, and so on.
7-2
Chapter 7: Efficiently Using Continuum-Series Caches
The caches are direct map caches, i. e. they are virtually indexed so that the processor
determines which cache line to reference based on virtual addresses. In hexadecimal format
for a 1 MB cache, virtual addresses are mapped to cache lines as follows:
Range of Virtual Addresses
Start Address
End Address
Cache Line Number
1F
20
3F
40
5F
FFFE0
FFFFF
32,767
100000
10001F
100020
10003F
100040
10005F
.
.
.
.
.
.
1FFFE0
1FFFFF
32,767
200000
20001F
.
.
.
2FFFE0
2FFFFF
32,767
.
.
.
If a program references two virtual addresses that are indexed to the same cache line, the data
in the cache line is written to memory or read from memory, eliminating the performance
advantage of having data cached.
Minimizing Data Sharing Among Processors

A Continuum-series module with two logical CPU/memory boards has four logical data
caches. On those modules, maximizing cache line usage is particularly important for shared
data that is being modified. Data that is never modified can be in both caches and therefore
can be accessed efficiently by processes assigned to either memory pool. But when data in
one memory pool is modified by a process and cached in that CPU/memory boards cache,
the other caches outdated copy of the data must be evicted and the modified data eventually
7-3
reloaded into the other cache. Therefore, the access time for modified data, especially data
that is frequently modified, is much greater than for data that is never modified. It takes more
than twice as long to make a shared memory request as it does to make an unshared request.
Heavily used global variables in shared virtual memory that are updated by every transaction
increase the occurrence of cache line loading and therefore reduce efficiency. Global
statistics, accounting, or timing variables can have just as high a performance cost as program
logic variables or data.
You can increase data caching efficiency in the following ways.
Eliminate unnecessary sharing. Make variables per-processor if possible, or at least be

sure they use different memory pools.
Be sure the data is in different cache lines to avoid false sharing (accessing different
virtual memory addresses in a common cache line, causing frequent flushing of the
cache to main memory). See the preceding section, Determining Cache Line
Boundaries, for information on the addresses of cache line boundaries.
Do not lay out large data structures so that their virtual addresses are separated by some
exact multiple of the cache line size. See Avoiding Inefficient Cache Usage in
Chapter 11 for more information on the performance problems this can cause.
Fully Utilizing Each Cache Line

In a multiprocessor environment, the performance cost of a memory access increases because
there is more bus traffic. Therefore, even after you eliminate unnecessary sharing, you can
further improve performance by fully utilizing each cache line to reduce the number of
memory accesses.
Cache lines are 32 bytes in size and, on Continuum-series modules and XA/R-series modules,
all data in cache line is read from or written back to memory if any data in the cache line is
modified. (XA2000-series modules write back only the modified locations in a cache line.)
Therefore, ensuring that as much data as possible fits in each cache line reduces the number
of memory accesses and alleviates bus contention.
To ensure optimal use of cache lines, do the following:
Rearrange data such as array subscripts and nested loops so that data is accessed
sequentially in main memory.
Rearrange data structures to maximize local referencing. Pack data that is referenced
together into as few cache lines as possible.
For automatic and static data, for which it is difficult to determine cache line
boundaries, incorporate the data into structures. The compilers, in most cases, allocate
memory for data structures in a way that fully utilizes each cache line.
Consider allocating large structures on cache line boundaries so that you can control
which variables occupy the same cache line.
7-4
Understanding Memory-Ordering, Caching Policies, and Locking
Avoiding Problems with the Instruction Cache

Most cache-related issues that you need to be aware of involve the data cache. However, each
CPU/memory board also has a separate instruction cache, which is the same size as the data
cache. You cannot control instruction caching efficiency in the same way as you control data
caching efficiency, such as by ensuring that each cache line is fully utilized. But
understanding how data is cached, as explained in this chapter, can help you avoid certain
instruction caching problems as well.
For example, having multiple processes running identical but separate copies of the same
program causes instruction caching problems because each process will have to reload the
cache each time it runs the program. See Avoiding Inefficient Cache Usage in Chapter 11
for an explanation of this error.

The following sections summarize the caching policies that applications can use on Stratus
modules, explain the relationship of those caching policies to virtual memory locking, and
recommend how you should modify caching policies and upgrade locking mechanisms when
migrating applications to Continuum-series modules.
Caching Policies that Support Memory-Ordering

On XA2000-series and XA/R-series modules, some of your applications may rely on
memory-ordering as the basis for their locking policy rather than using virtual memory locks.
Memory-ordering maintains data integrity by controlling the order in which reads and writes
occur in a multiprocessor shared memory environment, rather than by locking regions of
virtual memory.
To use memory-ordering on any Stratus module, you must choose the
s$connect_vm_region access mode 2. On XA2000-series and Continuum-series
modules, access mode 2 is the only access mode that gives you read/write access to a region
of shared virtual memory. Although this access mode does not require any routines that lock
regions of virtual memory, Stratus strongly recommends that you use locking routines.
There are three access modes available on XA/R-series modules that give you read/write
access to shared virtual memory (access modes 2, 7, and 9), but only access mode 2, which
uses a caching policy called exclusive-sequential, supports memory-ordering. Stratus
strongly discourages using exclusive-sequential caching on XA/R-series modules because,
on those modules, it has the highest performance cost of any of the caching policies available.
On Continuum-series modules, access mode 2 supports memory-ordering without the
performance degradation associated with the exclusive-sequential caching policy
implemented by access mode 2 on XA/R-series modules. However, if the application you are
migrating to a Continuum-series module uses memory-ordering without any virtual memory
locking routines, Stratus recommends that you upgrade to an exclusive-use locking policy
that uses the machine-independent locking mechanism (s$connect_vm_region access
mode 10) described in Chapter 8, Upgrading to Machine-Independent Locks.
7-5
Exclusive Non-Sequential and Shared Non-Sequential Caching Policies

For multiprocessor modules in the XA/R series, two additional caching policies were
introduced: exclusive non-sequential caching (s$connect_vm_region access mode 7) and
shared non-sequential caching (s$connect_vm_region access mode 9). On these modules,
you can choose a caching policy depending, for example, on whether your data is mostly
read-only or whether data is frequently written to memory. You can define different virtual
memory regions, each with a different caching policy implemented by a different access
mode specified in a call to the subroutine s$connect_vm_region. Since these two caching
polices do not support memory-ordering, you must use a virtual memory locking mechanism.
On Continuum-series and XA2000-series modules, s$connect_vm_region access modes
7 and 9 are not supported. If the XA/R-series application you are migrating to the Continuum
platform uses either of these access modes, Stratus recommends that you upgrade to an
exclusive-use locking policy by using the machine-independent locking mechanism
described in Chapter 8, Upgrading to Machine-Independent Locks. To implement this
policy, use s$connect_vm_region access mode 10 for the shared virtual memory region
containing the locks, and use access mode 2 for the shared virtual memory region containing
the associated program data.
7-6
Chapter 8:
Upgrading to Machine-Independent Locks
8-
On Continuum-series modules, VOS uses machine-independent locking rather than

StrataBUS-style locks. StrataBUS-style locks depend on the particular bus hardware of
XA2000- and XA/R-series Stratus modules. This chapter describes how to upgrade your
programs to use the machine-independent locking mechanism. The chapter also discusses
how to use an emulation of the StrataBUS locking system for compatibility with existing
applications, but strongly recommends upgrading applications to use the
machine-independent locking mechanism for improved performance.
Choosing a Locking Mechanism

Continuum-series modules support the machine-independent locking mechanism and an
emulation of the StrataBUS locking mechanism. However, Stratus strongly recommends that
you upgrade your applications to use the machine-independent locking mechanism.
Upgrading to the machine-independent locking mechanism can make the lock-related code
in an application run as much as a hundred times more quickly than lock-related code that
uses the StrataBUS lock emulation.
The StrataBUS lock emulation enables you to run existing applications on PA-RISC modules
without recoding the lock calls, but is performed by a fault handler that generates a thousand
or more additional instructions to be executed. Therefore, it is not nearly as efficient as the
machine-independent locking mechanism. The performance penalty for using the emulation
of the StrataBUS locking mechanism is about the same as that for an alignment fault.
If you recompile existing code without upgrading to the machine-independent locking
mechanism described in this chapter, the code uses the emulation of the StrataBUS locking
mechanism.
Note: You can choose instead to use a multiple-reader/one-writer locking policy, as
summarized in Ensuring That Only One Program at a Time Updates Shared Data in
Chapter 4, but you must provide your own subroutines to implement that locking
policy.
Using the Machine-Independent Lock Interfaces

To use the machine-independent locking mechanism, applications must create shareable
pages by specifying an access_mode value of 10 in the s$connect_vm_region
subroutine call. On Continuum-series systems, an access_mode value of 10 connects
read/write shared data, and is equivalent to an access_mode value of 2 on i860 and
MC68000-based systems. (On i860- and MC68000-based systems, an access_mode value
8-1
of 10 invokes the StrataBUS locking mechanism, the same interlock memory access invoked
by an access_mode value of 3 on those systems.)
The s$query_vm_lock subroutine, designed for use in debugging applications, requires
that an application specify an access_mode value of 8 in the s$connect_vm_region
subroutine call.
Table 8-1 describes access_mode values 8 and 10. For a complete description of
s$connect_vm_region and all the access modes, see the VOS Subroutines manuals.
1
Table 8-1. Additional Access Modes for Connecting a Processs Virtual Memory to a File
Code
Access Mode
I/O Type
Locking Mode
Vm-lock debug access. The calling process may read

or write any page in the region of virtual-memory
locks. This mode is useful for debug access to a region
of virtual-memory locks, since the reads are not done
with the hardware interlock mechanism. The
copy_on_write switch must be false.
update
implicit
10
Machine-independent vm-lock access. The calling

process operates on locks in the pages of this region
using the virtual-memory lock subroutines, such as
s$lock_vm_lock. The copy_on_write switch
must be false.
update
implicit
A program can use the machine-independent locking subroutines to perform the following
locking-related tasks:
initialize a lock with s$init_vm_lock

try once to lock a lock with s$try_vm_lock
try repeatedly to lock a lock until successful with s$lock_vm_lock
unlock a lock with s$unlock_vm_lock
check the size of locks with s$vm_lock_size
check a locks status, in vm-lock debug access mode 8, with s$query_vm_lock
VOS Release 13.0 supports Continuum-series modules only. However, with Release 13.1 and
later releases that support modules released prior to the Continuum series, you will be able to
use the machine-independent locking subroutines on all Stratus platforms.
The subroutines for using the machine-independent locking mechanism replace the existing
operating system library routines try_spin_lock, lock_spin_lock,
unlock_spin_lock, and spin_lock_size and provide some enhanced functionality. The
s$init_vm_lock and s$query_vm_lock subroutines have no equivalent existing
operating system library routines. Users of the existing routines had to initialize a lock by
explicitly setting the sign bit of the lock word to a negative value. Since any reading of the
lock word would reset the sign bit, users could not check the status of a lock without changing
that status. The s$init_vm_lock and s$query_vm_lock subroutines provide a
subroutine interface for initializing a lock and for checking the status of a lock.
8-2
Chapter 8: Upgrading to Machine-Independent Locks
Note: When recoding to replace unlock_spin_lock with s$unlock_vm_lock, be

sure you correctly declare and use the lock_storage argument to
s$unlock_vm_lock, as indicated in the VOS Subroutines manuals. Unlike the
similar arguments to the other existing operating system library (spin lock) routines, the
argument to unlock_spin_lock is defined as a pointer to the lock word, not the
address of a pointer to the lock word.
When you upgrade your code to use machine-independent locking to run on a
Continuum-series module, also replace any calls to the subroutine s$get_vm_lock_word.
The use of access mode 10 for s$connect_vm_region causes calls to
s$get_vm_lock_word to return the error code e$invalid_access_mode (1071).
Replace each call to s$get_vm_lock_word with a call either to s$lock_vm_lock or
s$try_vm_lock, and also replace the code that unlocked a lock word (probably a direct
assignment to the lock word) with a call to s$unlock_vm_lock.
The subroutines for using the machine-independent locking mechanism can be called from
all programming languages supported on the Stratus PA-RISC platform. The older operating
system library routines could be called only from VOS Standard C and VOS PL/I. To use
those routines in VOS COBOL, for example, you had to write a VOS Standard C function or
VOS PL/I procedure that called the routines for the VOS COBOL program.
Following are brief explanations of the six machine-independent locking subroutines.
The s$lock_vm_lock subroutine acquires ownership of a lock located in shared

virtual memory, looping until the lock is acquired.
The s$try_vm_lock subroutine tries to acquire a lock located in shared virtual

memory, but does not loop if the lock cannot be acquired immediately. If the lock is not
currently locked, s$try_vm_lock acquires ownership of the lock. If the lock is
currently locked, the subroutine returns the error code e$already_locked (1206).
The s$init_vm_lock subroutine initializes the state of a lock in shared virtual

memory to the unlocked state. Use this subroutine to initialize each lock to the
unlocked state before manipulating the lock with s$lock_vm_lock,
s$try_vm_lock, and s$unlock_vm_lock.
The s$vm_lock_size subroutine returns the number of bytes of lock memory that are
used for a single lock on the current processor.
The s$unlock_vm_lock subroutine unlocks a lock in shared virtual memory.

The s$query_vm_lock subroutine checks the current status of a lock in shared virtual
memory, but does not affect the locked or unlocked status of the lock.
For more information, refer to the following documentation:
For complete descriptions of all subroutines mentioned in this chapter, see the VOS
See the s$init_vm_lock subroutine description in the VOS Subroutines manuals for
information on, and a brief coding example of, conditional precompilation. You can use
8-3
conditional precompilation to handle different processor-specific lock sizes when using

the same source module to compile applications on different Stratus platforms.
(Beginning with VOS Release 13.1, you can use the machine-independent locking
mechanism on XA2000 and XA/R-series modules.)
For information on the existing operating system library routines, see the file
>system>doc>spin_lock.doc.
8-4
Chapter 8: Upgrading to Machine-Independent Locks
Chapter 9:
Restricting the Memory Used by Programs or Processes
9-
This chapter documents the following topics:
how address space is handled on Continuum-series modules and on VOS Release 13.0
and later releases
what kinds of virtual memory limits exist for a program or process and how you get
information about and adjust those limits from command level, at bind time, and with
subroutine calls in the source code
how you can further manage a programs virtual memory allocation using three
additional bind command arguments
how you can use bind directives to create a shared virtual memory database that avoids
duplicative use of physical disk space by multiple program modules using the database
For complete descriptions of the commands and subroutines referred to in this chapter, see
the following manuals:
The VOS Commands Reference Manual (R098) documents the

list_process_cmd_limits, update_process_cmd_limits, and bind
commands.
The manual VOS System Administration: Administering and Customizing a

System (R281) documents the list_default_cmd_limits and
update_default_cmd_limits commands.
The VOS Subroutines manuals document the s$get_current_cmd_limit and

s$set_current_cmd_limit subroutines.
For information on problems you might encounter if limits are inadequately or inaccurately
set, see Correcting Problems Related to Process and Program Limits in Chapter 11.
Understanding Program Address Space Changes

This section explains changes in how address space is handled on Continuum-series modules
and on VOS Release 13.0 and later releases.
On Continuum-series modules, stack and heap growth is in the opposite direction from stack
and heap growth on XA2000-series and XA/R-series modules. Stacks grow up from the
9-1
Understanding Program Address Space Changes
lowest address to the highest address, and heaps grow down. This change is specific to
Continuum-series modules, not to the VOS Releases that support them.
VOS Release 13.0 (and for XA2000 and XA/R-series modules, VOS Release 13.1) and later
releases handle address space differently from earlier releases. Each static task has its own
fence, which prevents tasks from overwriting each other, and the last tasks stack always has
a fence of at least 32K. In addition, program address space contains an area of dead space,
which is space that can be used as stack space, heap space, or shared-memory space.
Figure 9-1 shows the layout of a programs address space on Continuum-series modules.
1
Code Region
Lowest
Address
Unshared
Static Region
Shared
Static Region
Symbol Table
(Symtab)
Program
Address
Space
Maps
Stack
Fence
Dead Space
Heap
Process Space
Highest
Address
Figure 9-1. Program Address Space on Continuum-Series Modules
9-2
Chapter 9: Restricting the Memory Used by Programs or Processes
Limiting Virtual Memory Allocation for a Program or Command

With VOS Release 13.0 and later releases, VOS provides default virtual memory limits for
processes on a module and also lets you adjust virtual memory limits to meet the needs of
your program or process.
Controlling stack and heap growth is a safety measure. For example, programs with recursive
algorithms could, through a programming error, cause a runaway use of stack or heap space.
If a stack grows too far, it can occupy the space used by the processs heap or by another
process. If a heap grows too far, it can occupy the space used by the processs stack or by
another process. The result of this uncontrolled growth could be an application or module
interruption.
A process has four sets of memory limits that determine how much virtual memory (total
program address space, heap, and stack space) can be allocated for a program module or VOS
command.
Process maximum command limits restrict the maximum amount of virtual memory that can
be allocated for any program module a process executes on the current module. A programs
current command limits (the current size limits, either specified explicitly for the program or
initially allocated by default) cannot exceed the process maximum command limits. Thus, the
process maximum command limits restrict the size to which the current command limits can
grow. When a new process starts on a module, the process maximum command limits are set
to the maximum limits of the module default command limits. You can get or change the
process maximum command limits for a specified memory category (total program address
space, total heap size, or total stack size) as follows:
Use the s$get_current_cmd_limit subroutine to return the current setting for the
process maximum command limits for a specified memory category.
Display process maximum command limits for all three memory categories with the
list_process_cmd_limits command.
Change process maximum command limits for a specified memory category with the
s$set_current_cmd_limit subroutine or for one or more specified memory
categories with the update_process_cmd_limits command. Only a privileged
process can increase process maximum command limits. Using

s$set_current_cmd_limit, a non-privileged calling process can decrease its own
process maximum command limits but cannot increase them, and it cannot change any
limits of another process. At command level, a non-privileged user invoking the
update_process_cmd_limits command can decrease but not increase the process
maximum command limits of any or his or her processes, and cannot change any limits
of another users process.
Caution: A privileged user can increase the process maximum command
limits of user processes without restriction. Setting a maximum limit too
high can cause a fatal runtime error in an application. For more
information, see the update_process_cmd_limits command
description in the VOS Commands Reference Manual (R098).
9-3
Process initial command limits determine the virtual memory initially allocated for a program
module that does not itself specify different values for these limits. Unless otherwise
specified, the process initial command limits are set to the initial total limit, initial heap limit,
and initial stack limit of the module default command limits. You can override these limits at
bind time by using arguments to the bind command or equivalent binder control file
directives to specify the size of a programs address space, heap, and stack. You can display
or change the process initial command limits as follows:
Display process initial command limits with the list_process_cmd_limits

command.
Change process initial command limits with the update_process_cmd_limits

command. A non-privileged user can change the process initial command limits of any
of his or her own processes, but only a privileged user can change the process initial
command limits of another users process. No user can set a value for process initial
command limits that is less than the lower bound for the default limits for the module.
The lower bound is the lowest value that a system administrator is allowed to set for
the module defaults. See the update_process_cmd_limits command description
in VOS Commands Reference Manual (R098) for information on the lower bound
limits.
Current command limits restrict the virtual memory that can be allocated for a program
module. These limits are the same as the process initial command limits unless you specify
different limits at bind time or your program changes the initial limits by calling
s$set_current_cmd_limit. If you specify different limits at bind time, the limits you
specify become the programs current command limits, overriding any process initial
command limits. You can get or change the current command limits for a specified memory
category (total program address space, total heap size, or total stack size) as follows:
Use the s$get_current_cmd_limit subroutine to return the current command limit

for a specified memory category.
In a source module, set the current command limit for a specified memory category
with the s$set_current_cmd_limit subroutine.
At bind time, set the current command limit for a specified memory category with the
bind commands -max_program_size, -max_stack_size, and
-max_heap_size arguments or equivalent binder control file directives.
Module default command limits determine the maximum and initial virtual memory limits for
any new process started on the current module. If you are a system administrator, you can
display or change the module default command limits as follows:
Display the default limits with the list_default_cmd_limits command.

Change the default limits with the update_default_cmd_limits command.
However, you cannot specify a value below the lower bound limits, which are the
lowest allowed default values. See the update_default_cmd_limits command
description in VOS System Administration: Administering and Customizing a
System (R281) for the allowed lower bound values.
9-4
Additional bind Command Arguments for Managing Address Space
Additional bind Command Arguments for Managing Address Space

In addition to controlling total program, stack, and heap size as discussed in the preceding
section,Limiting Virtual Memory Allocation for a Program or Command, you can also
control other aspects of program address space usage with the bind commands -size,
-load_point, -stack_fence_size, and -stack_size arguments.
The -size argument specifies the size of the address space for which the binder is to
bind the object modules.
The -load_point argument assigns a lowest address for the object modules being
bound.
The -stack_fence_size argument specifies the size, in bytes, of the fence to be

placed after each static tasks stack. The fence after the last static task in a program is
always 32,768 bytes, unless you specify a higher value with the -stack_fence_size
argument or equivalent binder control file directive.
The -stack_size argument controls the maximum stack size for each static tasks
stack in a program with one or more static tasks.
If you omit any of these four bind command arguments, the binder uses default values
appropriate for the processor family of the module on which you are binding the program. In
most cases, the default settings for a Continuum-series module are adequate for programs you
are migrating to the Continuum architecture.
For information on bind command arguments and equivalent binder control file directives,
see the bind command description in the VOS Commands Reference Manual (R098).
Bind Directives for Creating a Shared Virtual Memory Database

In VOS Release 13.0 and later releases, two bind directives enable you to create a shared
virtual memory database that eliminates duplicative use of physical disk space.
In earlier releases, you could create a shared virtual memory database by creating a data
object module with the create_data_object command. However, both the data object
module and the program modules into which it was bound used physical disk space for the
memory-resident database.
Using the define and high_water_mark bind directives avoids duplicative use of disk
space by storing the address and size of the virtual memory database used by a set of program
modules. In each binder control file, you use the define directive to specify a symbol and
an address for the shared virtual memory region, and you use the high_water_mark
directive to specify the beginning of the stack.
For detailed, step-by-step instructions on using the bind directives to create a shared virtual
memory database, see Appendix C, Reducing Program Module Size When Using Shared
Virtual Memory Databases, in the VOS Commands Reference Manual (R098).
9-5
Bind Directives for Creating a Shared Virtual Memory Database
9-6
Chapter 10:
Upgrading to the Microjiffy Time-of-Day Clock
10-
This chapter describes the Time-of-Day clock used on Continuum-series modules and on
XA/R Model 300 modules and the programmatic interfaces to it.
The Time-of-Day Clock

All VOS time-of-day routines use the modules Time-of-Day clock, which is the timer that
programmers use in their applications.
Continuum-series modules and XA/R Model 300 modules have a microjiffy Time-of-Day
clock of much greater accuracy than the clocks of previously released modules, which
measure time in units called jiffies. A jiffy is 1/65,536 of a second or 15.25 microseconds. The
Continuum-series and XA/R Model 300 Time-of-Day clock measures time in microjiffies. (A
microjiffy is 1/65,536 of a jiffy, or 232.83 picoseconds).
Using the Interfaces to the Time-of-Day Clock

Two VOS system subroutine calls use the full resources of the Continuum-series and XA/R
Model 300 microjiffy Time-of-Day clock by returning time in microjiffies.
The subroutine s$read_clock returns the time in microjiffies since the module was
booted.
The subroutine s$clock_date_time returns the time in microjiffies since January 1,

1980 (Greenwich Mean Time).
VOS Release 13.0 supports Continuum-series modules only. However, with Release 13.1 and
later releases that support modules released prior to the Continuum series, you will be able to
use the s$read_clock and s$clock_date_time subroutines on all Stratus platforms,
with the accuracy of the results dependent upon the accuracy of each platforms clock.
Although Continuum-series modules and XA/R Model 300 modules both have a subjiffy
timer, the accuracy with which the Time-of-Day clock measures time at the subjiffy level
depends on the speed of that subjiffy timer. The speed of the subjiffy timer is 12 MHz on
Continuum-series modules, and 8 MHz on XA/R Model 300 modules. Other XA/R-series
modules and all XA2000-series modules do not have a subjiffy timer and therefore have
clocks accurate only to a jiffy.
Note: When you upgrade to the microjiffy Time-of-Day clock, the precision of the
variables in your application may change.
10-1
Using the Interfaces to the Time-of-Day Clock
To upgrade your applications to make full use of the microjiffy Time-of-Day clock, do the
following:
Check your applications calls to the subroutines s$int_date_time, which returns

the time since Greenwich Mean Time in seconds, and s$jiffy_date_time, which
returns the time since Greenwich Mean Time in jiffies. If accuracy to the microjiffy
level would be useful, change those subroutine calls to s$clock_date_time.
Check your applications calls to the subroutine s$read_jiffy_clock, which

returns the time in jiffies since the module was booted. If accuracy to the microjiffy
level would be useful, change those subroutine calls to s$read_clock.
For complete descriptions of the subroutines s$clock_date_time, s$int_date_time,
s$jiffy_date_time, s$read_clock, and s$read_jiffy_clock, see the VOS
10-2
Chapter 10: Upgrading to the Microjiffy Time-of-Day Clock
Chapter 11:
Troubleshooting
11-
This chapter explains some problems you may encounter in the migration process and how
to correct them. It covers the following topics:
problems of inadequate available paging space

performance problems related to cache usage
problems related to process or program virtual memory limits
Diagnosing and Correcting Paging Space Problems

The PA-RISC compilers make extensive use of virtual memory. Virtual memory usage
increases as optimization levels increase.
A block is a unit of code. In VOS COBOL, a block is a program or subprogram. In VOS PL/I
or VOS Pascal, a block is a program, procedure, or function. If a source module contains a
particularly large block, the compiler may consume more virtual memory than the master
disks paging partition and any paging files can accommodate.
VOS monitors paging space usage and issues warning messages in the system error log
during compilations. When the amount of free paging space reaches any one of several
internal thresholds, the operating system writes the following warning message to the system
error log for the current date (>system>syserr_log.date):
time: Paging space has xxxx pages free out of yyyy
Note that paging space problems are usually related to the size of the largest block within a
source program. It is unusual that procedures or functions in a typical modularly designed
program will be large enough to cause paging space problems.
The following diagnostic from the compiler indicates that there was insufficient free paging
space to accommodate virtual memory requirements:
FATAL ERROR 2533 SEVERITY 4
Implementation restriction: there was insufficient virtual memory for
this compilation. To eliminate this error you can break up this
compilation unit, procedure, or function; or the system administrator
can add a paging file or increase this modules paging partition size.
Paging space problems can occur when a number of concurrent compilations are performed
on the same module, and at least one compilation unit consumes excessive virtual memory.
11-1
Diagnosing and Correcting Paging Space Problems
During concurrent compilations, a relatively small compilation unit may be affected because
of the virtual memory usage of another compilation unit.
If you experience paging space problems, make one of the following modifications before
recompiling:
Break up the compilation unit into several smaller compilation units.

Break up the largest block in the compilation unit into several smaller blocks.
Dynamically add paging space by creating a paging file and then using the system
administration command add_paging_file to add that file to the available paging
space. Using a paging file to increase paging space does not require a reboot of the
module.
Increase the paging partition size with the system administration command
update_disk_label, which takes effect at the next reboot of the module.
If you use the add_paging_file command to dynamically increase paging space, also be
sure to include the add_paging_file command in the module_start_up.cm file. Giving
the add_paging_file interactively adds the specified paging file for the current bootload,
and inserting the same command line into the module_start_up.cm file ensures that the
paging file continues to be recognized as a paging file following the next reboot of the
module. See VOS System Administration: Disk and Tape Administration (R284) for the
argument values to use for the create_file command to create a paging file and for more
information on the add_paging_file command.
If you use the update_disk_label command to increase paging space, give the command
with the -pagepart_size number argument. The number you give in this argument will
be set at the next bootload. The default value is 6000. You can change the paging partition
size only in multiples of eight blocks. For example, if the current paging partition size is
256 blocks and you specify 516 blocks, the actual size will be 512 blocks. When you increase
the size of the paging partition, VOS takes blocks from the file partition. Use the
display_disk_info command to make sure there are enough free blocks in the file
partition that can be given to the paging partition. See the manual VOS System
Administration: Disk and Tape Administration (R284) for more information about the
update_disk_label command.
For each simultaneous large compilation, the module needs approximately 16,000 pages of
paging partition. For example, 32,000 pages of paging partition allows the compiling of two
large applications simultaneously, or the compiling of a large application and a number of
small applications simultaneously. (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
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.
From command level, you can monitor paging space availability by using the
display_paging_usage command. Use this command instead of the
display_disk_info command for such monitoring purposes. Using
11-2
Chapter 11: Troubleshooting
Avoiding Inefficient Cache Usage

display_disk_info -long reports the size of the paging partition and how much of that
paging partition space remains available, but it does not include information on paging space
available in paging files. The display_paging_usage command reports on paging space
available both in the paging partition and in any paging files.
You can also monitor paging space availability by using the s$get_paging_usage
subroutine. Use this subroutine instead of s$get_disk_info for such monitoring purposes.
The s$display_disk_info subroutine returns information on paging space in the paging
partition only, but s$get_paging_usage returns information on paging space available
both in the paging partition and in any paging files. See the VOS Subroutines manuals for
information on both of these subroutines.
Avoiding Inefficient Cache Usage

Correctly used, caches reduce the number of accesses to main memory and greatly improve
performance. However, practices that do not take into account how data is cached can cause
performance degradation.
Never have two large data structures, such as large arrays or strings, laid out so that their
virtual addresses are separated by an exact multiple of the cache size. Such data layout may
cause the addresses of these data structures to map to the same cache line, causing frequent
reading from and writing to memory. For example, with a 1Mb cache, if the second data
structure is located at a physical address equal to the address of the first data structure plus 1
Mb, and the source code assigns the value of either one of the data structures to the other, the
source and target addresses used to copy the data will map to the same cache line.
Never have multiple processes using identical copies of the same program. Instead, always
have multiple processes share the same copy of a program. When multiple processes run the
same program, they share the same pages of physical memory and share the same virtual
addresses in the same cache line. This makes the best use of the cache. If, instead, multiple
processes are running separate copies of the same program, VOS uses different pages of
physical memory as if the copies of the programs were actually different programs.
Consequently, each process will have to reload the cache each time it runs the program.
Rarely, two programs running on the same CPU/memory board may, by chance, heavily
access the same virtual addresses. In this case, the cache is flushed frequently, resulting in
some performance penalty. In a multiprocessor environment, you can run the two programs
on different CPU/memory boards by specifying memory pool 0 for one program and memory
pool 1 for the other, as described in Chapter 6, Improving Memory Access by Specifying
Memory Pools. If you own the source code for the programs, you can try rebinding one or
both programs, specifying a different order in which to bind the object files.
Checking for Alignment Faults Causing Uneven Performance

If you have diagnosed and corrected alignment faults and achieved high performance for your
application, you may at times still notice a performance degradation due to alignment fault
handling. Remember that 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 applications
performance.
11-3
Correcting Problems Related to Process and Program Limits
If performance is unsatisfactory in particular circumstances, recheck your application for the

occurrence of runtime alignment faults. For example, if you used the profile command to
determine the alignment fault level initially, you may want to use that command to generate
a new program_name.plist file so that you can check the alignment fault level again.
Refer to the guidelines in Compiling and Binding Applications for Continuum-Series
Modules in Chapter 2 for information on acceptable alignment fault levels.

Release 13.0 and later releases provide process maximum, process initial, and current
command limits that let general users set limits for heap, stack, and total address size for their
programs, and module default command limits that let system administrators set default
limits for a module. Chapter 9, Restricting the Memory Used by Programs or Processes,
describes the types of limits that you can set and the commands and subroutines you use to
set them.
Setting limits too high or too low or not adequately considering the effects of one limit on
another can cause application failure. The following sections describe some problems you
can encounter and some ways to avoid or fix those problems.
Setting Limits Too High

Only a privileged user can update process maximum command limits even for his or her own
processes. If you are a privileged user and need to increase process maximum command
limits, make any increases incrementally rather than increasing the limit by a large amount
that may be much higher than needed.
Caution: A privileged user can increase the process maximum command limits of
user processes without restriction. Setting a maximum limit too high can cause a
fatal runtime error in an application. For more information, see the
update_process_cmd_limits command description in the VOS Commands
Reference Manual (R098).
If your own process maximum command limits have been set too high, you can decrease
them, even as a non-privileged user, by using the update_process_cmd_limits
command or the s$set_current_cmd_limit subroutine.
Setting Limits Too Low

Be cautious about reducing the process maximum command limits for your process. If you
reduce the process maximum limits too far, you may make it impossible for your program to
run. The current program may continue to run successfully to completion, since VOS does
not de-allocate virtual memory that is in use. However, when the program frees that virtual
memory, the new limit you set takes effect. If it is too low, your next run of the program or of
a different program may fail due to insufficient virtual memory.
Note: If you are a non-privileged user, you can not increase process maximum
command limits even for your own process and even if you are the user who decreased
those limits.
11-4
If you are running a particularly large program, and your current command limits, your
process maximum command limits, or the module default command limits are not set high
enough, your program or other user programs may be unable to dynamically allocate enough
memory for successful operation.
For example, in VOS Standard C, the return value of the malloc function indicates whether
the functions attempt to dynamically allocate memory was successful. When the malloc
function successfully allocates memory of the size specified, the function returns a pointer to
the first byte of allocated memory, but if the attempted allocation fails because the specified
amount of memory is not free to be allocated, the function returns the NULL pointer constant.
When you are debugging the failure of a large program, check the pointer value returned by
malloc. If it is the NULL pointer constant, use s$get_current_cmd_limit to return the
setting of each category of current command limits, and then use
s$set_current_cmd_limit to increase those settings as needed. See Chapter 9,
Restricting the Memory Used by Programs or Processes, for information on current
command limits, and see the VOS Subroutines manuals for information on these two
subroutines.
If any other user programs on the module are unable to allocate sufficient memory to run, the
module default command limits for the module may also need to be increased. You must be
a system administrator to use the update_default_cmd_limits command to reset these
limits, as described in Chapter 9.
If your current heap size limit is too small, your program may use the entire heap. In such a
case, the program fails, and the system may generate a large program_name.kp file. To
correct the problem, you need to increase your current command limit for heap size.
In setting any of the virtual memory limits, remember also that the amount of memory a
program uses can be affected by runtime events, such as user input or the amount of data in
a file. Do not set process maximum limits based only on the anticipated current run of the
program, but allow for runtime variability for different runs of the same program.
Setting Inconsistent Limits

Stack space equal to your programs current stack limit is allocated initially for the stack, but
heap size is allocated dynamically as needed. Therefore, be careful that the limits you set for
the total address space and stack space do not restrict the heap allocation you need for your
program. For example, if you set your programs current command limit for heap size to 64
MB and for stack size limit to 64 MB, but for total program size only to 72 MB, your program
may fail. Because the system initially allocates stack space at the specified 64 MB, the 64 MB
you specified for the heap size limit is reduced to the remaining 8 MB of the 72 MB total
program size available. When the heap attempts to exceed the 8 MB available, the program
fails. In this case, you need to increase your current command limit for total program size to
accommodate the heap size limit you specified.
Running Programs on Modules with Insufficient Default Limits

The module default command limits determine your programs heap, stack, or program size
limits if you do not explicitly set such limits with the s$set_current_cmd_limit
subroutine or at bind time with bind command arguments or binder control file directives.
11-5
Because the default limits are settable by a system administrator, they may differ from
module to module. Do not assume that a program that runs successfully on one
Continuum-series module will run successfully on another unless you are sure that the default
process command limits are set to an adequate value on the other module.
You can display, update, or override module default command limits as follows:.
You can use the list_default_cmd_limits command with the module argument
to display the default command limits for a module.
If you are a system administrator, you can update the default command limits for the
module, using the update_default_cmd_limits command.
If you are a privileged user, you can override the default limits, including the process
maximum limits, by explicitly setting limits of your own with the
update_process_cmd_limits command or the s$set_current_cmd_limit
subroutine.
Note: If you are a general non-privileged user, you can increase any of your own
processes initial command limits but only within the bounds of the maximum module
default command limits, and you cannot increase any of your processes maximum
command limits. Regardless of how you are registered (as a privileged user or a
member of the SysAdmin group), you cannot override the default command limits for
the module by using bind command arguments or binder control file directives. At
bind time, you can specify current command limits, but only within the bounds set by
the default limits for the module.
11-6
Appendix A:
Migrating Forms Management System (FMS) Applications
A-
This appendix describes how to edit, recompile and rebind Forms Management System forms
using an FMS Forms Editor. It assumes that you are familiar with the VOS Forms
Management System manuals and the descriptions of the nls_edit_form and edit_form
commands in the VOS Commands Reference Manual (R098)
If your application uses Forms Management System (FMS) forms, you must recompile and
rebind the forms for the PA-RISC processor.
For best performance, Stratus recommends that you also edit the .form files to use longmap
data alignment. However, you can recompile the forms without editing them in the following
cases:
you created the .form files using longmap data alignment on an i860 processor
you migrated your applications from a processor in the MC68000 family to an i860
processor, and edited them to use longmap alignment at that time
your forms are currently shortmap-aligned and you choose to retain shortmap
alignment. In this case, if you experience unsatisfactory performance later, you can edit
and recompile the forms for longmap alignment at that time.
Choosing the Appropriate Forms Editor

To edit and recompile FMS forms, use the nls_edit_form or edit_form command,
choosing the same command that was used to create the forms. The nls_edit_form
command invokes the newer, enhanced Forms Editor and compiles the forms. The
edit_form command invokes the older Forms Editor and also compiles the forms.
In this appendix, arguments and values described for nls_edit_form are also available
with edit_form unless otherwise indicated.
Editing and Recompiling FMS Files

For migrating an FMS application to the PA-RISC processor, the method to use depends on
whether you are changing the data alignment in the .form files and how many .form files
the application contains. If the .form files already have the data alignment you want, use the
nls_edit_form command or edit_form command with the -no_edit argument to
recompile each form and to produce new object and include files.
A-1
If you are changing the .form files to longmap data alignment, use the nls_edit_form
command or the edit_form command interactively to edit each .form file, to recompile the
form, and to produce new object and include files. Give only the input_file argument and
the -processor processor_name argument from the command line, specifying pa7100
as the value for processor_name. Do not give other arguments from VOS command level.
Many of the command arguments given from VOS command level work only when you are
creating new forms. Because you are working with existing forms, VOS ignores most other
arguments you specify on the command line (so that any abbreviations you might have in
your abbreviations file do not change existing forms in ways you do not intend). After
you invoke the command, use <Menu> S, and choose options on the Form Options form.
Many of these options provide the same choices available in the command line arguments.
If you are changing the .form files to longmap data alignment in applications that have many
.form files, write a command macro that edits each file by means of the editing requests of
the line_edit command. Then use the nls_edit_form or edit_form command with the
-no_edit argument to recompile each form and produce new object and include files.
The following sections briefly explain how to migrate an FMS application to the PA-RISC
platform using the Form Options form or a VOS command macro.
Using the Form Options Form

To invoke the Forms Editor to recompile a form for the PA-RISC processor, the
nls_edit_form command line is:
nls_edit_form input_path -processor pa7100
The input_path argument is the path name of a form definition input file.
The value pa7100 indicates that the forms are being compiled to run on the PA-RISC
processor.
After executing the command line to invoke the Forms Editor, use <Menu> S to display the
Form Options form. In the Form Options form, use default values or cycle any field to
the value you want.
Cycle the PRODUCE INTO field to yes to create a new include file for each language specified
in the language options.
Cycle the LONGMAP field to yes to cause the include files generated by the Forms Editor to
follow longmap alignment rules and to cause the object files produced to expect
longmap-aligned data.
How the value you select for the LONGMAP field affects include files depends on the language
you are using.
In VOS Standard C, VOS C, and VOS Pascal, the include files created contain explicit
longmap or shortmap keywords in the field-values structures.
In VOS PL/I, these keywords are generated only if the value for the TEMPLATE field in
the Form Options form is the default value, yes. If you cycle the value in the
TEMPLATE field to no, you must add the appropriate keywords manually.
A-2
Appendix A: Migrating Forms Management System (FMS) Applications
VOS COBOL and VOS FORTRAN do not allow the definitions of structure templates.
In VOS COBOL and VOS FORTRAN, the Forms Editor generates an include file for
the body of the structure, which you include in your program under the definition of the
structure itself, such as in this VOS COBOL example:
01
my_structure.
copy 'struct_info.incl.cobol'.
Note that, in VOS COBOL, the Forms Editor cannot insert the longmap or shortmap
keywords for you. You must add the longmap or shortmap keywords manually.
Cycle one or more of the COBOL, PASCAL, PL/I, C, or FORTRAN fields to yes to specify the
language or languages for which you want to produce new include and object files.
Select a value for the FLAG WORD SIZE cycle field, available for nls_edit_form only, not
for edit_form. The FLAG WORD SIZE field specifies the size of the bit flag words in the
field-values file. The Forms Editor organizes the VOS Pascal boolean data type, the VOS
PL/I bit(1) data type, and the VOS Standard C and VOS C bit data type into bit flag words.
The possible values are 32, 16, and 8. The default is 32. Binary fields that are larger than the
flag word size are not allowed in any language. In VOS Standard C programs, always use 32,
the default. In VOS C programs, eight-bit flag words are not supported. If you use 16-bit flag
words in VOS C, the compilation unit must include the following options:
#options bit_field_size short;
#options bit_field_align short;
Select a value in the SORT BY ALIGNMENT cycle field. By default, the Forms Editor
rearranges the elements of a structure to minimize the amount of padding that has to be added
when following longmap rules. If you do not want the elements of structures rearranged in
this manner, cycle the value in the SORT BY ALIGNMENT field to no.
Using a Command Macro to Edit the Forms

If the application you are migrating to the new processor has many .form files, you may want
to write a command macro that edits each file. Write the command macro to accept a file
name as an argument. In the command macro, call the line_edit command, using the
specified file name for the test_file_name argument, and then specify Line Editor
requests to perform the editing. Use the command macro to add the options
longmap_into_buffer and sort_into_by_alignment after the produce_into
option in each .form file. For an example of how these options should appear in your .form
files, compile one form interactively using the Form Options form to choose longmap data
alignment, and then look at the resulting .form file.
Caution: Changes made to the .form files by a command macro cannot be
retracted. When you write or modify a command macro, always test it on a copy
of a file before using it to edit files that you need.
For a command description of the line_edit command, see the VOS Commands Reference
Manual (R098). For further information on how to write command macros and how to use
the line_edit command in command macros, see the VOS Commands Users
Guide (R089).
A-3
Binding Applications Compiled with nls_edit_form
When you complete editing the .form files with the command macro, use the
nls_edit_form or edit_form command with the -no_edit argument to recompile the
forms.
Binding Applications Compiled with nls_edit_form

If you use the command nls_edit_form instead of edit_form to compile the forms, you
must ensure that the following directory is in your object library search paths when you bind
the application:
(master_disk)>system>nls_fms_object_library
A-4
Appendix A: Migrating Forms Management System (FMS) Applications
Appendix B:
Finding and Correcting Runtime Alignment Faults
B-
This appendix briefly describes how to use VOS commands and VOS System Analysis
subsystem requests to detect and diagnose runtime alignment faults and how to use
information in the program_name.list file to further investigate the cause of a runtime
alignment fault.
Even if an application compiles and binds without error, in a few cases it may generate
runtime alignment faults that the compiler could not find. For example, a misaligned pointer
is a common cause of a runtime alignment fault, such as when a VOS Standard C application
uses an integer that is not mod4-aligned to increment a pointer that points to a longmap long
int integer.
The CPU detects such runtime alignment faults and invokes a VOS fault handler that corrects
the access with no user intervention. However, the fault handler may have to generate
hundreds, and perhaps thousands, of extra instructions to correct a runtime alignment fault
and therefore may noticeably affect the performance of your application.
This appendix describes the following commands for detecting and diagnosing runtime
alignment faults.
the set_alignment_fault_mode command, which causes a program to go to break

level when an alignment fault occurs
the profile command, which includes alignment fault information in the data it
generates about a program
The appendix also describes the following VOS System Analysis subsystem requests
the log_alignment_faults and display_alignment_faults requests, which

log and display alignment faults for processes running on the current module
the process, match, and who requests, which provide information you can use to
identify the program that is generating runtime alignment faults
the use_file and where requests, which let you analyze a non-running program for
the cause of alignment faults
the disassemble request, which displays the assembly language instructions for
source code associated with an alignment fault
B-1
Using the set_alignment_fault_mode Command
The last section of the appendix, Using Information in the .list File, explains how to
use information in the listing file, generated at compilation when you give the -list
argument, to further diagnose and track the cause of a runtime alignment fault.
Using the set_alignment_fault_mode Command

The set_alignment_fault_mode command is a debugging tool for finding and
diagnosing runtime alignment faults. You use the command to set a mode, controlling
whether alignment faults are identified for a given process.
The command has one argument, -fault, which defaults to yes. When the command is
issued in a particular process, any program run from that process will go to break level when
it encounters an alignment fault. When this occurs, you can use the VOS Symbolic Debugger
to track the cause of the alignment fault.
For example, if a program module customer_accounts.pm generates an alignment fault,
it runs successfully but at a performance penalty. To find the line of source code associated
with the alignment fault (line 48 in this example), first give the
set_alignment_fault_mode command to set alignment fault mode on for your current
process.
set_alignment_fault_mode
Then run the program.

customer_accounts
During program execution, when an alignment fault occurs, the program goes to break level
with a message similar to the following.
An attempt has been made to access unaligned data.
Error occurred in procedure customer_accounts, line 48.
Command was customer_accounts.pm.
In the message, the term procedure refers to the object module in which the error occurred.
In this case, the object module is customer_accounts.obj.
You are then prompted for a break-level request. Choose debug. At the db? prompt, give the
src debugger request. The debugger displays the line number and the source code on that
line of customer_accounts.c
Request? (stop, continue, debug, keep, login, re-enter) debug
Entering debug.
New language is c.
db? src
48
temp = *arg;
db?
You can then give additional debugger requests to further trace the fault by determining, for
example, where arg is used as an argument and what values are passed.
B-2
Appendix B: Finding and Correcting Runtime Alignment Faults
Using the profile Command
To turn off alignment fault mode, issue the set_alignment_fault_mode command with
the -no_fault argument.
set_alignment_fault_mode -no_fault
See the VOS Commands Reference Manual (R098) for command descriptions of the debug
command and the set_alignment_fault_mode command.
Using the profile Command

To use the profile command to generate information on runtime alignment faults, follow
these steps.
1. Compile any source modules for your application using either the -qc argument of the
VOS Standard C compiler or the -cpu_profile argument of the VOS COBOL, VOS
Pascal, or VOS PL/I compiler. For example, to compile the source module
customer_accounts.c, give the cc command with the -qc argument and other
relevant arguments.
cc customer_accounts -qc -processor pa7100 -mapping_rules
longmap/check -table -list -full
2. Bind your object modules with the bind command, using the
-profile_alignment_faults argument. When you use the -qc or the
-cpu_profile compiler argument without the bind commands
-profile_alignment_faults argument, code coverage, time and page fault
information is tracked. The -profile_alignment_faults argument overrides
page fault tracking and tracks alignment faults instead. The following example binds
the object modules customer_accounts.obj and overdue.obj and tracks
alignment faults rather than page faults.
bind customer_accounts overdue -processor pa7100
-profile_alignment_faults
Because the example omits the -pm_name argument, the program module created has
the same name as the first object module specified, but has the suffix .pm instead of
.obj.
3. Run your program module. For example:
customer_accounts
Running the program generates, in your current directory, a file named

customer_accounts.profile that you use as input for the profile command.
4. Give the profile command, specifying the .profile file to use as input and using the
-list argument. You can omit the .profile suffix for the input file. For example:
profile customer_accounts -list
The profile command generates a file named customer_accounts.plist in your

current directory.
B-3
Using the VOS System Analysis Subsystem
5. Use the VOS display command or one of the VOS text editors to view the .plist
file. For example
emacs customer_accounts.plist
The ALIGN FLTS column gives the number of alignment faults generated, and the
program listing to the right of that column shows the line number and source code
associated with the fault. (The COUNT column shows the number of statements
executed, and the CPU(ms) column shows the CPU time used, in milliseconds.)
COUNT
.
.
.
2000
CPU(ms) ALIGN FLTS
105.57
1000
48
temp = *arg;
For more information on the profile command, its several modes, and its other arguments,
see the profile command description in the VOS Commands Reference Manual (R098).

The VOS System Analysis subsystem (the analyze_system command and its requests)
provides detailed information for diagnosing runtime alignment faults. You must be
registered as a privileged user to use this subsystem.
The subsystem is a versatile tool for alignment fault analysis, enabling you to do such things
as log and display the alignment faults generated by an application, load a non-running
program module for analysis, list information about processes running on a module, and
specify particular processes to analyze.
Prior familiarity with the VOS System Analysis subsystem and the terminology used in the
output of its requests is helpful in using the subsystem. To diagnose runtime alignment faults
for a non-running application, you also need to know what program modules the application
uses.
If you are unfamiliar with the subsystem, you may want to diagnose runtime alignment faults
by using the commands documented earlier in this appendix, such as the
set_alignment_fault_mode command, to determine what .pm file in your application
generated the alignment fault. With set_alignment_fault_mode, your application stops
when it generates an alignment fault, enabling you to investigate the fault with VOS
Symbolic Debugger.
For detailed descriptions of most of the analyze_system requests referred to in this section,
see the VOS System Analysis Manual (R073). The log_alignment_faults and
display_alignment_faults requests are not yet documented in the VOS System Analysis
Manual (R073) at Release 13.0.
To prepare to use the VOS System Analysis subsystem, compile and bind your application
with the -table argument. Using the compilers -table argument sets the compilers
optimization level to 1, the level at which debugging is easiest. The bind commands
B-4

-table argument causes the binder to copy the symbol table information, enabling later use
of the VOS Symbolic Debugger.

To invoke the VOS System Analysis subsystem, enter the analyze_system command. The
subsystem displays information similar to the following.
VOS Release 13.0, analyze_system Release 13.0
Current process is 236, ptep 815C9000, person_name.group_name
as:
Make a note of the process number and PTEP (process table entry pointer) of your current
process for later use.
At request level, indicated by the as: prompt, you can use any of the analyze_system
requests.
Logging Alignment Fault Information

To find and diagnose runtime alignment faults with the VOS System Analysis subsystem,
first log the occurrence of the faults on the current module. Because you can display
information on only the most recent 255 instances of an alignment fault, do the following:
Choose a time of low usage on the module, when other programs are not likely to be
generating frequent alignment faults that will fill the log display buffer with unrelated
log entries.
Confirm that no other user is currently using information in the alignment fault log.
Since there is only one alignment fault log per module, you need to be sure that
resetting the log or restricting its contents does not interfere with alignment fault
tracking by another user.
Alert other users on the module that you are using the log so that they do not
inadvertently interfere with your alignment fault tracking by resetting or restricting the
logs contents.
To determine if alignment fault logging is taking place on the current module, invoke the
display form of the log_alignment_faults request.
as: log_alignment_faults -form
------------------------------ log_alignment_faults -----------------------------ptep:

-mode: on
-reset: yes
In this example, the -mode argument is set to on, which means that alignment faults are
currently being logged.
B-5
Leave the -reset argument value as yes to delete all current log entries. If you want to log
alignment fault information only about programs run by your current process, specify the
PTEP number of your current process. Press <Enter> to start and reset the log.
If -mode is set to off instead, alignment faults are not currently being logged. Cycle the
value to on, specify the PTEP number of your current process if you want to log alignment
fault occurrences only for that process, and press <Enter> to start and reset the log.
Now run your application. The occurrence of any runtime alignment faults are logged.
Displaying Alignment Fault Information

To display information on the most recent 255 alignment faults logged, use the
display_alignment_faults request as follows:
as: display_alignment_faults -no_brief
If you did not restrict logging to one process by specifying a PTEP when you issued the
log_alignment_faults request, the output of display_alignment_faults
-no_brief is similar to the following:
10001 alignment faults have been logged. Up to 256 will be displayed.
ptep
# of times
818ED2E0
11
8197DAC0
22
818EEB40
22
813FCC40
117
823C6920
8
81E7FC60
75
Fault instruction
pc: 80631D30 (object_module_name+320)
pc: 00008208 (analyze_system+208)
pc: 8043EA2C (object_module_name+186C, line 464)
pc: 00006848 (user address in another process)
Trace complete.
as:
The preceding output shows alignment faults for system and user processes. (System
processes can generate alignment faults when misaligned argument data is passed by user
programs to kernel routines.) The output contains the following information.
the PTEP (Process Table Entry Pointer) for each process generating alignment faults
the number of times an alignment fault occurred for each process
the hexadecimal address of the program counter (pc: address), which is the address
where the fault occurred. User programs occupy addresses between 800x and
3FFFFFFx; the other programs are system programs
in parentheses, the name of the object module generating the fault, and the statement
offset
for user programs still running in the current process (even if they are not currently
using CPU time), the source code line number associated with the fault. If you use the
process request to set a different process to be analyzed, the output of
display_alignment_faults -no brief also shows line number information for
programs currently running in that process. See the discussion of the process request
B-6
in Using analyze_system from a Process That Did Not Run the Program later
in this chapter for information on designating a process to be analyzed.
for alignment faults generated by other user processes not specified as the process to be
analyzed, the message user address in another process instead of the object
module name, statement offset, and line number
Determining Which Program to Analyze

Next you must determine which process listed in the log (and therefore which program)
caused the alignment fault you want to find and correct. Before attempting to diagnose the
alignment fault, always verify that you are using the correct log entry by checking the PTEP
of the process listed.
The following two sections describe how to determine which log entry to use when you
invoke analyze_system from the same process that ran the program and when you invoke
analyze_system from a different process.
Using analyze_system from the Same Process That Ran the Program
When a program module completes running, you can invoke the analyze_system
command from the same process in which you ran the program.
Before giving the display_alignment_faults request, be sure you know the PTEP
number of your current process.The PTEP number of your current process is displayed when
you invoke analyze_system, but you can also display it by giving the match request
followed by the who request. In the output, your current process is listed with an asterisk. For
example, if your user name is Joan_Reynolds, give the match and who requests as follows
to list all processes of yours on the current module.
as: match Joan_Reynolds
as: who
* 236 815C9000 Joan_Reynolds.SysAdmin, on CPU28
329 815ED920 Joan_Reynolds.Administration
In the preceding example, your current process is process number 236, with a PTEP number
of 815C9000.
Next give the display_alignment_faults request with the -no_brief argument. The
log entries displayed include an entry similar to the following.
ptep
# of times
.
.
.
815C9000
117
Fault instruction
pc: 00008208
(analyze_system+208)
Because the program module has run to completion and is no longer loaded, the fault is
B-7
attributed to the analyze_system command you are using to track the fault. To correctly
identify the log entry to use, you must be sure of the following:
The PTEP number in the displayed log entry must match the PTEP of your current
process. The PTEP number of the log entry in the preceding example is 815C9000.
Your current process must not have run another program module that may have
generated the fault since you reset the log. When analyzing a program that has already
run to completion, you need to be familiar with what other program modules your
process may have run. You may need to examine source code or command macros of
a multi-program application to determine what program modules it uses.
If the PTEP number in the log entry matches the PTEP number of your current process, and
your current process has not run other program modules since you reset the log, you have
identified the correct log entry to use.
Using analyze_system from a Process That Did Not Run the Program
You can view alignment fault log entries from a process other than the process that runs your
program. For example, if you are working in a Window Terminal environment, you can run
your program from one process and then, from another process in a different window, invoke
analyze_system to display the alignment fault log entries.
When you display alignment faults from a different process from the one that is already
running your program, use the process request to indicate which process to analyze, and
then give the display_alignment_faults request. See the process request description
in the VOS System Analysis Manual (R073) for information on how to specify any of the
following to set the process to be analyzed:
the process number

the process name
a user name identifying the process
the CPU on which the process is running
the parent process of your current process
If you invoke analyze_system from a different process and do not indicate the process to
analyze, any alignment fault log entry your program generates is of limited usefulness and
may be very similar to other entries in the log. For example, the output of
display_alignment_faults -no_brief would show a log entry similar to the
following, containing the words user address in another process rather than the
program name and line number associated with the fault occurrence.
ptep
# of times
.
.
.
8240B700
199
Fault instruction
pc: 00008208 (user address in another process)
To obtain the information necessary to indicate the process to be analyzed, use the who
request to list information about the processes running on the module. If you already know
the PTEP of the process you want to analyze, first give the match request, specifying that
B-8
PTEP. The match request limits the output of the subsequent who request to information
about the process associated with the PTEP you specify.
as: match 82470B700
as: who
1914 82470B700 person_name.group_name, on CPUnumber
as:
The first number in the output is the process number. You can then use that process number
to set the process to be analyzed.
as: process 1914
After you set the process to be analyzed and then invoke display_alignment_faults
-no_brief, a displayed log entry for that process contains the object module name and
source code line number associated with an alignment fault occurrence.
For example, the output of display_alignment_faults -no_brief would include an
entry similar to the following.
ptep
# of times
.
.
.
82470B700
117
Fault instruction
pc: 00008208 (customer_accounts+208, line 48)
Note: the process request loads symbol table information for a program running in
the specified process at the time you give the process request, not at the time you
start the program running. Therefore, always run the program first, then set the process
to be analyzed, and then display the log by using display_alignment_faults
-no_brief.
If your program has run to completion and is no longer loaded, the command
display_alignment_faults, with the -no_brief argument, displays no object module
or line number information about the fault. (Note that this also occurs if you compiled the
program without using the -table argument.) For example:
ptep
# of times
.
.
.
82470B700
117
Fault instruction
pc: 00008208
(8208)
If the program is no longer loaded, use the use_file request described in the next section
to load the program into user address space so that you can examine the code at the address
associated with the fault.
Analyzing a Non-Running Program

The VOS System Analysis subsystems use_file request loads a program module that is
not actively running.
B-9
Note: Accurate determination of which program module generated an alignment fault

log entry for a non-running program depends on your knowing what program modules
the process causing the fault has run. Also, the version of the program module you load
must be identical to the version that generated the fault; if it is not, source code line
number references may be inaccurate.
For example, if you determine that the program module customer_accounts.pm is the
program module that generated alignment faults, load that program module as follows:
as: use_file customer_accounts
The use_file request has no output except a line of VOS and analyze_system release
information, followed by the as: prompt.
At the as: prompt, give the where request with the address of the alignment fault, as listed
in the earlier output of the display_alignment_faults request. The output identifies the
line number associated with the alignment fault in the source module.
as: where 8208
00008208 at customer_accounts+208, line 48
as:
You can then give the VOS display command, preceded by two periods, from within the
subsystem to display the source module line associated with the fault. The following example
assumes the source module is in your current directory.
as: ..display customer_accounts.c -first_line 48 -last_line 48
path_name>customer_accounts.c 95-01-21 08:47:57 EST
temp = *arg
Examining Assembly Language Code

If you are familiar with assembly language, the disassemble request may be useful in
further examining the source of an alignment fault. For example, after loading the
non-running program with the use_file request, give the disassemble request followed
by either the address of the source module line associated with the fault or the program name,
a commercial at sign (@) and the line number associated with the fault.
In the following example, specifying the address associated with the fault produces output
showing, in assembly language and hexadecimal format, the particular assembly language
instructions for the portion of line 48 that generated the fault.
as: use_file customer_accounts
VOS Release 13.0, analyze_system Release 13.0
as: disassemble 8208
/* Part of line 48
00008208 14210001 ld.l
+0(r1),r1
0000820C 1C7F0FE5 st.l
r1,-28(r3)
B-10
Using Information in the .list File
In the following example, specifying the source module line number associated with the fault
produces output showing, in assembly language and hexadecimal format, the particular
assembly language instructions for that entire line.
as: disassemble customer_accounts@48
/* Line 48
00008204 14610011 ld.l
+16(r3),r1
00008208 14210001 ld.l
+0(r1),r1
0000820C 1C7F0FE5 st.l
r1,-28(r3)
In the output of both examples, ld.l and st.l access a longword (4-byte item). If this 4-byte
item is misaligned, an alignment fault is the result. While not providing conclusive evidence
for the cause of the fault, a look at this assembly language code identifies a possible cause to
be explored further.
The output of the VOS System Analysis disassemble request is similar to the assembly
language information provided in the listing file when you use both the -list and -full
compiler arguments, and also to the output of the VOS Symbolic Debuggers disassemble
request.

You can use information in the listing file, generated at compilation when you give the -list
argument, to further diagnose and track the cause of a runtime alignment fault. For example,
suppose a program module customer_accounts.pm generates an alignment fault that you
have traced to the following line in the VOS Standard C source module
customer_accounts.c.
temp = *arg;
Use the VOS display command to check the listing file to find all the instances where arg
is accessed.
display customer_accounts.list -match arg -no_header
Suppose that the relevant portions of the display commands output are the following:
36
void report ( long $longmap *arg )
48
temp = *arg;
.
.
.
Prototype Arguments: arg
->long
arg
parameter
4 4 0010 ->long
at 36
From this output, you know that arg is longmapped, but you also know that arg is an
argument to the function report. You therefore might need to use the display command
with its -match argument several more times to investigate the fault further. For example,
you might first display all instances of the function report to see what argument values are
being passed. If members of several different structures were found to be the argument values
for the report function, you might then display all instances of each of those structure
B-11
members to see how each is declared, what values are assigned to them, and how they are
used.
A possible finding might be a misalignment of one of the structure members. For example,
the following excerpts from a listing file show that the offset of member_b is 4 (the value in
the A column) and the offset of member_d is 2, suggesting that member_d is shortmapped.
NAME
STORAGE
SIZE A
.
.
.
member_b
.
.
.
member_d
LOC
TYPE
4 4
long
4 2
long
You would then check the source code to confirm that member_d is shortmapped.
To correct such an alignment fault, use the information on data alignment in Chapter 3,
Addressing Alignment Issues. Some options to correct the fault might include the
following:
explicitly declaring the shortmapped structure to be longmapped

padding or reorganizing the structure to achieve correct alignment of its members
passing member_d by value instead of by reference
assigning member_d to a temporary variable that is correctly aligned and can be safely
passed by reference
B-12
Index
Index-
A
Access modes
e$invalid_access_mode error
code, 8-3
s$connect_vm_region modes
for debugging with
s$query_vm_lock, 8-2
for exclusive non-sequential
caching, 7-6
for exclusive-sequential caching, 7-5
for exclusive-use locking, 7-6
for machine-independent locking, 8-2
for memory-ordering support, 7-5
for shared non-sequential caching, 7-6
add_paging_file command, 1-4, 11-2
Address space layout, 9-2
Aliased values with defined storage, 4-7
aligned attribute, 3-17
Alignment
argument and parameter compatibility in
VOS PL/I, 3-15
checking for inserted padding, 3-5
checking structures not explicitly
aligned, 3-6
correcting mismatches in subroutine
arguments, 3-14
deciding on a strategy, 2-4
for migrating i860-based
applications, 2-4
for migrating MC68000-based
applications, 2-4
inheritance, 3-11
VOS Pascal usage, 3-11
VOS PL/I usage, 3-12
VOS Standard C usage, 3-11
longmap definition, 3-2
padding in VOS Standard C, 3-4
performance penalties for misalignment, 1-1
sample longmapped structure, 3-2
sample shortmapped structure, 3-3
shortmap definition, 3-2
sorting structure elements by alignment in
FMS, A-3
specifying
for FMS include files, A-2
in communications-based
applications, 3-10
with alignment attributes, 3-6
with compiler command arguments, 3-5
with compiler directives, 3-5
string data, 3-17
using longmap rules, 1-2
using shortmap rules, 1-2
with untyped storage sharing, 3-18
Alignment faults at runtime
finding and correcting, B-1
identifying source module line
number, B-10
identifying the correct log entry, B-8
interpreting log entries, B-6
logging, B-5
recommended maximum number, 2-8
variation when different code paths
execute, 11-3
analyze_system requests, 2-9, B-4
disassemble
interpreting output of, B-11
with use_file request, B-10
display_alignment_faults, B-6
log_alignment_faults, B-5
match, B-7, B-8
preparing to use, B-4
process, B-8
to select the process to analyze, B-8
using after a program runs, B-9
use_file, B-9
where, B-10
who, B-7, B-8
arglistptr obsolete built-in function, 4-8
Assembly language code analysis, B-10
Asynchronous data modification, 4-2
Attributes
like in VOS PL/I, 3-13
specifying data alignment
for aggregate data types, 3-6
for scalar data types, 3-6
Index-1
Index
type in VOS PL/I, 3-13
volatile, 4-2
alternatives to, 4-3
using with locks, 4-3
Automatic variables after longjmp function
call, 4-6
B
Based storage
avoiding for overlays of incompatible data
types, 4-7
compatible alignment when referenced by
pointers, 3-17
bind command
arguments specifying virtual memory
limits, 1-4, 9-4
-load_point argument, 9-5
-max_heap_size argument, 9-4
-max_program_size argument, 9-4
-max_stack_size argument, 9-4
overriding module default command
limits, 11-5
argument, 2-8, 2-9, B-3
-size argument, 9-5
-stack_fence_size argument, 9-5
-stack_size argument, 9-5
-table argument, B-4
Bind directives for shared virtual memory
database
define, 9-5
high_water_mark, 9-5
Bit field overlays, 4-8
Bit flag word size in FMS, A-3
Bit-string data
aligned, 3-17
length, 3-17
BREAK condition, 4-2
Built-in functions
paramptr, 4-8
rel, 4-8
unspec, 4-8
C
C language. See VOS Standard C
Caches
cache lines, 7-1
determining boundaries of, 7-2
virtual address indexing to, 7-3
cache misses, 7-1
cache sizes on Continuum, 7-2
caching policies
exclusive non-seqential, 7-6
Index-2
exclusive-sequential, 7-5
shared non-seqential, 7-6
supporting memory-ordering, 7-5
data, 7-5
default VOS behavior, 6-1
direct map, 1-3
efficiently using
avoiding duplicate programs, 11-3
avoiding false sharing, 7-4
avoiding faulty data layout, 7-4, 11-3
fully packing cache lines, 7-4
minimizing data sharing, 7-3
improving performance with, 7-1
instruction, 7-5
virtually indexed, 1-3
cc command
-qc argument, 2-8, 2-9, B-3
CHARACTER functions in VOS FORTRAN, 5-4
Character-string data alignment, 3-18
Clocks
subroutine interfaces to, 10-2
Time-of-Day, 1-5, 10-1
Command macros
specifying memory pools in, 6-3
to edit multiple FMS forms, A-3
Command virtual memory limits. See Virtual
memory limits, command
Commands
add_paging_file, 1-4, 11-2
analyze_system, 2-9, B-4
bind
arguments specifying virtual memory
limits, 1-4, 9-4
-load_point argument, 9-5
-max_heap_size argument, 9-4
-max_program_size
argument, 9-4
-max_stack_size argument, 9-4
overriding module default command
limits, 11-5
argument, 2-8, 2-9, B-3
-size argument, 9-5
-stack_fence_size
argument, 9-5
-stack_size argument, 9-5
cc
compiler
-check_uninitialized
argument, 5-4
-cpu_profile argument, 2-8, B-3
-mapping_rules argument, 3-5
Index
-production_table
argument, 4-6, 5-1
-table argument, B-4
create_file to create paging files, 11-2
debug
continue request, 4-6, 5-2
set request, 4-6, 5-2
with floating-point exceptions, 5-3
display
tracing an argument in .list
file, B-11
using from System Analysis
subsystem, B-10
display_disk_info, 2-2, 11-2
display_error, 3-5
display_paging_usage, 1-3, 11-2
edit_form, A-1
line_edit, A-2, A-3
list_default_cmd_limits, 1-4, 2-3,
9-4, 11-6
list_process_cmd_limits, 1-4, 2-7,
9-3, 9-4
list_users for memory pool
information, 6-4
login
-memory_pool argument
error message with one memory
pool, 6-4
for subprocess login, 6-3
nls_edit_form, A-1
profile, 2-8, 2-9, 11-4, B-3
set_alignment_fault_mode, 2-9,
B-2
break-level requests, B-2
turning off the mode, B-3
start_process
error message with one memory
pool, 6-4
-memory_pool argument, 2-7, 6-3
update_default_cmd_limits, 1-4,
2-3, 9-4, 11-5, 11-6
update_disk_label, 1-4, 11-2
update_process_cmd_limits, 1-4,
2-7, 9-3, 9-4, 11-4
Communications-based applications
alignment of structures, 3-10
using latest include files, 3-11
Compiler commands
-check_uninitialized
argument, 5-4
-cpu_profile argument, 2-8, 2-9
-mapping_rules argument, 3-5
-production_table argument, 4-6, 5-1
-table argument, 4-5, 5-1
Compiler directives
no_default_mapping, 3-6
to specify data alignment, 3-5
Compiler options
for specifying alignment, 3-5
untyped_storage_sharing, 4-8
Compiling
FMS .form files, A-1
multiple large applications, 2-1, 11-1
with longmap mapping rules, 2-7
with shortmap mapping rules, 2-9
Conditional precompilation, 8-3
Continuum features affecting migration, 1-1
Converting structures to longmap, 3-18
Correcting incorrect or inefficient coding, 2-6
CPU/memory boards, 6-1
create_file command to create paging
files, 11-2
Current command limits, 9-4
D
Data alignment
See Alignment
Data caches, 7-5
Dead space, 9-2
debug command
continue request, 4-6, 5-2
set request, 4-6, 5-2
with floating-point exceptions, 5-3
Debugging
floating-point exceptions, 5-3
runtime alignment faults, B-2
virtual memory locks, 8-2
with -table compiler argument, 4-5
define bind directive, 9-5
Defined storage
avoiding performance penalty for defined
overlays, 4-7
using for overlays of incompatible data
types, 4-7
Direct map cache, 1-3, 7-1
disassemble System Analysis request
interpreting output of, B-11
with use_file request, B-10
display command
tracing an argument in .list file, B-11
using from System Analysis
subsystem, B-10
display_alignment_faults System
Analysis request, B-6
display_disk_info command, 2-2, 11-2
display_error command, 3-5
display_paging_usage command, 1-3,
Index-3
Index
11-2
E
edit_form command, A-1
Editing FMS forms, A-3
Exception handlers in floating-point
calculations, 5-3
Exclusive-use locking, 4-4
Expressions
breaking up big expressions to avoid
rounding, 5-3
misaligned variables in relational
expressions, 3-18
F
Fault handlers for runtime alignment faults, B-1
Fences, 9-2
Files
.list, B-1
displaying all instances of a data
item, B-11
interpreting, B-11
.plist
generating, B-3
viewing, B-4
.profile, B-3
Flag words size in FMS, A-3
Floating-point values
exception-handling, 5-3
precision on different platforms, 5-2
FMS. See Forms Management System
.form files, A-1
editing with a command macro, A-2
Form Options form required for
revising, A-2
Form Options form in FMS, A-2
Forms Management System, A-1
Form Options form required for revising
forms, A-2
object library for NLS, A-4
FORTRAN language. See VOS FORTRAN
Functions
VOS PL/I parampter, 4-8
VOS PL/I rel, 4-8
VOS PL/I unspec, 4-8
VOS Standard C
longjmp, 4-6
malloc, 11-5
setjmp, 4-6
G
Gaps in structures, 3-5
Index-4
H
Heap space
controlling growth of heaps, 9-3
correcting inconsistent limits, 11-5
default per-command limit, 2-3
default per-process limit, 2-3
different address space usage on
Continuum, 9-2
setting limit too small, 11-5
high_water_mark bind directive, 9-5
I
Include files
generated by the FMS Forms Editor, A-3
using for accurate structure
declarations, 3-10, 3-11
Increasing paging space, 1-4
Inheritance of alignment, 3-11
Instruction caches, 7-5
J
Jiffies, 1-5, 2-7, 10-1
K
.kp files, 11-5
L
like attribute
alignment rules for, 3-13
used with mixed structures, 3-12
Limits
correcting inconsistent limits, 11-5
current command limits, 9-4
module default command limits
differing among modules, 11-6
displaying and setting, 9-4
process initial command limits, 9-4
process maximum command limits, 9-3
setting too high, 11-4
setting too low, 11-4
virtual memory limits for commands, 1-4
virtual memory limits for processes, 1-4
line_edit command, A-2, A-3
.list file, B-1
displaying all instances of a data item, B-11
interpreting, B-11
list_default_cmd_limits
command, 1-4, 2-3, 9-4, 11-6
list_process_cmd_limits
command, 1-4, 2-7, 9-3, 9-4
list_users command for memory pool
Index
information, 6-4
Loading a program for alignment analysis, B-9
Local memory, 1-3, 6-1
Locking mechanisms
emulation of StrataBUS mechanism, 1-4,
2-7
performance penalty, 8-1
using for compatibility, 8-1
ensuring consistency of sets of variables, 4-4
machine-independent, 1-4, 2-7
performance advantage, 8-1
upgrading to, 8-1
used with volatile variables, 4-3
Locking policies
exclusive-use, 4-4, 7-6
multiple-reader/one-writer, 4-4
Locking subroutines, 1-4, 7-5, 8-2
checking lock status, 5-2
creating your own, 4-5
required to be external calls, 4-4
log_alignment_faults System Analysis
request, B-5
Logging alignment faults, B-5
identifying the correct log entry, B-6
identifying the log entry to use, B-8
viewing the log from another process, B-8
login command
-memory_pool argument
error message with one CPU/memory
Board, 6-4
for subprocess login, 6-3
longjmp function, 4-6
Longmap attributes, 3-6
VOS COBOL usage, 3-8
VOS FORTRAN usage, 3-9
VOS PL/I usage, 3-8
Longmap mapping rules, 3-2
as recommended rules, 2-3
compiling with, 2-7
Loops removed by compiler optimizations, 5-2
M
Machine-independent locking. See Locking
mechanisms, machine-independent
malloc function in VOS Standard C, 11-5
Mapping rules
checking the default, 2-2, 3-5
longmap
as recommended mapping rules, 2-3
compiling with, 2-7
where disallowed, 3-9
-mapping_rules compiler
argument, 3-5
shortmap
as a Continuum option, 2-4
compiling with, 2-9
where required, 3-9
-mapping_rules compiler argument
specifying alignment rules, 3-5
checking for padding, 3-5
match System Analysis request, B-7, B-8
Memory limits
current command limits, 9-4
module default command limits
different settings among modules, 11-6
overriding, 11-5
process initial command limits, 9-4
process maximum command limits, 9-3
Memory pools
controlling allocation to, 6-2
default allocation to, 6-1
getting information about assignment of, 6-4
local, 1-3, 6-1
remote, 1-3, 6-1
specifying, 2-7, 11-3
in command macros, 6-3
to solve caching conflict, 11-3
Memory-ordering, 7-5
Microjiffies, 1-5, 2-7
as unit of time measurement, 10-1
precision of Time-of-Day clock, 10-1
Migrating applications
effects of Continuum features, 1-1
FMS applications, A-1
ORACLE databases, 2-9
planning, 2-1
Mixing shortmap and longmap data, 3-11
Module default command limits, 9-4
different settings among modules, 11-6
overriding, 11-5
module_start_up.cm to add paging
file, 11-2
Multiple-reader/one-writer locking, 4-4
N
nls_edit_form command, A-1
nls_fms_object_library directory, A-4
O
object-computer paragraph to specify
Index-5
Index
alignment, 3-6
Optimization
effects on older applications, 5-1
eliminating redundant loading and
storing, 4-2
introducing risk of outdated shared data, 4-2
limited by volatile variables, 4-3
with -production_table compiler
argument, 4-6
with -table compiler argument, 4-5
ORACLE databases
migrating from Release 6 ORACLE, 2-9
ORACLE7 support on Continuum, 2-9
Overlays
bit field, 4-8
of incompatible data types, 4-7
P
Padding, 3-4
checking for inserted padding, 3-5, 3-10
explicitly padding a structure or union, 3-19
minimizing by rearranging elements, 3-18,
A-3
Paging space
adding dynamically, 11-2
adding for next bootload, 11-2
guidelines, 2-1
increasing, 1-4, 11-1
problem-solving, 11-2
usage
displaying current usage, 11-2
warning messages, 11-1
Parameter lists of varying length, 4-8
paramptr built-in function, 4-8
Pascal Language. See VOS Pascal
PL/I language. See VOS PL/I
.plist file
generating, 11-4, B-3
viewing, B-4
Pointers
alignment issues with based storage, 3-17
misalignment causing runtime fault, B-1
relational comparisons on pointer
values, 4-8
using alignment specifiers with, 3-7
Precision of Time-of-Day clock, 1-5
Precompilation, 8-3
Privileged process for updating command
limits, 9-3, 9-4
Process initial command limits, 9-4
Process maximum command limits, 9-3
allowing for memory usage variability, 11-5
Index-6

process System Analysis request, B-8
to select the process to analyze, B-8
using after a program runs, B-9
Process table entry pointer, B-6
checking for correct number, B-7
when invoking analyze_system, B-5
Process virtual memory limits. See Virtual
memory limits, process
Processes
getting information about, 6-4, B-9
profile command, 2-8, 2-9, 11-4, B-3
.profile file, B-3
Program address space layout, 9-2
Program virtual memory limits. See Virtual
memory limits, command
Pseudovariables as alternatives to bit field
overlays, 4-8
PTEP, B-6
checking for correct number, B-7
when invoking analyze_system, B-5
R
Registers
increased number on Continuum, 1-2
storing values in, 4-1
rel built-in function, 4-8
Remote memory, 1-3, 6-1
Runtime alignment faults. See Alignment faults at
runtime
S
s$clock_date_time subroutine, 1-5, 2-7,
10-1
s$clone subroutine, 6-3
s$connect_vm_region subroutine
access_mode values, 2-7
for debugging with
s$query_vm_lock, 8-2
for exclusive non-sequential
caching, 7-6
for exclusive-sequential caching, 7-5
for exclusive-use locking, 7-6
for machine-independent locking, 8-1
for memory-ordering support, 7-5
for shared non-sequential caching, 7-6
e$invalid_access_mode errror
code, 8-3
s$get_current_cmd_limit
subroutine, 1-4, 2-7, 9-3, 9-4, 11-5
s$get_disk_info subroutine, 11-3
s$get_paging_usage subroutine, 1-3, 11-3
s$get_process_info subroutine, 6-4
Index
s$get_processes_info subroutine, 6-4
s$get_vm_lock_word subroutine, 8-3
s$init_vm_lock subroutine, 8-3
s$int_date_time subroutine, 2-7, 10-2
s$jiffy_date_time subroutine, 2-7, 10-2
s$lock_vm_lock subroutine, 4-5, 5-2, 8-3
s$query_vm_lock subroutine
access mode for, 8-2
checking lock status with, 8-3
s$read_clock subroutine, 1-5, 2-7, 10-1
s$read_jiffy_clock subroutine, 2-7, 10-2
s$set_current_cmd_limit
subroutine, 1-4, 2-7, 9-3, 9-4, 11-4,
11-5, 11-6
s$sleep subroutine, 5-2
s$start_new_process subroutine, 2-6
on modules with one memory pool, 6-3
specifying a memory pool, 6-2
s$start_process subroutine, 2-6, 6-2
s$try_vm_lock subroutine, 4-5, 8-3
s$unlock_vm_lock subroutine, 8-3
declaring lock_storage argument, 8-3
releasing a virtual memory lock, 4-5
s$vm_lock_size subroutine, 8-3
set_alignment_fault_mode
command, 2-9, B-2
break-level requests, B-2
turning off the mode, B-3
setjmp function, 4-6
Setting up the migration environment, 2-1
Shared virtual memory
accessing outdated variable values, 4-1
conflicts with compiler assumptions, 4-2
ensuring consistency of sets of variables, 4-4
performance cost of cache line loading, 7-4
updates by multiple processes or
devices, 4-2
Shortmap attributes, 3-6
VOS COBOL usage, 3-8
VOS FORTRAN usage, 3-9
VOS PL/I usage, 3-8
Shortmap mapping rules, 3-2
as optional rules, 2-4
compiling with, 2-9
Specifying memory pool assignment, 2-7
Spin lock routines
lock_spin_lock, 8-2
spin_lock_size, 8-2
try_spin_lock, 8-2
unlock_spin_lock, 8-2
Stack fences, 9-2, 9-5
Stack space
default per-command limit, 2-3

default per-process limit, 2-3
-stack_fence_size binder argument, 9-5
Stacks, 4-8
controlling growth of, 9-3
different address space usage on
Continuum, 9-2
modifying routines that directly access, 4-8
start_process command
error message with one memory pool, 6-4
-memory_pool argument, 6-3
stdarg.h header file macros, 4-8
Storage
based, 4-7
defined, 4-7
overlaying one data type on another, 4-7
types to use without volatile, 4-4
Storage sharing
untyped, 3-18
with defined variables, 3-18
StrataBUS-style locking. See Locking
mechanisms, emulation of StrataBUS
mechanism
STRING functions in VOS FORTRAN, 5-4
String lengths
bit, 3-17
character, 3-17
Structures
adding pad elements explicitly, 3-19
converting to longmap, 3-18
nesting differently aligned structures, 3-11
padding added by compilers, 3-2, 3-3
using shortmap for predefined, 3-10
with alignments that cannot change, 3-10
Subjiffy timer speed determining clock
accuracy, 10-1
Subroutine calls
alignment of dec 15 and dec 18
simulations, 3-20
correcting argument alignment
mismatches, 3-14
where shortmap structures are accepted, 3-9
where shortmap structures are required, 3-9
Subroutines
s$clock_date_time, 1-5, 2-7, 10-1
s$clone, 6-3
s$connect_vm_region
access_mode values, 2-7, 7-5, 7-6,
8-1, 8-2
e$invalid_access_mode error
code, 8-3
s$get_current_cmd_limit, 1-4, 2-7,
9-3, 9-4, 11-5
Index-7
Index
s$get_disk_info, 11-3
s$get_paging_usage, 1-3, 11-3
s$get_process_info, 6-4
s$get_processes_info, 6-4
s$get_vm_lock_word, 8-3
s$init_vm_lock, 8-3
s$int_date_time, 2-7, 10-2
s$jiffy_date_time, 2-7, 10-2
s$lock_vm_lock, 4-5, 5-2, 8-3
s$query_vm_lock
access mode for, 8-2
checking lock status with, 8-3
s$read_clock, 1-5, 2-7, 10-1
s$read_jiffy_clock, 2-7, 10-2
s$set_current_cmd_limit, 1-4, 2-7,
9-3, 9-4, 11-4, 11-5, 11-6
s$sleep, 5-2
s$start_new_process, 2-6
on modules with one memory pool, 6-3
specifying a memory pool, 6-2
s$start_process, 2-6, 6-2
s$try_vm_lock, 4-5, 8-3
s$unlock_vm_lock, 8-3
declaring lock_storage
argument, 8-3
releasing a virtual memory lock, 4-5
s$vm_lock_size, 8-3
subroutines that require arguments initialized
to zero, 5-4
System Analysis subsystem, B-4
displaying source module lines from, B-10
invoking, B-5
T
Time-of-Day clock, 1-5, 2-7, 10-1
Troubleshooting
faulty data layout affecting cache
usage, 11-3
inconsistent memory limits, 11-5
insufficient module default command
limits, 11-6
paging space problems, 11-1
problems from running duplicate
programs, 11-3
process and command limit settings, 11-4
runtime alignment faults, 11-3
two programs heavily accessing the same
virtual addresses, 11-3
type attribute in VOS PL/I, 3-13
typedef used with alignment specifiers, 3-7
U
Unaligned bit strings, 3-18
Index-8
Uninitialized variables causing application

failure, 5-4
unspec
built-in function, 4-8
psuedovariable, 4-8
Untyped storage sharing, 3-18, 4-8
untyped_storage_sharing compiler
option, 4-8
update_default_cmd_limits
command, 1-4, 2-3, 9-4, 11-5, 11-6
update_disk_label command, 1-4, 11-2
update_process_cmd_limits
command, 1-4, 2-7, 9-3, 9-4, 11-4
use_file System Analysis request, B-9
user address in another process
message, B-7, B-8
V
Variables
accessing outdated values in shared
memory, 4-1
after longjmp function call, 4-6
global variables and cache line loading, 7-4
removed by optimization when
unreferenced, 5-2
uninitialized causing applications
failure, 5-4
using with extended floating-point
calculations, 5-3
volatile, 4-3
impeding optimizations, 4-3
preventing optimization of unreferenced
variables, 5-2
with locking subroutines, 4-3
with setjmp function call, 4-6
Varying length parameter lists, 4-8
Virtual memory limits
command
default, 2-3
retrieving, 2-7
setting, 2-7
process
default, 2-3
retrieving, 2-7
setting, 2-7
volatile attribute, 4-2, 4-3
volatile variables, 4-3
impeding optimizations, 4-3
in loops, 5-2
preventing optimization of unreferenced
variables, 5-2
with locking subroutines, 4-3
with setjmp function call, 4-6
Index
VOS C, FMS usage, A-2
VOS COBOL
FMS usage, A-3
using longmap clause, 3-8
using shortmap clause, 3-8
VOS FORTRAN
compiler directives, 3-6
FMS usage, A-3
interoperability restriction on
Continuum, 5-4
(longmap) attribute, 3-9
(shortmap)attribute, 3-9
VOS Pascal
aligning dec 15 and dec 18
simulation, 3-20
alignment inheritance with, 3-11
FMS usage, A-2
longmap attribute, 3-8
%options alignment compiler
directive, 3-6
shortmap attribute, 3-8
VOS PL/I
accessing varying length parameter lists, 4-8
alignment specifier used with structures, 3-8
argument and parameter alignment
mismatches, 3-15
based storage, 4-7
compiler directives, 3-6
defined storage, 4-7
FMS usage, A-2
like attribute, 3-13
longmap attribute, 3-8
overlaying incompatible data types, 4-7
shortmap attribute, 3-8
structures as elements of other
structures, 3-12
type attribute, 3-13
VOS Standard C
accessing varying length parameter lists, 4-8
aligning dec 15 and dec 18
simulation, 3-20
alignment inheritance with, 3-11
alignment specifiers used with pointers, 3-7
FMS usage, A-2
longjmp function, 4-6
$longmap attribute usage, 3-6
malloc function, 11-5
#pragma compiler directive, 3-5
setjmp function, 4-6
$shortmap attribute usage, 3-6
transferring control to another function, 4-6

using alignment attributes
with bit fields, 3-7
with functions returning void, 3-7
using alignment specifiers
with struct, union, and enum
keywords, 3-6
with type definitions, 3-7
W
where System Analysis request, B-10
who System Analysis request, B-7, B-8
structures as elements of other

structures, 3-11
Index-9
Index
Index-10

Migrating VOS Applications To Continuum (r407-00)

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Migrating VOS Applications To Continuum (r407-00)

Caricato da

Copyright:

Formati disponibili

R407-00

Migrating VOS Applications to Continuum Systems

Stratus Computer, Inc.

Manual Name: Migrating VOS Applications to Continuum Systems

Stratus Computer, Inc.

1995 by Stratus Computer, Inc. All rights reserved.

Migrating VOS Applications to Continuum Systems (R407)

Italics introduces or defines new terms. For example:

Boldface emphasizes words in text. For example:

Key Mappings for VOS Functions

Migrating VOS Applications to Continuum Systems (R407)

VOS Commands Reference Manual (R098)

A Note on the Contents of Stratus Manuals

all of the information necessary to process your manual order.

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

How to Comment on This Manual

Migrating VOS Applications to Continuum Systems (R407)

1. Continuum Features Affecting Application Migration

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

3. Addressing Alignment Issues. . . . . . . . . . . .

Migrating VOS Applications to Continuum Systems (R407)

VOS Pascal Usage . . . . . . . . . . . . . . . . . . . . . . . .

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

5. Correcting Coding Practices That Jeopardize Portability . .

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

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

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

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

Migrating VOS Applications to Continuum Systems (R407)

Appendix A. Migrating Forms Management System (FMS) Applications

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

Migrating VOS Applications to Continuum Systems (R407)

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

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

Data Alignment Rules

Migrating VOS Applications to Continuum Systems (R407)

Chapter 1: Continuum Features Affecting Application Migration

Memory on Each CPU/Memory Board

Memory on Each CPU/Memory Board

The Virtually Indexed Cache

Increased Paging Space Requirements

The Machine-Independent Locking Mechanism

The Machine-Independent Locking Mechanism

Process and Command Memory Limits

The commands list_process_cmd_limits and update_process_cmd_limits

The system administration commands list_default_cmd_limits and

A program can use the s$set_current_cmd_limit and

Chapter 1: Continuum Features Affecting Application Migration

Migrating VOS Applications to Continuum Systems (R407)

Chapter 1: Continuum Features Affecting Application Migration

Preparing to Migrate Your Applications

Setting Up Your Environment

the available paging space

Migrating VOS Applications to Continuum Systems (R407)

Preparing to Migrate Your Applications

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

Preparing to Migrate Your Applications

Checking and Setting Process Command Limits

Deciding on a Data Alignment Strategy

Migrating VOS Applications to Continuum Systems (R407)

Preparing to Migrate Your Applications

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

Revising Your Source Modules