R142-00

Stratus Computer, Inc.

VOS COBOL Users Guide

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.

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.

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, the Stratus logo, Continuum, VOS, Continuous Processing, StrataNET, FTX, and SINAP are registered trademarks of Stratus Computer, Inc.

XA, XA/R, Stratus/32, Stratus/USF, StrataLINK, RSN, Continuous Processing, Isis, the Isis logo, Isis Distributed, Isis Distributed Systems, RADIO, RADIO Cluster, and the SQL/2000 logo are trademarks of Stratus Computer, Inc.

Apple and Macintosh are registered trademarks of Apple Computer, Inc.IBM PC is a registered trademark of International Business Machines Corporation.Sun is a registered trademark of Sun Microsystems, Inc.Hewlett-Packard is a trademark of Hewlett-Packard Company.UNIX is a registered trademark of X/Open Company, Ltd., in the U.S.A. and other countries.HP-UX is a trademark of Hewlett-Packard Company.Manual Name: VOS COBOL Users Guide

Part Number: R142Revision Number: 00VOS Release Number: 10.0 Printing Date: March 1990

Stratus Computer, Inc.55 Fairbanks Blvd.Marlboro, Massachusetts 01752

1990 by Stratus Computer, Inc. All rights reserved.

Preface

The Purpose of This ManualThe VOS COBOL Users Guide (R142) documents the VOS COBOL compiler available with Release 10.0 of the VOS operating system. This compiler supports both COBOL-74 and COBOL-85.

AudienceThis manual is intended for experienced applications programmers who have a working knowledge of COBOL. It is a users guide designed to familiarize the COBOL programmer with the VOS implementation of COBOL; it also contains a reference section, written for the user who is familiar with VOS COBOL, which provides details of specific commands and options.

Before using the VOS COBOL Users Guide (R142), you should be familiar with VOS COBOL Language Manual (R010).

Revision InformationThis is the first publication of this manual. For information on which release of the software this manual documents, see the Notice page.

Manual OrganizationThis manual has seven chapters and three appendixes.

Chapter 1 provides an overview of the steps involved in preparing a program.

Chapter 2 discusses how to use the VOS COBOL compiler and its arguments.

Chapter 3 describes how to use the binder and its arguments.

Chapter 4 explains how to use the debugger and its requests.

Chapter 5 describes the VOS file I/O system and the VOS COBOL I/O system.

Chapter 6 discusses how to call programs written in other languages from VOS COBOL.

Chapter 7 describes how VOS COBOL supports National Language Support (NLS).

Appendix A provides the VOS Character Set table. VOS COBOL Users Guide (R142) iii

PrefaceAppendix B lists the differences between the ansi74, compatible, ansi85, and full_ansi85 versions of the compiler.

Appendix C provides the command descriptions of the cobol, bind, debug, and format_cobol_source commands in a reference format.

NotationStratus documentation uses italics to introduce or define new terms. For example:

A COBOL source program is a text file, called a source module.

Computer font is used to represent text that would appear on your display screen or on a line printer. (Such text is referred to as literal text.) For example:

Entering debug.New language is cobol.db?

Slanted font is used to represent general terms that are to be replaced by literal values. In the following example, the user must supply an actual value to replace the slanted font term.

The operating system creates a file named program_name.plist.

Boldface is used to emphasize words within the text. For example: A use procedure, if specified, does not execute.

Syntax NotationA syntax format is a specific arrangement of the elements of a VOS COBOL statement (or portion of a VOS COBOL statement). When VOS COBOL permits more than one arrangement, the documentation presents the arrangements as consecutively numbered formats. The text may also supply additional information defining the syntax formats.

Key words are reserved words that are underlined in the syntax formats. These words determine the code that is generated by the compiler. Reserved words that are not underlined can be used to increase readability, but have no effect on compilation.

The elements in a list of elements must be entered in the order shown in a syntax format, unless the text specifies otherwise.

Brackets and braces are sometimes nested in syntax formats.

Three dots ( . . .) in a syntax format represents the position at which repetition can occur. The scope of the dots is either the preceding element or the segment of the syntax format enclosed in the preceding brackets or braces. iv Preface

PrefaceIn examples, three dots in a column indicates that a portion of a language construct or program has been omitted. For example:

db? step .

.

.

Step complete at monthly_sales line 66.

Related ManualsRefer to the following Stratus manuals for related documentation.

VOS COBOL Language Manual (R010) VOS COBOL Subroutines Manual (R019) VOS COBOL Transaction Processing Facility (R034) VOS COBOL Forms Management System (R035) VOS Commands Reference Manual (R098) VOS Commands Users Guide (R089) VOS Tape Processing Users Guide and Programmers Reference (R052) VOS COBOL Programmers Guide (R077)VOS COBOL Users Guide (R142) v

Prefacevi Preface

Contents

1. Overview: Programming in VOS COBOL . . . . . . . . . . . . . . . . . . . . . . 1-1Preparing a Source Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Compiling a Source Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Binding Object Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Executing and Interrupting a Program Module . . . . . . . . . . . . . . . . . . . . 1-4

2. Compiling a Source Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Creating a Program Listing. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Creating a Compilation Listing. . . . . . . . . . . . . . . . . . . . . . . . 2-3Creating a Cross-Reference Listing . . . . . . . . . . . . . . . . . . . . . . 2-6Producing an Assembly Language Listing . . . . . . . . . . . . . . . . . . . 2-8Compiler Arguments That Affect the Listing . . . . . . . . . . . . . . . . . . 2-9

Interpreting Compiler Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Checking for Additional Errors at Compile Time and Run Time . . . . . . . . . . . . 2-10Creating a Symbol Table for Debugging Purposes . . . . . . . . . . . . . . . . . 2-11Displaying Compilation Statistics . . . . . . . . . . . . . . . . . . . . . . . . 2-12Getting Information about Program Execution . . . . . . . . . . . . . . . . . . . 2-13Specifying the Subset of ANSI COBOL . . . . . . . . . . . . . . . . . . . . . 2-15

Diagnosing Language Subset Elements . . . . . . . . . . . . . . . . . . . 2-15Specifying a Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17Specifying the Defaults for Data Attributes . . . . . . . . . . . . . . . . . . . . 2-18

Specifying the Computational Value . . . . . . . . . . . . . . . . . . . . 2-18Specifying the Default Sign . . . . . . . . . . . . . . . . . . . . . . . . 2-19Specifying the Default Allocation Type . . . . . . . . . . . . . . . . . . . 2-19

Specifying how the Compiler Interprets Text. . . . . . . . . . . . . . . . . . . . 2-19Specifying the Interpretation of Uppercase Letters . . . . . . . . . . . . . . . 2-19Specifying Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20Specifying the Method of String Replacement . . . . . . . . . . . . . . . . . 2-20

Optimizing the Object Code . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21Other Compiler Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21

3. Binding Object Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Specifying the Object Module or Modules. . . . . . . . . . . . . . . . . . . . . . 3-1Locating Object Modules and Entry Points . . . . . . . . . . . . . . . . . . . . . 3-2

Specifying the Search Rules for Finding Object Modules . . . . . . . . . . . . . 3-2The add_entry_names Command . . . . . . . . . . . . . . . . . . . . . 3-3Calling External and Internal Entry Points . . . . . . . . . . . . . . . . . . . 3-3VOS COBOL Users Guide (R142) vii

ContentsSpecifying Retained Entry Points . . . . . . . . . . . . . . . . . . . . . . . 3-4Generating a Bind Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4Specifying the Size of a Programs Address Space . . . . . . . . . . . . . . . . . . 3-6Displaying Statistics about the Binding . . . . . . . . . . . . . . . . . . . . . . . 3-8Writing a Binder Control File . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Specifying Required Directives . . . . . . . . . . . . . . . . . . . . . . . 3-9Specifying Optional Directives. . . . . . . . . . . . . . . . . . . . . . . 3-11Replacing bind Command Arguments with Directives . . . . . . . . . . . . . 3-14

4. Debugging a Program Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Preparing a Program for Debugging . . . . . . . . . . . . . . . . . . . . . . . . 4-3Invoking the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

From Command Level on a Program Module . . . . . . . . . . . . . . . . . . 4-3From Command Level on a Keep Module . . . . . . . . . . . . . . . . . . . 4-4From Break Level on a Program Module . . . . . . . . . . . . . . . . . . . . 4-4

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5Defining Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5Entering Debugger Requests. . . . . . . . . . . . . . . . . . . . . . . . . 4-5Getting Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6Ending and Interrupting a Debugging Session . . . . . . . . . . . . . . . . . . 4-6Displaying Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7Moving Backwards and Forwards in Source Code . . . . . . . . . . . . . . . . 4-8Starting Program Execution . . . . . . . . . . . . . . . . . . . . . . . . . 4-9Listing Frames on the Stack . . . . . . . . . . . . . . . . . . . . . . . . . 4-9Moving from One Block to Another. . . . . . . . . . . . . . . . . . . . . 4-10

Using Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11Setting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12Issuing Requests from Breakpoints . . . . . . . . . . . . . . . . . . . . . 4-12

Displaying an Expressions Value . . . . . . . . . . . . . . . . . . . 4-13Displaying Declaration Information . . . . . . . . . . . . . . . . . . 4-13Changing a Data Items Value . . . . . . . . . . . . . . . . . . . . 4-14Continuing Program Execution . . . . . . . . . . . . . . . . . . . . 4-14Setting Another Breakpoint. . . . . . . . . . . . . . . . . . . . . . 4-15Using Conditional Requests at Breakpoints . . . . . . . . . . . . . . . 4-15

Clearing Breakpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16Listing Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17

Stepping through a Program . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17Using Additional Debugger Requests. . . . . . . . . . . . . . . . . . . . . . . 4-21

Calling a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21Displaying Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21Checking That the Source Module Corresponds to the Program . . . . . . . . . . 4-22Checking a Tasks Status . . . . . . . . . . . . . . . . . . . . . . . . . 4-23Examining a Programs Assembly Code . . . . . . . . . . . . . . . . . . . 4-24

Examining a Lines Assembly Code . . . . . . . . . . . . . . . . . . 4-24Examining Registers . . . . . . . . . . . . . . . . . . . . . . . . 4-25Displaying a Variables Address and Contents . . . . . . . . . . . . . . 4-26

Using Shortcuts in the Debugger . . . . . . . . . . . . . . . . . . . . . . . . 4-27Abbreviating Requests . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28Using VOS Commands. . . . . . . . . . . . . . . . . . . . . . . . . . 4-28viii Contents

Contents5. The VOS COBOL I/O System . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1I/O System Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1Sequential File Organization . . . . . . . . . . . . . . . . . . . . . . 5-2Stream File Organization . . . . . . . . . . . . . . . . . . . . . . . 5-3Fixed File Organization . . . . . . . . . . . . . . . . . . . . . . . . 5-4Relative File Organization . . . . . . . . . . . . . . . . . . . . . . . 5-4

Access Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5File Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6File Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8I/O Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

File and Record Locking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9I/O Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12VOS COBOL I/O Summary . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

Opening a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12File Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13Integrating File System Commands with VOS COBOL . . . . . . . . . . . . . . . 5-15Tape Handling Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17

File Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18Mounting the Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18File Positioning at open . . . . . . . . . . . . . . . . . . . . . . . . . 5-18File Positioning at close . . . . . . . . . . . . . . . . . . . . . . . . 5-19Positioning the Reel During Multi-reel File Processing . . . . . . . . . . . . . 5-19

Printer Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20

6. Calling Programs in Other VOS Languages . . . . . . . . . . . . . . . . . . . . . 6-1Calling a Subprogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3Calling a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4Passing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4Referencing VOS COBOL Programs . . . . . . . . . . . . . . . . . . . . . . . . 6-5

A VOS COBOL Subprogram . . . . . . . . . . . . . . . . . . . . . . . . 6-5A VOS COBOL Function . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5

Referencing VOS PL/I Programs . . . . . . . . . . . . . . . . . . . . . . . . . 6-6A VOS PL/I Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7A VOS PL/I Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7Calling a PL/I Program with Dope . . . . . . . . . . . . . . . . . . . . . . 6-8Specifying PL/I Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 6-8

Referencing VOS Pascal Programs . . . . . . . . . . . . . . . . . . . . . . . . 6-9A VOS Pascal Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9A VOS Pascal Function . . . . . . . . . . . . . . . . . . . . . . . . . 6-10Specifying Pascal Data Types . . . . . . . . . . . . . . . . . . . . . . . 6-10

Referencing VOS C Functions . . . . . . . . . . . . . . . . . . . . . . . . . 6-11A VOS C Function That Does Not Return a Value . . . . . . . . . . . . . . . 6-11A VOS C Function That Returns a Value. . . . . . . . . . . . . . . . . . . 6-12Specifying C Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 6-12

Referencing VOS FORTRAN Programs . . . . . . . . . . . . . . . . . . . . . 6-13A VOS FORTRAN Subroutine. . . . . . . . . . . . . . . . . . . . . . . 6-13A VOS FORTRAN Function . . . . . . . . . . . . . . . . . . . . . . . 6-14VOS COBOL Users Guide (R142) ix

ContentsSpecifying FORTRAN Data Types . . . . . . . . . . . . . . . . . . . . . 6-14Referencing VOS BASIC Programs . . . . . . . . . . . . . . . . . . . . . . . 6-15

A VOS BASIC Subprogram . . . . . . . . . . . . . . . . . . . . . . . . 6-15Specifying BASIC Data Types . . . . . . . . . . . . . . . . . . . . . . . 6-15

7. National Language Support and VOS COBOL . . . . . . . . . . . . . . . . . . . . 7-1NLS String Representation . . . . . . . . . . . . . . . . . . . . . . . . . 7-2Shift Characters and NLS Strings . . . . . . . . . . . . . . . . . . . . . . . 7-3

Canonical Strings . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4Common Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

Default Character Sets of String Constants . . . . . . . . . . . . . . . . . . . 7-4Checking the Contents of Strings . . . . . . . . . . . . . . . . . . . . . . . 7-5Character Sets and NLS Functions . . . . . . . . . . . . . . . . . . . . . . 7-6

Appendix A. The VOS Character Code Set . . . . . . . . . . . . . . . . . . . . . . A-1

Appendix B. Differences Between COBOL-74 and COBOL-85 . . . . . . . . . . . . . B-1VOS COBOL Compiler Language Options . . . . . . . . . . . . . . . . . . . . B-1

The full_ansi85 Language Option . . . . . . . . . . . . . . . . . . . B-2The ansi85 Language Option . . . . . . . . . . . . . . . . . . . . . . B-3The compatible Language Option . . . . . . . . . . . . . . . . . . . . B-4The ansi74 Language Option . . . . . . . . . . . . . . . . . . . . . . B-4

VOS COBOL Language Differences . . . . . . . . . . . . . . . . . . . . . . . B-5New Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5

Specifying -ansi_replace . . . . . . . . . . . . . . . . . . . . B-5Defining Default Class Storage . . . . . . . . . . . . . . . . . . . . B-6Using Label Variables. . . . . . . . . . . . . . . . . . . . . . . . B-6Using Entry Variables . . . . . . . . . . . . . . . . . . . . . . . . B-6Defining Functions with Procedure Division Syntax . . . . . . . . . . . . B-7Specifying Recursive Programs . . . . . . . . . . . . . . . . . . . . B-7Eliminating Words with the %replace Directive . . . . . . . . . . . . B-8

Differences Between the full_ansi85 and ansi85 Options . . . . . . . . . B-8Support of the cancel Statement . . . . . . . . . . . . . . . . . . . B-8Reinitialization of perform Ranges . . . . . . . . . . . . . . . . . . B-8

Differences Between the ansi85 and compatible Options . . . . . . . . . . B-9Support for global Data Names and File Names . . . . . . . . . . . . B-9I/O Incompatibilities . . . . . . . . . . . . . . . . . . . . . . . . B-9Nested Programs . . . . . . . . . . . . . . . . . . . . . . . . . . B-11Obsolete Elements . . . . . . . . . . . . . . . . . . . . . . . . . B-11The perform ... varying Statement . . . . . . . . . . . . . . . B-12Alphabetic Class Test . . . . . . . . . . . . . . . . . . . . . . . . B-12Variable-Length Assignments. . . . . . . . . . . . . . . . . . . . . B-12Restrictions Generating Compiler Errors . . . . . . . . . . . . . . . . B-13

Differences Between the compatible and ansi74 Options . . . . . . . . . . B-14Lifted Restriction on program-id . . . . . . . . . . . . . . . . . . B-14New Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . B-14

Upgrading Programs from COBOL-74 to COBOL-85 . . . . . . . . . . . . . . . . B-15x Contents

ContentsAppendix C. Summary of VOS COBOL Commands . . . . . . . . . . . . . . . . . . C-1cobol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-6Binder Control File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8Syntax, Comments, and Empty Lines. . . . . . . . . . . . . . . . . . . . . . . C-8Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-12Source Mode Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . C-13

Frequently Used Arguments . . . . . . . . . . . . . . . . . . . . . . . . C-13Source Mode Requests . . . . . . . . . . . . . . . . . . . . . . . . . . C-14

Object Mode Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . C-17format_cobol_source . . . . . . . . . . . . . . . . . . . . . . . . . . . C-18

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Glossary-1

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1VOS COBOL Users Guide (R142) xi

xii Figures

Figures

Figure 1-1. Program Development Process . . . . . . . . . . . . . . . . . . . . . . . 1-2Figure 2-1. Compilation Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Figure 2-2. Cross-Reference Listing. . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Figure 2-3. Sorted Cross-Reference Listing . . . . . . . . . . . . . . . . . . . . . . . 2-8Figure 2-4. Assembly Language Listing . . . . . . . . . . . . . . . . . . . . . . . . 2-8Figure 2-5. Compilation Listing with a Run-Time Error . . . . . . . . . . . . . . . . . . 2-10Figure 2-6. Compilation Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12Figure 2-7. Run-Time Performance Information of a Program Module . . . . . . . . . . . . 2-14Figure 2-8. FIPS Level Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16Figure 2-9. ANSI Subset Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17Figure 3-1. Bind Map for monthly_sales.pm . . . . . . . . . . . . . . . . . . . . . 3-6Figure 3-2. Program Address Space . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Figure 3-3. Binder Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8Figure 4-1. Displaying the Declaration Information of a Data Name . . . . . . . . . . . . . 4-14Figure 4-2. Using Conditional Requests . . . . . . . . . . . . . . . . . . . . . . . . 4-16Figure 4-3. Stepping through a Program . . . . . . . . . . . . . . . . . . . . . . . . 4-18Figure 4-4. Stepping Into a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . 4-19Figure 4-5. Stepping Past a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . 4-20Figure 4-6. Displaying the Arguments Associated with a Procedure . . . . . . . . . . . . . 4-22Figure 4-7. Displaying the Assembly Code Translation of a Line . . . . . . . . . . . . . . 4-25Figure 4-8. Displaying the Contents of Registers. . . . . . . . . . . . . . . . . . . . . 4-26Figure 4-9. Displaying a Dump of a Variable . . . . . . . . . . . . . . . . . . . . . . 4-27Figure 5-1. Sequential File Organization . . . . . . . . . . . . . . . . . . . . . . . . 5-3Figure 5-2. Stream File Organization . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Figure 5-3. Fixed File Organization . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4Figure 5-4. Relative File Organization . . . . . . . . . . . . . . . . . . . . . . . . . 5-5Figure 7-1. The VOS Internal Character Coding System. . . . . . . . . . . . . . . . . . 7-3

Tables

Table 2-1. Arguments That Create Compilation Listings. . . . . . . . . . . . . . . . . . 2-2Table 2-2. Options That Specify a Processor . . . . . . . . . . . . . . . . . . . . . . 2-18Table 3-1. Directives That Replace bind Command Arguments . . . . . . . . . . . . . . 3-14Table 4-1. Debugger Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Table 4-2. Break Level Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7Table 5-1. Run-Time Access Modes. . . . . . . . . . . . . . . . . . . . . . . . . . 5-6Table 5-2. Lock Mode Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11Table 5-3. Mapping of VOS COBOL Open Mode to I/O Type . . . . . . . . . . . . . . . 5-13Table 5-4. Files Supported Using Output Mode . . . . . . . . . . . . . . . . . . . . . 5-13Table 5-5. File System Commands and Subroutines . . . . . . . . . . . . . . . . . . . 5-16Table 6-1. Cross-Language Compatibility . . . . . . . . . . . . . . . . . . . . . . . 6-2Table 7-1. Number of Bytes per Character . . . . . . . . . . . . . . . . . . . . . . . 7-2Table 7-2. Default Character Set Options. . . . . . . . . . . . . . . . . . . . . . . . 7-4Table 7-3. NLS Mnemonic Names and Character Set IDs . . . . . . . . . . . . . . . . . 7-7Table A-1. VOS Character Code Set . . . . . . . . . . . . . . . . . . . . . . . . . A-1Table B-1. COBOL-85 and COBOL-74 File Status Codes . . . . . . . . . . . . . . . . . B-10VOS COBOL Users Guide (R142) xiii

Tablesxiv Tables

Chapter 1: Overview: Programming in VOS COBOL 1-

This chapter gives an overview of the steps used to prepare and execute a COBOL program. These steps are as follows:

preparing a source program compiling a source module binding an object module executing and interrupting a program module.

Figure 1-1 shows the sequence of steps you use to produce a program module and the files that these steps produce. VOS COBOL Users Guide (R142) 1-1

Overview: Programming in VOS COBOL1

Figure 1-1. Program Development Process

file_name.error

file_name.cobol

file_name.listcobol file_name

Source Module

Error Listing

ListingCompilerCompile Time

file_name.obj

Object Module

edit file_name

Program Module

file_name.pm

file_name

Test Program

Run Time

bind file_name

BinderBind Time

otherobject module

CompilerErrors?

Binder Errors?

Test/Debug

Errors?

Debug

debug file_nameor

debug filename.kp

Yes

No

Yes

No

Yes

No

Error FreeExecutable Program

file_name.pm

PD00381-2 Chapter 1: Overview: Programming in VOS COBOL

Preparing a Source ProgramPreparing a Source ProgramA COBOL source program is a text file, called a source module. The file name of a VOS COBOL source module must have the suffix .cobol. You write and update source modules with an editor such as the VOS Word Processing Editor or Emacs.

For information on the VOS implementation of the COBOL language, see the VOS COBOL Language Manual (R010). This manual also describes how to prepare your source modules. Additional information is provided in the VOS COBOL Programmers Guide (R077).

Compiling a Source ModuleWhen you compile a source module, the compiler translates the code in your program into object code and puts it in your current directory. The VOS COBOL compile command is cobol. You need not enter the .cobol suffix when you enter file_name. The format of the cobol command is:

cobol file_name [argument] . . . The cobol command, which has many compiler arguments, produces an object module. The object module contains object code and has the name of the source module file and the .obj suffix.

If there are any compilation errors or warnings, the compiler creates an error file with the name of the source module and the suffix .error. When you recompile the source module, the compiler overwrites the object module it generated previously if the file still exists with the same name in the current directory. Likewise, if there are still errors, the compiler overwrites the error file. However, if there are no errors, the compiler deletes the error file.

The following example of a cobol command compiles the source module in the file named monthly_sales.cobol.

cobol monthly_sales

If the compilation is successful, the compiler creates an object module in the file monthly_sales.obj. If the compiler finds any errors, it creates an error file called monthly_sales.error and also displays the error diagnostics on your screen.

You can enter one or more compiler arguments with the cobol command. For example, if you select the -list argument, the cobol command creates a listing of the source module in a file with the suffix .list. The cobol command is described in Appendix C. VOS COBOL Users Guide (R142) 1-3

Binding Object ModulesBinding Object ModulesAfter you compile a source module, you must bind the object module before executing the program. When you bind an object module or object modules, the binder incorporates the following into one executable program module:

the object modules you specified any object modules invoked by other object modules being bound certain predefined VOS functions and procedures used by the program.

The command for binding COBOL programs is bind. You need not specify the .obj suffix when you enter the command. The following example shows the format.

bind file_name [argument] . . . The bind command produces a program module. A program module contains executable code and has the suffix .pm. Program modules are referred to as external commands because you can execute them from the command level.

The following example of a bind command binds the object module in a file named monthly_sales.obj.

bind monthly_sales

This command produces a program module called monthly_sales.pm.

You can enter one or more binding arguments with the bind command. For example, if you specify the -map argument, the binder creates a bind map. For more details about the bind command, see Chapter 3.

Executing and Interrupting a Program ModuleThis section describes how you execute a program module and interrupt execution.

To execute a program module named monthly_sales.pm, you type, at the command level, the name of the module.

monthly_sales.pm

Then press .

You can omit the .pm suffix if there is no command macro (.cm) file with the same name, such as monthly_sales.cm. 1-4 Chapter 1: Overview: Programming in VOS COBOL

Executing and Interrupting a Program ModuleTo interrupt the execution of the program module, press . The following prompt then appears on the screen.

BREAKRequest? (stop, continue, debug, keep, login, re-enter)

To stop the execution of a program, press s for the stop request. To resume the execution of a program, press c for the continue request. See Chapter 4 for more information on the other requests you can enter at break level. VOS COBOL Users Guide (R142) 1-5

Executing and Interrupting a Program Module1-6 Chapter 1: Overview: Programming in VOS COBOL

Chapter 2: Compiling a Source Module 2-

The cobol command invokes the VOS COBOL compiler. The compiler reads the source module, checks it for errors, and produces an object module and/or error file if there are any errors in the source module. This chapter explains how to use the cobol command and its arguments to perform the following tasks:

creating a program listing interpreting compiler diagnostics checking for additional errors at compile time and run time creating a symbol table for debugging purposes displaying compilation statistics getting information about program execution specifying the subset of ANSI COBOL specifying a processor on which to execute a program specifying the method of string replacement specifying a computational default specifying the interpretation of uppercase letters and indentation optimizing the object code.VOS COBOL Users Guide (R142) 2-1

Creating a Program ListingThe cobol commands display form is as follows:

Display Form

Access RequirementsYou need read access to a source module to compile it. You need modify access to the directory from which you are issuing the command, in which the .obj file will be created.

Creating a Program ListingA listing file contains the source module and any include files. Each line of the source code is numbered. The compiler writes any error messages at the end of the listing file.

To get a listing, you can use any of the arguments shown in Table 2-1. This table shows all the arguments for producing a compilation listing and the information included in each listing. The simplest form of a listing is created with the -list argument.

1

------------------------------------- cobol ------------------------------------source_file_name: -processor: default-language: compatible -level: none-list: no -full: no-xref: no -xref_format: standard-table: no -production_table: no-optimize: yes -check: no-format: no -mapcase: no-profile: no -cpu_profile: no-statistics: no -silent: no-default_comp: none -default_sign: trailing_embedded-debugging_mode: no -default_class: static-main: no -segmentation: no-ansi_replace: no

Table 2-1. Arguments That Create Compilation Listings

Option Contents of Listing

-list Compilation listing and symbol listing

-xref Compilation listing, symbol listing, and cross-reference listing

-xref_format Compilation listing, symbol listing, and cross-reference listing

-full Compilation listing, symbol listing, and assembly language listing2-2 Chapter 2: Compiling a Source Module

Creating a Program ListingCreating a Compilation ListingIf you select the -list argument, the compiler creates a compilation listing. The file containing the compilation listing has the name of the program module and the .list suffix.

The example in Figure 2-1 shows a compilation listing created with the -list argument. The boldfaced numbers to the left of Figure 2-1 correspond to the boldfaced numbers in the explanation following the figure.

1. SOURCE FILE: %s1#d01>Sales>monthly_sales.cobolCOMPILED ON: 89-11-26 AT 11:39 BY COBOL Release 10

OPTIONS: -list

2. 1 identification division. 2 program-id. monthly_sales. 3 4 * This program tabulates regional sales totals and outputs them 5 * to a file. The program reads raw data from an input file and 6 * calculates the region number from the sales reps number. 7 8 environment division. 9 input-output section. 10 file-control. 11 select raw_sales assign to s 12 organization is sequential 13 access is sequential. 14 15 select sales_by_region assign to p 16 organization is sequential 17 access is sequential. 18 19 data division. 20 file section. 21 fd raw_sales. // input file. 22 01 raw_sales_record. // record format for input file. 23 02 rep_number_in picture 9(5). 24 02 name_in picture x(20). 25 02 transaction_number_in picture 9(6). 26 02 trans_amount_in picture x(7). 27 28 fd sales_by_region. // output file. 29 01 sales_totals. 30 02 region_out picture 9 value zeroes. 31 02 region_total picture 9(5)v99 value zeroes. 32 33 working-storage section. 34 01 sales_record. // record format for input file. 35 02 rep_number picture 9(5). 36 02 name picture x(20) 37 02 transaction_number picture 9(6). 38 02 trans_amount picture 9999v99. 39 01 regional_sales. 40 02 region_info picture 99999v99 occurs 5 times value zeroes. 41 01 region picture 9. 42 01 end_flag picture x value n. 43

(Continued on next page)VOS COBOL Users Guide (R142) 2-3

Creating a Program Listing44 procedure division. 45 main_paragraph. 46 open input raw_sales. 47 perform add_it until end_flag is equal to y. 48 close raw_sales. 49 perform summary_and_cleanup. 50 call write_report. 51 exit program. 52 53 * This paragraph assigns rep number and keeps running totals. 54 55 add_it. 56 read raw_sales into sales_record 57 at end move y to end_flag 58 not at end divide rep_number by 10000 giving region 59 add trans_amount region_info(region) 60 giving region_info(region). 61 62 * This paragraph writes running totals to output file. 63 64 summary_and_cleanup. 65 open output sales_by_region. 66 perform varying region from 1 by 1 until region > 5 67 move region to region_out 68 move region_info(region) to region_total 69 write sales_totals. 70 close sales_by_region.

3. NAME TYPE/CLASS SIZE LOC ATTRIBUTES

monthly_sales program-name external report_writer entry-name 0004 external

DATA-NAMES FOR PROCEDURE monthly_sales

add_it paragraph-name 0184 end_flag data/alphanum 1 0034 pic x f/raw_sales data/group 164 00dc f/sales_by_region

data/group 164 0038 main_paragraph paragraph-name raw_sales file-name 38 00dc seq/seq raw_sales_record

data/group 38 0188 record rep_number_in data/numeric 5 0 display, pic 9(5) name_in data/alphanum 20 5 pic x(20) transaction_number_in

data/numeric 6 19 display, pic 9(6) region data/numeric 1 01ae display, pic 9 regional_sales data/group 35 0010 region_info data/numeric 7 0 display, pic 9(5)v99, occurs 5

.

.

.

4. PROGRAMMED OPERATORS USED IN THIS COMPILATION:

div_long_int fixdec_to_cobol_decimal cobol_decimal_to_fixdec assign_chars mult_long_int_nofofl

(Continued on next page)2-4 Chapter 2: Compiling a Source Module

Creating a Program Listing5. CODE GENERATED FOR PROCESSOR: mc68000

6. STACK FRAME SIZES: (fixed length portion only)

NAME LINE STACK SIZE

monthly_sales 44 76

7. WARNING 383 SEVERITY 1 BEGINNING ON LINE 37An apparently missing period following "x(20)" has been supplied.

1

Figure 2-1. Compilation Listing

In the following explanation, the numbers correspond to the numbers in Figure 2-1.

1. The opening banner contains the path name of the source file, the date and time of compilation, the release number of the VOS COBOL compiler on which the program was compiled, and any arguments that were used.

2. The actual listing of the program with line numbers (in this case, lines 1-70).

3. The list of data names for a procedure gives information about each identifier defined in the program. For each named constant or variable, the symbol listing gives the following information.

NAME gives the name of an object defined in the program. The objects listed include all data names, index names, procedure names, file names, entry names, etc.

TYPE/CLASS describes the type of the object, and the class, if the object is a data name.

SIZE gives the decimal number of bytes occupied by the storage associated with the object, if applicable. For file names, this is the size of the associated record area.

LOC gives the hexadecimal offset within the stack of an automatic variable, the offset within the static region of a static variable or a link to external data, or the displacement of a record field within the associated record. The offset of a procedure name is in the code region; the offset of a file name is in the static area.

ATTRIBUTES lists various attributes related to the object. 4. The list of programmed operators used in this compilation are subroutines with

predefined interfaces that are shared throughout the system.

5. This section specifies the processor for which the code is generated.

6. This section lists the stack frame sizes for each program; it shows the beginning line of the executable code, and lists the size of the stack, in bytes.

7. Error messages resulting from the compilation are shown at the end of the file. VOS COBOL Users Guide (R142) 2-5

Creating a Program ListingCreating a Cross-Reference ListingIf you choose the -xref argument, the compiler creates a compilation listing, a symbol listing, and a cross-reference listing of all the data names declared in the program. For each data name declared in the program, the cross-reference shows the line number on which the data name is defined and the line of a statement on which the data name is referenced. To specify the format of the listing, use the -xref_format argument. The following list contains the format options.

standard. The cross-reference information is included in the Attributes area of the listing. This is sorted according to data name, as shown in Figure 2-2, except when the item is subordinate to a record, in which case it appears following the record that contains it. (This is the default.)

sorted. The cross-reference information is sorted for all data names that are referenced in the program, whether or not the data item is subordinate to a record, and is appended to the standard listing. An example of this format is shown in Figure 2-3.

all_sorted. The cross-reference information is given for all data names in the program, whether or not they are referenced. The list is sorted as in the sorted option and appended to the standard listing. It is similar to the listing shown in Figure 2-3, but longer. 2-6 Chapter 2: Compiling a Source Module

Creating a Program ListingFigure 2-2 shows the cross-reference listing, in the standard format, for the program monthly_sales.

NAME TYPE/CLASS SIZE LOC ATTRIBUTES/REFERENCES

monthly_sales program-name external Def 44 No Refs write_report entry-name 0004 external Implicit Def 50 Ref 50

DATA-NAMES FOR PROCEDURE monthly_sales

add_it paragraph-name 0184 Def 55 Ref 47 end_flag data/alphanum 1 0034 pic x Def 42 Ref 47 57 f/raw_sales data/group 164 00dc Def 11 No Refs f/sales_by_region data/group 164 0038 Def 15 No Refs main_paragraph paragraph-name Def 45 No Refs raw_sales file-name 38 00dc seq/seq Def 11 Ref 46 48 56 raw_sales_record data/group 38 0188 record Def 22 No Refs rep_number_in data/numeric 5 0 display, pic 9(5) Def 23 No Refs name_in data/alphanum 20 5 pic x(20) Def 24 No Refs transaction_number_in data/numeric 6 19 display, pic 9(6) Def 25 No Refs trans_amount_in data/alphanum 7 1f pic x(7) Def 26 No Refs .

.

.

summary_and_cleanup paragraph-name 0180 Def 64 Ref 49

2

Figure 2-2. Cross-Reference ListingVOS COBOL Users Guide (R142) 2-7

Creating a Program ListingFigure 2-3 shows the cross-reference listing for the same program, compiled with the argument -xref_format sorted.

CROSS-REFERENCE LISTING

write_report Implicit Def 71 Ref 50

DATA-NAMES FOR PROCEDURE monthly_sales

add_it Def 55 Ref 47 end_flag Def 42 Ref 47 57 raw_sales Def 11 Ref 46 48 56 region Def 41 Ref 58 59 59 66 66 67 68 region_info Def 40 Ref 59 59 68 region_out Def 30 Ref 67 region_total Def 31 Ref 68 rep_number Def 35 Ref 58 sales_by_region Def 15 Ref 65 70 sales_record Def 34 Ref 56 sales_totals Def 29 Ref 69 summary_and_cleanup Def 64 Ref 49 trans_amount Def 38 Ref 59

3

Figure 2-3. Sorted Cross-Reference Listing

Producing an Assembly Language ListingIf you select the -full argument, the compiler creates an assembly language listing in addition to the compilation listing. The example in Figure 2-4 shows the assembly language listing for one statement of the program monthly_sales.

4

Figure 2-4. Assembly Language Listing

In the following explanation, the numbers correspond to the numbers in Figure 2-4.

Before the assembly listing for each line of executable code, the compiler inserts the line number and the source code from that line.

1. The first column contains the hexadecimal offset, in bytes, relative to the beginning of the object module.

2. The second and third columns contain the object code. 3. The fourth column contains the assembly language instruction.

1. 2. 3. 4. 5.LINE 57

at end move y to end_flag000001B0 7E79 moveq =121,d7 =y000001B2 1B47 8034 move.b d7,-32716(a5) end_flag2-8 Chapter 2: Compiling a Source Module

Interpreting Compiler Diagnostics4. The fifth column contains the operands.

5. The last column contains comments on the code.

Compiler Arguments That Affect the ListingIn addition to the compiler arguments just described, VOS COBOL supports the following extensions that affect the program listing when you compile with the -list argument.

%page. This extension inserts a page break in the listing.

%list. This extension indicates that the code following this statement should be included in the .list file.

%nolist. This extension indicates that the code following this statement should not be included in the .list file.

Interpreting Compiler DiagnosticsAt compile time, the VOS COBOL compiler checks for errors, such as syntax errors, undeclared data names, and operands that have incompatible data types. If the compiler discovers any errors in your source module, it displays an error message on your screen.

The compiler also creates an error file in the current directory and writes the error messages to this file. The error file has the same name as the source module with the suffix .error. The compiler also appends the error messages to a compilation listing if a listing is produced. Any .error file is deleted by the compiler if a subsequent compilation of the same source module contains no errors or warnings.

The VOS COBOL compiler distinguishes four levels of severity in the errors it detects.

SEVERITY 1: Warning SEVERITY 2: Correctable Error SEVERITY 3: Uncorrectable Error: Translation Can Continue SEVERITY 4: Uncorrectable Error: Translation Cannot Continue

The text of the error message usually explains the cause of the error.

A severity-1 error, although possibly valid COBOL, is most likely a programming error. However, since the source module is syntactically and semantically correct at the point of the error, the compiler continues to compile the source and produce an object module. A severity-2 error is invalid COBOL, but the compiler can reinterpret the source in such a way that it can continue to compile the program. The compiler proceeds as if the faulty code were replaced with the most likely syntactically and semantically correct code and produces an object module. A severity-3 error is invalid COBOL, and the compiler cannot reinterpret the source in such a way that it can continue to compile the program into a usable object module. Nevertheless, the compiler continues to process the program to detect additional errors. VOS COBOL Users Guide (R142) 2-9

Checking for Additional Errors at Compile Time and Run TimeA severity-4 error is invalid COBOL, and the compiler cannot reinterpret the source in such a way that it can continue to process the program from the point of the error.

If a severity-1 or a severity-2 error occurs, you can bind the object module, but the program may not perform as expected. If a severity-3 or a severity-4 error occurs, the object module is not created.

If you specify the -silent argument with the cobol command, the compiler suppresses warning messages of severity-1 errors from appearing on your screen.

Checking for Additional Errors at Compile Time and Run TimeThe -check compiler argument enables you to check for additional errors at compile time or at run time.

If you specify the -check argument, the compiler checks for certain errors during compilation and adds extra code that checks for errors at run time. If an error is caused by a constant value, the error is detected at compile time. Otherwise, the error will be detected at run time. The errors that can be detected include the following:

out-of-bounds table subscripts values falling out of the range of the occurs...depending on clause.

An array (table) subscript is out of bounds when it is not within the range of values defined in the occurs clause.

Figure 2-5 contains the add_it procedure of the sample program monthly_sales. Suppose the file raw_sales contains the following entry:

72489Spenser, Richard 110022080000

In this example, the value of rep_number is 72489. This number is out of range because the first digit, which indicates the region, exceeds the number of valid regions, which is 5. The error occurs when the program attempts to assign a value to region_info(7), which has only 5 elements.

55 add_it. 56 read raw_sales into sales_record 57 at end move 'y' to end_flag58 not at end divide rep_number by 10000 giving region59 add trans_amount region_info(region) 60 giving region_info(region).

5

Figure 2-5. Compilation Listing with a Run-Time Error2-10 Chapter 2: Compiling a Source Module

Creating a Symbol Table for Debugging PurposesWhen the error is detected at run time, the following message appears on the screen:

One or more subscripts of an array reference are out of bounds.Error occurred in procedure monthly_sales, line 59.Command was monthly_sales.pm.

In this case, to correct the error, correct the invalid data.

Creating a Symbol Table for Debugging PurposesIn order to debug a program in source mode, you must create a symbol table in the object code. You can select one of two arguments to produce this table: -table or -production_table. Note that a symbol table greatly increases the size of the object module.

If you specify the -table argument, you can take advantage of the full functionality of the debugger. However, when you specify this argument, the compiler does not perform certain types of object code optimization. As a result, program execution may be slower. If you specify the -production_table argument, the compiler creates a symbol table and optimizes the object code. However, because the code is optimized, the set and continue debugger requests may produce unpredictable results. If you specify both -production_table and -table, -production_table takes precedence.

See Chapter 4 for more information on the debugger. VOS COBOL Users Guide (R142) 2-11

Displaying Compilation StatisticsDisplaying Compilation StatisticsIf you select the -statistics argument, the compiler displays compilation statistics on the screen during the compile. If you also specify the -list argument, the compiler appends the statistics to the compilation listing. Figure 2-6 shows the compilation statistics of a sample program.

COMPILATION STATISTICS

PHASE DISK SECONDS SPACE PAGING CPUinitial 0 3 1 23 1 14:10:31 parser 4 6 1 96 2 14:10:37 optimizer 7 2 1 9 1 14:10:39 allocator 1 0 1 7 0 14:10:39 code gen 12 5 1 62 2 14:10:44 total 24 16 1 197 6 14:10:45

NODE PAGES 4CODE SIZE 1034STATIC SIZE 534SYMTAB SIZE 230SOURCE LINES 70LINES PER MIN 700

6

Figure 2-6. Compilation Statistics

The following list describes the information in each column.

PHASE is the phase of compilation.

DISK is the number of times that the compiler performed disk I/O in each phase of compilation.

SECONDS is the number of seconds the compiler took to complete each phase.

SPACE is the number of pages that the compiler used in allocating blocks of memory during each phase.

PAGING is the number of page faults the compiler made in executing each phase.

CPU is the amount of time, in seconds, that the central processing unit took to complete each phase.

The last column indicates the time when the compiler completed each phase.

The -statistics argument also reports the number of node pages, the number of source code lines, the number of lines compiled per minute, and the size, in bytes, of the object code, the static code, and the symbol table. 2-12 Chapter 2: Compiling a Source Module

Getting Information about Program ExecutionGetting Information about Program ExecutionTo get information about the execution of a program module each time you run it, you specify one of two arguments: -profile or -cpu_profile. If you specify either of these arguments, the compiler inserts code, into the object module, that reports performance information when you run the program. The profile file, which is created when you execute the code, is a non-ASCII file that has the same name as the program module except the suffix is .profile.

If you specify the -profile argument, the compiler inserts additional code that keeps track of the number of times each source statement is executed.

If you specify the -cpu_profile argument, the compiler inserts additional code that keeps track of the amount of CPU time spent and the number of page faults taken executing each statement when the program runs. Because the operating system must process more code when you run the module, the execution of the program compiled with the -cpu_profile argument takes significantly more time.

You cannot specify both the -profile and -cpu_profile arguments.

To convert the information in the profile, created with either argument, into readable text, you must create a .plist file from it. Here are the steps you follow.

1. Compile the source module with the -profile argument or the -cpu_profile argument.

2. Bind the object module with the bind command. 3. Run the program module. This creates the .profile file.

4. Process the .profile file with the profile command. The operating system creates a file named program_name.plist.

5. Display or print the .plist file.

Note that if you process the .profile file with the profile commands -list argument, the operating system creates, in the .plist file, a compilation listing in addition to the .plist information so that you can see the performance information and the source code for each statement in a program. See VOS Commands Reference Manual (R098) for details on the other profile command arguments. VOS COBOL Users Guide (R142) 2-13

Getting Information about Program ExecutionFigure 2-7 shows a .plist file created by the profile command from an execution of a program compiled with the -cpu_profile argument.

Profile of: monthly_sales

Number of statements: 18 Statements Executed: 17 (94.44% of statements)

STATEMENT COUNT CPU(ms) PAGES CUM % %

44 1 0.01 0 0.0 0.00 46 1 201.43 0 30.0 30.01 47 1 0.01 0 30.0 0.00 48 1 45.88 0 36.8 6.83 49 1 0.00 0 36.8 0.00 50 1 0.00 0 36.8 0.00 51 1 0.00 0 36.8 0.00 56 16 61.42 0 46.0 9.15 57 1 0.00 0 46.0 0.00 58 16 4.40 0 46.6 0.65 59 16 9.83 0 48.1 1.46 65 1 222.73 0 81.3 33.18 66 1 0.00 0 81.3 0.00 67 5 0.00 0 81.3 0.00 68 5 0.54 0 81.4 0.08 69 5 10.30 0 82.9 1.53 70 1 114.51 0 100.0 17.06

TOTALS: 74 671.12 0

Null statement CPU time: 0.196 milliseconds.

7

Figure 2-7. Run-Time Performance Information of a Program Module

The performance information in the sample monthly_sales.plist file is divided into six columns. The following list describes the information in each column.

STATEMENT is the line number of the statement.

COUNT is the number of times the statement was executed.

CPU(ms) is the number of milliseconds the CPU took to process the statement.

PAGES is the number of page faults caused by the execution of the statement.

CUM % is the percentage of program execution time taken by the statement and all preceding statements.

% is the percentage of program execution time taken by the statement. 2-14 Chapter 2: Compiling a Source Module

Specifying the Subset of ANSI COBOLSpecifying the Subset of ANSI COBOLThe VOS COBOL compiler supports the ANSI Programming Language COBOL standards X3.23-1985 (COBOL-85) and X3.23-1974 (COBOL-74). In addition, the compiler implements specific extensions to ANSI Standard COBOL. Users can compile using a COBOL-74 option that includes the VOS extensions available with previous releases, a full ANSI COBOL-85 option, or one of two options that invoke intermediate subsets of COBOL-85, that have been implemented for compatibility.

To specify the subset of ANSI COBOL with which to compile the program, use the -language argument. The following list shows the options available with the -language argument.

full_ansi85. This option provides complete COBOL-85 support.

ansi85. This option provides complete COBOL-85 support except for the use of call identifier and cancel statements to reference nested programs and the reinitialization of the ends of perform ranges.

compatible. This option provides the COBOL-85 functionality that is compatible with COBOL-74, except for the introduction of new reserved words.

ansi74. This option provides full ANSI COBOL-74 support and the VOS extensions provided in pre-Release 10.0 VOS COBOL.

If you do not specify a language option in the command line form, the program is compiled with the compatible option. For additional information about the subsets of ANSI COBOL supported by the VOS COBOL compiler, refer to Appendix B.

Diagnosing Language Subset ElementsIf you compile with the ansi74 language option, the level of errors reported is based on the Federal Information Processing Standard (FIPS) Level defined by the ANSI-74 COBOL standard.

The -level argument of the cobol command instructs the compiler to report all occurrences of language elements whose FIPS level exceeds the number you specify with the argument. The value of the -language argument determines the subset of elements diagnosed. VOS COBOL Users Guide (R142) 2-15

Specifying the Subset of ANSI COBOLThe following table shows the levels at which errors are diagnosed if you specify the ansi74 language option.

Refer to the ANSI-74 COBOL standard for a list of what is included in each subset.

Figure 2-8 shows the sample program, monthly_sales, compiled with -language ansi74 and -level 4.

THE FOLLOWING FEATURES ARE VIOLATIONS OF SUBSET LEVEL 4

Use of non-COBOL characters (2EXT) on lines 2, 11, 15, 21, 22, 23, 24, 25, 26, 28, 29, 30, 31, 34, 35, 37, 38, 39, 40, 42, 45, 46, 47, 48, 49, 55, 56, 57, 58, 59, 60, 64, 65, 67, 68, 69, 70 Omission of Configuration Section (2EXT) on line 9

Omission of the LABEL RECORDS clause (2EXT) on lines 21, 28

Use of // to delimit end-of-line comment (2EXT) on lines 21, 22, 28, 34

Use of in-line PERFORM sequences (1EXT) on line 66

TOTAL OF 5 VIOLATIONS OF FIPS HIGH LEVEL

8

Figure 2-8. FIPS Level Errors

If you compile with the compatible, ansi85, or full_ansi85 language options, the level of errors reported is based on the 1985 ANSI Standard.

Level Subset 1 All elements not in the FIPS low subset. 2 All elements not in the FIPS low-intermediate

subset.3 All elements not in the FIPS

high-intermediate subset. 4 All elements not in the FIPS high subset (that

is, VOS COBOL extensions). 2-16 Chapter 2: Compiling a Source Module

Specifying a ProcessorThe following table shows the levels at which errors are diagnosed when you compile with the compatible, ansi85, or full_ansi85 language option.

Refer to the ANSI Standard for a list of what is included in each subset.

Figure 2-9 shows the sample program, monthly_sales, compiled with -language compatible and -level 4.

THE FOLLOWING FEATURES ARE VIOLATIONS OF SUBSET LEVEL 4

Use of non-COBOL characters (EXT)/5 on lines 2, 11, 15, 21, 22, 23, 24, 25, 26, 28, 29, 30, 31, 34, 35, 37, 38, 39, 40, 42, 45, 46, 47, 48, 49, 55, 56, 57, 58, 59, 60, 64, 65, 67, 68, 69, 70 Use of // to delimit end-of-line comment (EXT)/5 on lines 21, 22, 28, 34

TOTAL OF 2 VIOLATIONS OF THE HIGH SUBSET INCLUDING OBSOLETE ELEMENTS

9

Figure 2-9. ANSI Subset Errors

Specifying a ProcessorThe compiler generates code that will run on the default system processor. Unless your system administrator has changed the default system processor, it is the MC68000 processor. To generate code for other processors, you specify the -processor argument

with a processor option when you compile the source module. When you use this argument, the compiler creates object code customized for use on the processor specified by the processor option. As a result, the code runs faster on the specified processor, but cannot, in some cases, run on alternate processors.

Level Subset 1 All elements not in the ANSI COBOL-85

minimum subset. 2 All elements not in the ANSI COBOL-85

intermediate subset. 3 All elements not in the ANSI COBOL-85 high

subset. This subset does not include obsolete items and VOS COBOL extensions.

4 All elements not in the ANSI COBOL-85 high subset (that is, VOS COBOL extensions). This subset includes VOS COBOL extensions, but does not include obsolete items. VOS COBOL Users Guide (R142) 2-17

Specifying the Defaults for Data AttributesIf you select the -processor argument, you can specify one of eight options: default, mc68000, mc68010, mc68010/arithmetic_processor, mc68020, mc68020/mc68881, mc68030, and mc68030/mc68882.

Table 2-2 gives the processor and model number for which each option generates code.

2

Specifying the Defaults for Data AttributesThe VOS COBOL compiler enables you to specify the following data attribute defaults.

Default computational value Default sign Default allocation type

Specifying the Computational ValueNormally, data defined as comp in COBOL is given a type based on the picture clause description. The compiler selects the best data type for the picture description. However, with the -default_comp argument you can specify explicit comp values. For example, comp-3 and comp-6 make reasonable defaults because they are able to represent data having any valid numeric picture; comp-3 data is packed, comp-6 data is variable-length.

Table 2-2. Options That Specify a Processor

Option Processor Model

default systems processor default

mc68000 MC68000 or MC68010 with or without an arithmetic processor

XA400

mc68010 MC68010 with or without an arithmetic processor

XA400

mc68010/arithmetic_processor

MC68010 with an arithmetic processor

XA600

mc68020 MC68020 with or without the MC68881 co-processor

XA2000 Model 100

mc68020/mc68881 MC68020 with the MC68881 co-processor

XA2000 Model 110 to XA2000 Model 160

mc68030 MC68030 with or without the MC68882 co-processor

XA2000 Model 30 and XA2000 Model 200 to XA2000 Model 260

mc68030/mc68882 MC68030 with the MC68882 co-processor

XA2000 Model 30 and XA2000 Model 200 to XA2000 Model 2602-18 Chapter 2: Compiling a Source Module

Specifying how the Compiler Interprets TextSpecifying the Default SignThe -default_sign argument enables you to set the default sign type for numeric data items. The possible values are leading_separate, trailing_separate, leading_embedded, and trailing_embedded. If you do not specify a default sign type, the compiler assumes trailing_embedded.

Specifying the Default Allocation TypeThe -default_class argument enables you to specify how uninitialized working-storage data should be allocated. The following list shows the possible values.

static. Static storage is used for data names, such as error codes, that must retain their values between calls to a procedure. Static storage is allocated once within the program module prior to program execution.

auto. Automatic storage is used for data names whose values can change each time a procedure is called. Storage for automatic data names is allocated each time the containing program is activated. If a program is called recursively, each stack frame for that program contains an instance of each automatic data name declared in that program.

The default is static. When you use the redefines statement for Level-1 data, the redefining data of a data name defined by auto class must not be longer than the object being redefined.

Note: You cannot initialize automatic data. If you attempt to use this argument to initialize automatic data, the variable is treated as static.

Specifying how the Compiler Interprets TextThe VOS COBOL compiler enables you to specify the following, relative to the interpretation of the source module.

Mapcasing Indentation String replacement

Specifying the Interpretation of Uppercase LettersThe compiler interprets uppercase letters differently from lowercase letters. You can make the compiler appear to be case insensitive by specifying the -mapcase argument. When you select the -mapcase argument, the compiler interprets uppercase letters as their lowercase counterparts, except for uppercase letters in character-string constants.

Note: When you compile a source module with the -mapcase argument, and the module contains an external variable name or entry name with one or more uppercase letters, you may not be able to bind the resulting object module with other programs that define the same external variable and have not been compiled with the -mapcase argument. If the binder encounters a reference to the original name, for example in a binder control file, it will not recognize the original name and its lowercase version as the same name. VOS COBOL Users Guide (R142) 2-19

Specifying how the Compiler Interprets TextSpecifying FormatVOS COBOL allows you to write your program in free format. The -format argument tells the compiler that the source program is in free format, rather than in standard fixed format. If you write your program in free format and use the -format argument, all include files must be in the same format as the file that includes them. In nearly all cases, fixed format source is acceptable as free format; however, there are a few rules that apply to free format text. These rules are described in VOS COBOL Programmers Guide (R077).

Note: The -format argument does not reformat your program; it merely instructs the compiler to interpret it as a formatted program. If your program is written in free format and you format it with the format_cobol_source command, the source is overwritten in indented format (thus, no longer in free format). If you format your program in this way, you should not attempt to compile it with the -format argument.

Specifying the Method of String ReplacementVOS COBOL supports both the ANSI replace statement and the VOS COBOL %replace compiler directive.

The %replace compiler directive implemented in the pre-Release 10.0 VOS COBOL compiler provides most of the useful functionality of the ANSI replace statement and is more efficient, since the ANSI replace statement requires that the source file be preprocessed.

The compiler processes simple replace statements as %replace compiler directives, by replacing one word with another during the compilation. If the statement is more complex (that is, the string being replaced contains more than one word), it cannot be handled as a %replace directive. The compiler then preprocesses the remainder of the source file, beginning with that replace sequence.

If you specify the -ansi_replace argument, the compiler initially preprocesses the entire source file, so that all replace statements are treated consistently. When the source file is preprocessed, the source that is compiled is not identical to that contained in the original file. Instead, a temporary source file is created that contains the source with all text replacements made. If you specify the -table or -production_table argument, and preprocessing is required, these temporary expanded source files are created in the same directory as the object module and are not deleted following compilation. The debugger uses these files when you request source line information. The expanded source file is named _program_name.1.r and expanded copy files are named _program_name.nn.rc, where program_name is the source file name and nn is the number of the copy file shown on the listing. You can delete these files at any time. However, if you delete them and then try to reference source code in which a replacement has been made, the debugger returns a message that the source is not available.

For further information about the replace statement and the %replace compiler directive, refer to VOS COBOL Language Manual (R010). 2-20 Chapter 2: Compiling a Source Module

Optimizing the Object CodeOptimizing the Object CodeThe compiler optimizes the object code during compilation unless you specify the -no_optimize argument. Optimization produces more compact object code by removing unnecessary or redundant computations. The types of optimization include the following:

elimination of common subexpressions constant folding, replacing expressions that consist solely of constant operands loop optimization, such as removing invariant computations.

Certain types of optimization cause code motion. For example, optimization removes invariant computations from loops. If the compiler encounters an error during or after the optimization phase, it may issue an error message with a line number that corresponds to a line of the optimized code and not a source code line.

Other Compiler ArgumentsIn addition to the compiler arguments described in this chapter, the VOS COBOL compiler provides the following, less frequently used arguments.

The -main argument enables you to compile the source module in a form that identifies the program as a main program. This allows the external switches to be set when the program is called, and it allows special treatment of the exit program statement.

Note: This argument is rarely used. It is available with the pre-Release 10.0 VOS COBOL compiler or the Release 10.0 VOS COBOL compiler.

The -segmentation argument inserts code in the object module that initializes every independent segment each time control is transferred to it, if required. This argument is meaningful only if an independent segment contains an alterable go to statement.

Note: This argument is rarely used. It is available with the pre-Release 10.0 VOS COBOL compiler or the Release 10.0 VOS COBOL compiler.

The -debugging_mode argument enables you to compile the program as if the debugging mode clause were specified in the special-names paragraph.

For more information about segmentation and the debugging mode clause, refer to VOS COBOL Language Manual (R010). VOS COBOL Users Guide (R142) 2-21

Other Compiler Arguments2-22 Chapter 2: Compiling a Source Module

Chapter 3: Binding Object Modules 3-

The bind command combines a set of one or more object modules into a program module. Binding compacts the code and resolves symbolic references to external programs and variables that are shared by the modules in a set and in the object library. The object library is the directory in which the binder searches for the object modules of the predefined COBOL functions and procedures.

This chapter explains how to use the bind command and its arguments to perform the following tasks:

specifying the object module or modules specifying the search rules for finding object modules generating a bind map specifying the size of a programs address space displaying statistics about the binding implementing a binder control file (useful for repeated binds and essential for tasking).

The bind commands display form is as follows:

Display Form

Access RequirementsYou need read access to all the object modules you are binding. You need modify access to the current directory.

Specifying the Object Module or ModulesYou can specify the object module or modules to bind by using the object_modules command argument or by specifying the object module names in a binder control file.

------------------------------------- bind ------------------------------------object_modules: -control:-search:-compact: yes-map: no-retain_all: no-size: small-statistics: no-table: yesVOS COBOL Users Guide (R142) 3-1

Locating Object Modules and Entry PointsWith the object_modules argument, you specify the object module by entering the object module name. The object module name refers to the name of the file that contains the compiled source program, and has the suffix .obj. The first module listed specifies the main entry point to the program.

If an object module contains a call to an entry point that is defined in another object module, you do not need to specify the name of the latter object module if the object module and the entry point have the same name. To call an entry point whose name differs from the name of the object module in which it is defined, you must specify the name of the object module to the binder. For example, if a program calls the entries mul and div and these are separately compiled as mul.obj and div.obj, you do not need to list these object modules for the binder. If mul and div are entry points within do_arithmetic.obj, though, you must list do_arithmetic as one of the object modules to be bound. The syntax for specifying object module names with the bind command is as follows:

bind object_module ...

You can also specify an object module by writing a binder control file that directs the binder to the object module files. See Writing a Binder Control File, later in this chapter, for more information about this file.

Locating Object Modules and Entry PointsThe binder links together the object modules you have specified and additional object modules that are referenced as entry points within the object modules being bound. Each object module can contain calls to additional entry points that are defined within other object modules.

You must be aware of where these object modules and entry points are located, and instruct the binder how to find them. The following section describes several ways to do this.

Specifying the Search Rules for Finding Object ModulesTo find the files that you have specified in the object_m