VOS COBOL User Guide

R142-00
VOS COBOL Users Guide
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. 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: R142 Revision Number: 00 VOS 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 Manual
The 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.
Audience
This 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 Information
This is the first publication of this manual. For information on which release of the software this manual documents, see the Notice page.
Manual Organization
This 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
Preface
Appendix 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.
Notation
Stratus 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 Notation
A 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
Preface
In 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 Manuals
Refer 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)
Preface
vi
Preface
Contents
1. Overview: Programming in VOS COBOL . . Preparing a Source Program . . . . . . . Compiling a Source Module . . . . . . . Binding Object Modules . . . . . . . . . Executing and Interrupting a Program Module
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . .
1-1 1-3 1-3 1-4 1-4 2-1 2-2 2-3 2-6 2-8 2-9 2-9 2-10 2-11 2-12 2-13 2-15 2-15 2-17 2-18 2-18 2-19 2-19 2-19 2-19 2-20 2-20 2-21 2-21 3-1 3-1 3-2 3-2 3-3 3-3
2. Compiling a Source Module . . . . . . . . . . . . . . . Creating a Program Listing. . . . . . . . . . . . . . . Creating a Compilation Listing. . . . . . . . . . . Creating a Cross-Reference Listing . . . . . . . . . Producing an Assembly Language Listing . . . . . . Compiler Arguments That Affect the 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 . . . . . . . . . Diagnosing Language Subset Elements . . . . . . . Specifying a Processor . . . . . . . . . . . . . . . . Specifying the Defaults for Data Attributes . . . . . . . . Specifying the Computational Value . . . . . . . . Specifying the Default Sign . . . . . . . . . . . . Specifying the Default Allocation Type . . . . . . . Specifying how the Compiler Interprets Text. . . . . . . . Specifying the Interpretation of Uppercase Letters . . . Specifying Format. . . . . . . . . . . . . . . . Specifying the Method of String Replacement . . . . . Optimizing the Object Code . . . . . . . . . . . . . . Other Compiler Arguments . . . . . . . . . . . . . . 3. Binding Object Modules. . . . . . . . . . . . . . . . . Specifying the Object Module or Modules. . . . . . . . . Locating Object Modules and Entry Points . . . . . . . . Specifying the Search Rules for Finding Object Modules The add_entry_names Command . . . . . . . . Calling External and Internal Entry Points . . . . . .
. . . . . .
vii
Contents
Specifying Retained Entry Points . . . . . . . . . Generating a Bind Map . . . . . . . . . . . . . . . Specifying the Size of a Programs Address Space . . . . Displaying Statistics about the Binding . . . . . . . . . Writing a Binder Control File. . . . . . . . . . . . . Specifying Required Directives . . . . . . . . . Specifying Optional Directives. . . . . . . . . . Replacing bind Command Arguments with Directives
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
3-4 3-4 3-6 3-8 3-9 3-9 3-11 3-14 4-1 4-3 4-3 4-3 4-4 4-4 4-5 4-5 4-5 4-6 4-6 4-7 4-8 4-9 4-9 4-10 4-11 4-12 4-12 4-13 4-13 4-14 4-14 4-15 4-15 4-16 4-17 4-17 4-21 4-21 4-21 4-22 4-23 4-24 4-24 4-25 4-26 4-27 4-28 4-28
4. Debugging a Program Module . . . . . . . . . . . . . . . . . Preparing a Program for Debugging . . . . . . . . . . . . . . Invoking the Debugger . . . . . . . . . . . . . . . . . . . From Command Level on a Program Module . . . . . . . . From Command Level on a Keep Module . . . . . . . . . From Break Level on a Program Module . . . . . . . . . . Getting Started . . . . . . . . . . . . . . . . . . . . . . Defining Terms . . . . . . . . . . . . . . . . . . . . Entering Debugger Requests. . . . . . . . . . . . . . . Getting Online Help . . . . . . . . . . . . . . . . . . Ending and Interrupting a Debugging Session . . . . . . . . Displaying Source Code . . . . . . . . . . . . . . . . Moving Backwards and Forwards in Source Code . . . . . . Starting Program Execution . . . . . . . . . . . . . . . Listing Frames on the Stack . . . . . . . . . . . . . . . Moving from One Block to Another. . . . . . . . . . . . Using Breakpoints . . . . . . . . . . . . . . . . . . . . . Setting Breakpoints . . . . . . . . . . . . . . . . . . Issuing Requests from Breakpoints . . . . . . . . . . . . Displaying an Expressions Value . . . . . . . . . . Displaying Declaration Information . . . . . . . . . Changing a Data Items Value . . . . . . . . . . . Continuing Program Execution . . . . . . . . . . . Setting Another Breakpoint. . . . . . . . . . . . . Using Conditional Requests at Breakpoints . . . . . . Clearing Breakpoints. . . . . . . . . . . . . . . . . . Listing Breakpoints . . . . . . . . . . . . . . . . . . Stepping through a Program . . . . . . . . . . . . . . . . . Using Additional Debugger Requests. . . . . . . . . . . . . . Calling a Procedure . . . . . . . . . . . . . . . . . . Displaying Arguments . . . . . . . . . . . . . . . . . Checking That the Source Module Corresponds to the Program . Checking a Tasks Status . . . . . . . . . . . . . . . . Examining a Programs Assembly Code . . . . . . . . . . Examining a Lines Assembly Code . . . . . . . . . Examining Registers . . . . . . . . . . . . . . . Displaying a Variables Address and Contents . . . . . Using Shortcuts in the Debugger . . . . . . . . . . . . . . . Abbreviating Requests . . . . . . . . . . . . . . . . . Using VOS Commands. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
viii
Contents
Contents
5. The VOS COBOL I/O System . . . . . . . . . . . . . I/O System Objects . . . . . . . . . . . . . . . . . Files . . . . . . . . . . . . . . . . . . . . Sequential File Organization . . . . . . . . Stream File Organization . . . . . . . . . Fixed File Organization . . . . . . . . . . Relative File Organization . . . . . . . . . Access Modes . . . . . . . . . . . . . . . . File Indexes . . . . . . . . . . . . . . . . . File Errors . . . . . . . . . . . . . . . . . . Error Handling . . . . . . . . . . . . . . . . I/O Ports . . . . . . . . . . . . . . . . . . File and Record Locking. . . . . . . . . . . . . . . I/O Type . . . . . . . . . . . . . . . . . . . . . VOS COBOL I/O Summary . . . . . . . . . . . . . Opening a File . . . . . . . . . . . . . . . . File Organization . . . . . . . . . . . . . . . . . Integrating File System Commands with VOS COBOL . . Tape Handling Requirements . . . . . . . . . . . . . File Characteristics . . . . . . . . . . . . . . Mounting the Tape . . . . . . . . . . . . . . File Positioning at open . . . . . . . . . . . . File Positioning at close . . . . . . . . . . . Positioning the Reel During Multi-reel File Processing Printer Files. . . . . . . . . . . . . . . . . . . . 6. Calling Programs in Other VOS Languages . . . . . Calling a Subprogram . . . . . . . . . . . . . . Calling a Function . . . . . . . . . . . . . . . Passing Data . . . . . . . . . . . . . . . . . Referencing VOS COBOL Programs . . . . . . . . A VOS COBOL Subprogram . . . . . . . . A VOS COBOL Function . . . . . . . . . . Referencing VOS PL/I Programs . . . . . . . . . A VOS PL/I Procedure . . . . . . . . . . . A VOS PL/I Function . . . . . . . . . . . Calling a PL/I Program with Dope . . . . . . Specifying PL/I Data Types . . . . . . . . . Referencing VOS Pascal Programs . . . . . . . . A VOS Pascal Procedure . . . . . . . . . . A VOS Pascal Function . . . . . . . . . . Specifying Pascal Data Types . . . . . . . . Referencing VOS C Functions . . . . . . . . . . A VOS C Function That Does Not Return a Value A VOS C Function That Returns a Value. . . . Specifying C Data Types . . . . . . . . . . Referencing VOS FORTRAN Programs . . . . . . A VOS FORTRAN Subroutine. . . . . . . . A VOS FORTRAN Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . .
5-1 5-1 5-1 5-2 5-3 5-4 5-4 5-5 5-6 5-6 5-8 5-8 5-9 5-12 5-12 5-12 5-13 5-15 5-17 5-18 5-18 5-18 5-19 5-19 5-20 6-1 6-3 6-4 6-4 6-5 6-5 6-5 6-6 6-7 6-7 6-8 6-8 6-9 6-9 6-10 6-10 6-11 6-11 6-12 6-12 6-13 6-13 6-14
. . . . . . . . . . . . . .
ix
Contents
Specifying FORTRAN Data Types Referencing VOS BASIC Programs . . A VOS BASIC Subprogram . . . Specifying BASIC Data Types . .
. . . .
. . . .
. . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
6-14 6-15 6-15 6-15 7-1 7-2 7-3 7-4 7-4 7-4 7-5 7-6 A-1 B-1 B-1 B-2 B-3 B-4 B-4 B-5 B-5 B-5 B-6 B-6 B-6 B-7 B-7 B-8 B-8 B-8 B-8 B-9 B-9 B-9 B-11 B-11 B-12 B-12 B-12 B-13 B-14 B-14 B-14 B-15
7. National Language Support and VOS COBOL . NLS String Representation . . . . . . Shift Characters and NLS Strings . . . . Canonical Strings . . . . . . . Common Strings . . . . . . . . Default Character Sets of String Constants Checking the Contents of Strings . . . . Character Sets and NLS Functions . . .
Appendix A. The VOS Character Code Set . . . . . . . . . . . . . . . . . . . . . . Appendix B. Differences Between COBOL-74 and COBOL-85 . . . . VOS COBOL Compiler Language Options . . . . . . . . . . . The full_ansi85 Language Option . . . . . . . . . . The ansi85 Language Option . . . . . . . . . . . . . The compatible Language Option . . . . . . . . . . . The ansi74 Language Option . . . . . . . . . . . . . VOS COBOL Language Differences . . . . . . . . . . . . . . New Functionality. . . . . . . . . . . . . . . . . . . Specifying -ansi_replace . . . . . . . . . . . Defining Default Class Storage . . . . . . . . . . . Using Label Variables. . . . . . . . . . . . . . . Using Entry Variables . . . . . . . . . . . . . . . Defining Functions with Procedure Division Syntax . . . Specifying Recursive Programs . . . . . . . . . . . Eliminating Words with the %replace Directive . . . Differences Between the full_ansi85 and ansi85 Options Support of the cancel Statement . . . . . . . . . . Reinitialization of perform Ranges . . . . . . . . . Differences Between the ansi85 and compatible Options . Support for global Data Names and File Names . . . I/O Incompatibilities . . . . . . . . . . . . . . . Nested Programs . . . . . . . . . . . . . . . . . Obsolete Elements . . . . . . . . . . . . . . . . The perform ... varying Statement . . . . . . Alphabetic Class Test . . . . . . . . . . . . . . . Variable-Length Assignments. . . . . . . . . . . . Restrictions Generating Compiler Errors . . . . . . . Differences Between the compatible and ansi74 Options . Lifted Restriction on program-id . . . . . . . . . New Reserved Words . . . . . . . . . . . . . . . Upgrading Programs from COBOL-74 to COBOL-85 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Contents
Appendix C. Summary of VOS COBOL Commands . cobol . . . . . . . . . . . . . . . . . . bind . . . . . . . . . . . . . . . . . . Binder Control File . . . . . . . . . . . . . Syntax, Comments, and Empty Lines. . . . . . Directives . . . . . . . . . . . . . . . . debug . . . . . . . . . . . . . . . . . . Source Mode Debugging . . . . . . . . . . Frequently Used Arguments . . . . . . . Source Mode Requests . . . . . . . . . Object Mode Debugging. . . . . . . . . . . format_cobol_source . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
C-1 C-2 C-6 C-8 C-8 C-8 C-12 C-13 C-13 C-14 C-17 C-18
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Glossary-1
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1
xi
Figures
Figure 1-1. Program Development Process . . . . . . . . . . . Figure 2-1. Compilation Listing . . . . . . . . . . . . . . . Figure 2-2. Cross-Reference Listing. . . . . . . . . . . . . . Figure 2-3. Sorted Cross-Reference Listing . . . . . . . . . . . Figure 2-4. Assembly Language Listing . . . . . . . . . . . . Figure 2-5. Compilation Listing with a Run-Time Error . . . . . . Figure 2-6. Compilation Statistics . . . . . . . . . . . . . . Figure 2-7. Run-Time Performance Information of a Program Module Figure 2-8. FIPS Level Errors . . . . . . . . . . . . . . . . Figure 2-9. ANSI Subset Errors . . . . . . . . . . . . . . . Figure 3-1. Bind Map for monthly_sales.pm . . . . . . . . . Figure 3-2. Program Address Space . . . . . . . . . . . . . . Figure 3-3. Binder Statistics . . . . . . . . . . . . . . . . . Figure 4-1. Displaying the Declaration Information of a Data Name . Figure 4-2. Using Conditional Requests . . . . . . . . . . . . Figure 4-3. Stepping through a Program . . . . . . . . . . . . Figure 4-4. Stepping Into a Procedure . . . . . . . . . . . . . Figure 4-5. Stepping Past a Procedure . . . . . . . . . . . . . Figure 4-6. Displaying the Arguments Associated with a Procedure . Figure 4-7. Displaying the Assembly Code Translation of a Line . . Figure 4-8. Displaying the Contents of Registers. . . . . . . . . Figure 4-9. Displaying a Dump of a Variable . . . . . . . . . . Figure 5-1. Sequential File Organization . . . . . . . . . . . . Figure 5-2. Stream File Organization . . . . . . . . . . . . . Figure 5-3. Fixed File Organization . . . . . . . . . . . . . . Figure 5-4. Relative File Organization . . . . . . . . . . . . . Figure 7-1. The VOS Internal Character Coding System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 2-5 2-7 2-8 2-8 2-10 2-12 2-14 2-16 2-17 3-6 3-7 3-8 4-14 4-16 4-18 4-19 4-20 4-22 4-25 4-26 4-27 5-3 5-3 5-4 5-5 7-3
xii
Figures
Tables
Table 2-1. Arguments That Create Compilation Listings. . . . Table 2-2. Options That Specify a Processor . . . . . . . . Table 3-1. Directives That Replace bind Command Arguments Table 4-1. Debugger Requests . . . . . . . . . . . . . . Table 4-2. Break Level Requests . . . . . . . . . . . . . Table 5-1. Run-Time Access Modes. . . . . . . . . . . . Table 5-2. Lock Mode Values . . . . . . . . . . . . . . Table 5-3. Mapping of VOS COBOL Open Mode to I/O Type . Table 5-4. Files Supported Using Output Mode . . . . . . . Table 5-5. File System Commands and Subroutines . . . . . Table 6-1. Cross-Language Compatibility . . . . . . . . . Table 7-1. Number of Bytes per Character . . . . . . . . . Table 7-2. Default Character Set Options. . . . . . . . . . Table 7-3. NLS Mnemonic Names and Character Set IDs . . . Table A-1. VOS Character Code Set . . . . . . . . . . . Table B-1. COBOL-85 and COBOL-74 File Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 . 2-18 . 3-14 . 4-1 . 4-7 . 5-6 . 5-11 . 5-13 . 5-13 . 5-16 . 6-2 . 7-2 . 7-4 . 7-7 . A-1 . B-10
xiii
Tables
xiv
Tables
Chapter 1: Overview: Programming in VOS COBOL

This chapter gives an overview of the steps used to prepare and execute a COBOL program. These steps are as follows:
1-
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.
1-1
Overview: Programming in VOS COBOL

1
edit file_name Source Module file_name.cobol Error Listing file_name.error
Compile Time
Compiler Listing cobol file_name file_name.list
Compiler Errors? No Object Module file_name.obj
Yes
Bind Time
other object module
Binder bind file_name
Binder Errors? No Program Module file_name.pm
Yes
Test Program
Test/Debug
file_name Debug Errors? No Error Free Executable Program file_name.pm Yes debug file_name or debug filename.kp
Run Time
PD0038
Figure 1-1. Program Development Process

1-2 Chapter 1: Overview: Programming in VOS COBOL
Preparing a Source Program
Preparing a Source Program

A 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 Module

When 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.
1-3
Binding Object Modules
Binding Object Modules

After 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 Module

This 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 <RETURN>. 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
To interrupt the execution of the program module, press <CTRL><BREAK>. The following prompt then appears on the screen.
BREAK Request? (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.
1-5
1-6
Chapter 2: Compiling a Source Module

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:
2-
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.
2-1
Creating a Program Listing
The cobol commands display form is as follows:
Display Form
------------------------------------- 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
Access Requirements
You 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.

A 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
Table 2-1. Arguments That Create Compilation Listings Option

-list -xref
Contents of Listing Compilation listing and symbol listing Compilation listing, symbol listing, and cross-reference listing Compilation listing, symbol listing, and cross-reference listing Compilation listing, symbol listing, and assembly language listing
-xref_format
-full
2-2
Creating a Compilation Listing

If 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.cobol COMPILED ON: 89-11-26 AT 11:39 BY COBOL Release 10 OPTIONS: -list 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
2.
(Continued on next page)
2-3

44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 3. procedure division. main_paragraph. open input raw_sales. perform add_it until end_flag is equal to y. close raw_sales. perform summary_and_cleanup. call write_report. exit program. * This paragraph assigns rep number and keeps running totals. add_it. read raw_sales into sales_record at end move y to end_flag not at end divide rep_number by 10000 giving region add trans_amount region_info(region) giving region_info(region). * This paragraph writes running totals to output file. summary_and_cleanup. open output sales_by_region. perform varying region from 1 by 1 until region > 5 move region to region_out move region_info(region) to region_total write sales_totals. close sales_by_region. TYPE/CLASS program-name entry-name SIZE LOC ATTRIBUTES external external
NAME monthly_sales report_writer
0004
DATA-NAMES FOR PROCEDURE monthly_sales add_it paragraph-name end_flag data/alphanum f/raw_sales data/group f/sales_by_region data/group main_paragraph paragraph-name raw_sales file-name raw_sales_record data/group rep_number_in data/numeric name_in data/alphanum transaction_number_in data/numeric region data/numeric regional_sales data/group region_info data/numeric . . . PROGRAMMED OPERATORS USED IN THIS div_long_int assign_chars 0184 0034 00dc 0038 00dc 0188 0 5 19 01ae 0010 0 seq/seq record display, pic 9(5) pic x(20) display, pic 9(6) display, pic 9 display, pic 9(5)v99, occurs 5
1 164 164 38 38 5 20 6 1 35 7
pic x
4.
COMPILATION: cobol_decimal_to_fixdec
fixdec_to_cobol_decimal mult_long_int_nofofl
2-4

5. 6. CODE GENERATED FOR PROCESSOR: mc68000 STACK FRAME SIZES: (fixed length portion only) NAME monthly_sales 7. LINE 44 STACK SIZE 76
WARNING 383 SEVERITY 1 BEGINNING ON LINE 37 An 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 Cross-Reference Listing

If 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
Figure 2-2 shows the cross-reference listing, in the standard format, for the program monthly_sales.
NAME monthly_sales write_report TYPE/CLASS program-name entry-name 0004 external Implicit Def 50 Ref 50 SIZE LOC ATTRIBUTES/REFERENCES external Def 44 No Refs
DATA-NAMES FOR PROCEDURE monthly_sales add_it end_flag f/raw_sales f/sales_by_region main_paragraph raw_sales raw_sales_record rep_number_in name_in paragraph-name data/alphanum data/group data/group paragraph-name file-name data/group data/numeric data/alphanum 0184 Def 55 Ref 47 0034 pic x Def 42 Ref 47 57 00dc Def 11 No Refs 0038 Def 15 No Refs Def 45 No Refs 00dc seq/seq Def 11 Ref 46 48 56 0188 record Def 22 No Refs 0 display, pic 9(5) Def 23 No Refs 5 pic x(20) Def 24 No Refs 19 display, pic 9(6) Def 25 No Refs 1f pic x(7) Def 26 No Refs
1 164 164 38 38 5 20
transaction_number_in data/numeric trans_amount_in data/alphanum . . . summary_and_cleanup paragraph-name

2
0180 Def 64
Ref 49
Figure 2-2. Cross-Reference Listing
2-7
Figure 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 end_flag Def 42 raw_sales Def 11 region Def 41 region_info Def 40 region_out Def 30 region_total Def 31 rep_number Def 35 sales_by_region Def 15 sales_record Def 34 sales_totals Def 29 summary_and_cleanup Def 64 trans_amount Def 38
3
Ref 47 Ref 47 57 Ref 46 48 56 Ref 58 59 59 66 66 67 68 Ref 59 59 68 Ref 67 Ref 68 Ref 58 Ref 65 70 Ref 56 Ref 69 Ref 49 Ref 59
Figure 2-3. Sorted Cross-Reference Listing
Producing an Assembly Language Listing

If 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
1.
2.
3.
4.
5. LINE 57 =y end_flag
at end move y to end_flag 000001B0 7E79 moveq 000001B2 1B47 8034 move.b
=121,d7 d7,-32716(a5)
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.
2-8
Interpreting Compiler Diagnostics
4. The fifth column contains the operands. 5. The last column contains comments on the code.
Compiler Arguments That Affect the Listing

In 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 Diagnostics

At 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: SEVERITY 2: SEVERITY 3: SEVERITY 4:
Warning Correctable Error Uncorrectable Error: Translation Can Continue 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.
2-9
Checking for Additional Errors at Compile Time and Run Time
A 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 Time

The -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 56 57 58 59 60
5
add_it. read raw_sales into sales_record at end move 'y' to end_flag not at end divide rep_number by 10000 giving region add trans_amount region_info(region) giving region_info(region).
Figure 2-5. Compilation Listing with a Run-Time Error
2-10
Creating a Symbol Table for Debugging Purposes
When 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 Purposes

In 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.
2-11
Displaying Compilation Statistics
Displaying Compilation Statistics

If 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 initial parser optimizer allocator code gen total NODE PAGES CODE SIZE STATIC SIZE SYMTAB SIZE SOURCE LINES LINES PER MIN
6
DISK 0 4 7 1 12 24
SECONDS 3 6 2 0 5 16 4 1034 534 230 70 700
SPACE 1 1 1 1 1 1
PAGING 23 96 9 7 62 197
CPU 1 2 1 0 2 6
14:10:31 14:10:37 14:10:39 14:10:39 14:10:44 14:10:45
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
Getting Information about Program Execution

To 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.
2-13
Figure 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: Statements Executed: STATEMENT 44 46 47 48 49 50 51 56 57 58 59 65 66 67 68 69 70 TOTALS: COUNT 1 1 1 1 1 1 1 16 1 16 16 1 1 5 5 5 1 74 18 17 (94.44% of statements) CPU(ms) 0.01 201.43 0.01 45.88 0.00 0.00 0.00 61.42 0.00 4.40 9.83 222.73 0.00 0.00 0.54 10.30 114.51 671.12 PAGES CUM % 0 0.0 0 30.0 0 30.0 0 36.8 0 36.8 0 36.8 0 36.8 0 46.0 0 46.0 0 46.6 0 48.1 0 81.3 0 81.3 0 81.3 0 81.4 0 82.9 0 100.0 0 % 0.00 30.01 0.00 6.83 0.00 0.00 0.00 9.15 0.00 0.65 1.46 33.18 0.00 0.00 0.08 1.53 17.06
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
Specifying the Subset of ANSI COBOL

The 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 Elements

If 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.
2-15
The following table shows the levels at which errors are diagnosed if you specify the ansi74 language option. Level
1 2 3 4
Subset All elements not in the FIPS low subset. All elements not in the FIPS low-intermediate subset. All elements not in the FIPS high-intermediate subset. All elements not in the FIPS high subset (that is, VOS COBOL extensions).
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, 26, 28, 29, 39, 40, 42, 56, 57, 58, 69, 70 Omission of Configuration Section (2EXT) on line 9 15, 30, 45, 59, 21, 31, 46, 60, 22, 34, 47, 64, 23, 35, 48, 65, 24, 37, 49, 67, 25, 38, 55, 68,
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.
2-16
Specifying a Processor
The following table shows the levels at which errors are diagnosed when you compile with the compatible, ansi85, or full_ansi85 language option. Level
1 2 3
Subset All elements not in the ANSI COBOL-85 minimum subset. All elements not in the ANSI COBOL-85 intermediate subset. All elements not in the ANSI COBOL-85 high subset. This subset does not include obsolete items and VOS COBOL extensions. 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.
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 Processor
The 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.
2-17
Specifying the Defaults for Data Attributes
If 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
Table 2-2. Options That Specify a Processor Option

default mc68000
Processor systems processor MC68000 or MC68010 with or without an arithmetic processor MC68010 with or without an arithmetic processor MC68010 with an arithmetic processor MC68020 with or without the MC68881 co-processor MC68020 with the MC68881 co-processor MC68030 with or without the MC68882 co-processor MC68030 with the MC68882 co-processor
Model default XA400
mc68010
XA400 XA600 XA2000 Model 100 XA2000 Model 110 to XA2000 Model 160 XA2000 Model 30 and XA2000 Model 200 to XA2000 Model 260 XA2000 Model 30 and XA2000 Model 200 to XA2000 Model 260
mc68010 /arithmetic_processor mc68020
mc68020/mc68881
mc68030
mc68030/mc68882
Specifying the Defaults for Data Attributes

The VOS COBOL compiler enables you to specify the following data attribute defaults.
Default computational value Default sign Default allocation type Specifying the Computational Value
Normally, 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.
2-18
Specifying how the Compiler Interprets Text
Specifying the Default Sign

The -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 Type

The -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.

The 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 Letters

The 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.
Specifying Format
VOS 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 Replacement

VOS 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
Optimizing the Object Code
Optimizing the Object Code

The 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 Arguments

In 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).
2-21
Other Compiler Arguments
2-22
Chapter 3: Binding Object Modules

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:
3-
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
------------------------------------- bind -----------------------------------object_modules: -control: -search: -compact: yes -map: no -retain_all: no -size: small -statistics: no -table: yes
Access Requirements
You need read access to all the object modules you are binding. You need modify access to the current directory.
Specifying the Object Module or Modules

You 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.
3-1
Locating Object Modules and Entry Points
With 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.

The 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 Modules

To find the files that you have specified in the object_module argument, the binder searches directories in the order that follows: 1. any directories specified with the -search argument, in the order in which they are listed 2. any directories specified in the search directive of the binder control file 3. the directories specified by the processs current object library search rules. The -search argument and the search directive enable you to specify one or more directories where the binder is to look before it searches the directories specified by the default search rules. You specify this argument when you have stored object modules in directories other than those listed in your library paths list. The syntax of the -search argument for the bind command is as follows:
bind object_module... -search [search_directory] ...
3-2
For example, the object library search paths could include (current_dir) and %s1#d01>system>object_library. If you want to use an object module stored in the directory >sales>tools, you could specify the -search argument, naming that directory as follows:
bind commissions -search >sales>tools
If you specify the -search argument, but do not specify a directory, the binder searches the current directory before searching any of the directories specified in the binder control file. If you do not use the -search argument to specify a directory, the binder first searches the directories listed in the binder control file search directive and then those listed in master_disk>system>object_library, unless you have redefined the object library paths for your process. Refer to VOS Commands Users Guide (R089) for a complete description of search rules. The binder allows as many command line and/or binder control file search directories (whether specified or default) as memory allows. The binder searches a directory only once, even if it is specified more than once.
The add_entry_names Command

The object module may contain a number of secondary entry points, and other object modules may contain external references to any of these entry points. To bind object modules into a program module, the binder must find a definition for every entry point and external data definition referenced in the program module. The VOS command add_entry_names searches an object library for entry points and creates links to the object modules that contain those entry points. To resolve an external reference in one object module to an external name defined by another, the binder must find a name of the form entry.obj in the object library. Thus, an external name must be identified by a link to an object module, or by the object module itself. The add_entry_names command adds the name of each entry point in an object module as an additional name on the object module file. It adds a link to the object module using the name of the entry point. This command should be run on any directory that is to be included in the object library search paths. The binder searches each directory in the object library search list by looking for an object module with the same name as the unresolved entry name. This command guarantees that all entry names are visible to the binder.
Calling External and Internal Entry Points

VOS COBOL allows users to pass and receive entry points as arguments, set and compare them using the move and if statements, and use them as the operand of the call statement. If you write a nested program, you may have entry points that are not visible to the binder. It is imperative that the entry points name be unique. To convert a character string to an entry
3-3
Generating a Bind Map
variable, you call the operating system subroutine s$find_entry. Or, you can use the compute entry statement to set entry variables from character-string variables.
compute entry entry-var = alphanumeric-expression [on exception ...end-compute]
You can convert an entry constant name to an entry variable name using the set entry statement.
set entry entry-var to program-name.
Unlike the compute entry statement, which requires that the binder retain all entry names, the set entry statement involves no computation. If the value of program-name is not resolved at bind time, the binder issues an error. Refer to the description of the retain directive, later in this chapter, for additional information about retaining entry names. Refer to VOS COBOL Language Manual (R010) for complete information about using the set and compute statements and about nested programs.
Specifying Retained Entry Points

When a subprogram is called by the call literal statement, not all entry points in the subprogram are retained by default. When an entry point is retained, its name is included in the entry map for the program module. Use the -retain_all argument of the bind command to retain all of the subprograms entries, or the retain directive in the binder control file to specify external entry names that the binder places in the programs entry map.

If you select the -map argument, the binder creates, in your current directory, a bind map in a file that has the name of the program module and the suffix .map. The bind map lists the directories searched, the minimum stack size, the main entry points, the external name definitions, and the starting address and length of the following:
code symbol table static storage external variables.
Figure 3-1 shows the contents of a bind map for the sample program monthly_sales.
3-4

Bound for: Jane_Smith.Sales at s1 Bound by: bind, Release 10 Bound on: 89-05-30 07:27:22 EDT Options: -compact -table -search paths -map Program size: small Search directories: 1 2 %s1#d01>sales>object_library %s1#d01>sales>runtime
Other directories: 3 Section paged %s1#d01>sales>tools Code Symtab Unshared Shared Start Length Start Length Start Length Start Length 00E00000 00002ED4 00E05000 00006F30 00E03000 0000081A 00E04000 00000006
Module Map: Name Scn Code Start Length monthly_sales p 00E00000 000003B6 . . . write_report p 00E02968 00000562 External Variable Map: Name Scn Address Length e$invalid_control_operation p 00E04004 00000002 shared s$cobol_fcb_chain p 00E04000 00000004 shared Minimum stack size: 32768 Directory Index Symtab Start Length 1 00E05000 00002A4C Date Compiled Unshared UERW, SAP Start Length 89-06-13 07:33:54 00E03000 00000216
1 00E093A4 00002B8C
89-06-13 07:10:52 00E034E0 0000033A
Main Entrypoint: Name monthly_sales Code Address 00E00038 Unshared Address 00E0B000
External Name Definitions: Name Scn Rgn Ref Address Count e$invalid_control_operation Unshared Length Type Defining Module
3-5
Specifying the Size of a Programs Address Space

p p p s c c 1 00E04004 00000002 variable s$cobol_open_85 0 00E00038 00E0B000 entrypoint monthly_sales 1 00E0298C 00E0B4E0 entrypoint write_report
monthly_sales write_report
Undefined External Names: Name Ref Count Module s$add_epilogue_handler s$attach_port s$close s$control s$create_file
1
Use
Referencing
1 1 1 2 1
entrypoint entrypoint entrypoint entrypoint entrypoint
s$cobol_open_85 s$cobol_open_85 s$cobol_close_85 s$cobol_close_85 s$cobol_open_85
Figure 3-1. Bind Map for monthly_sales.pm

By default, the binder attempts to put the program module into a 2-megabyte address space. If you choose the -size argument, you can specify a larger amount of space. The -size argument takes the options small, large, 2mb, 8mb, and 64mb. The option small specifies the 2-megabyte default. The option large specifies an 8-megabyte address space. The programs address space includes areas for the programs code, static data, and symbol table, as well as stack space and heap space. The external static region is used for global, or shared, variables. In a tasking program, each task has its own space in the user static (unshared) region. In addition, there is a user fence, consisting of eight pages of nonreadable and nonwriteable address space and an area for stack or heap expansion. Figure 3-2 shows the layout of a programs address space.
3-6

2
VOS
800x
FFF(16mb) 47FF(128mb)
User Code User Static (Unshared) External Region (Shared) User Symtab User Maps User Heap User Fence Stack/Heap Expansion User Stack
Process Space
PD0033
Figure 3-2. Program Address Space You must specify the large, 8mb, or 64mb address space if the generated code of all the object modules needs more than 2 megabytes or if a bound program module fits in a smaller space, but insufficient dynamic storage space remains. If there is not enough storage space, the operating system issues an error message and aborts the program when you try to run it. You can rebind the object modules, specifying the large option with the -size argument or the size binder control directive, if the operating system finds insufficient space to run the program.
3-7
Displaying Statistics about the Binding
Displaying Statistics about the Binding

If you select the -statistics argument, the binder displays performance information about each phase of the bind. Figure 3-3 shows what the binder displays for a program bound with the -statistics argument.
Binder Statistics Phase parse pass1 pass2 map TOTAL Seconds 2 14 1 2 19 Paging 15 38 5 5 63 Disk I/O 0 93 0 0 93 47508 237540 4086 15 CPU 1 10 0 1 12
07:23:58 07:24:12 07:24:13 07:24:15 07:24:15
Total bytes: Bytes per minute: Bytes removed: Size of program:

3
Figure 3-3. Binder Statistics The following list describes the information in each column.
Phase gives the phase of the bind: pass1, pass2, and the total of all the phases. If you
use a binder control file, the list includes the binder control file parser before pass1. If you select the -map argument, the time the binder took to create the bind map is included.
Seconds gives the number of seconds the binder took to perform each phase. Paging gives the number of page faults caused by the processing of each phase. Disk I/O gives the number of times the binder had to access the disk to read the binder
control file and the object files, and to read and write to the program module.
CPU gives the number of seconds the CPU took to process each phase.
Below this information, the binder displays the following statistics.
Total bytes is the total number of bytes in the program module before the binder
increased the size of each program section to align with a page of disk space.
Bytes per minute is the number of bytes the binder processed per minute. Bytes removed is the number of bytes the binder removed by compacting the code. Size of program is the number of pages of the program module after the binder
increased the size of each program section to align with a page.
3-8
Writing a Binder Control File

A binder control file is a text file that directs the binding of a set of object modules. You must use a binder control file if you are writing applications that use tasking. A binder control file is also useful if you intend to bind the same module or set of modules more than once and do not want to repeat the command specifications each time. You specify the binder control file with the -control argument. The control file must have the suffix .bind. If you use the -control argument, the binder control file takes the place of most of the arguments you would specify with the bind command. You might, however, want to include the -search argument so that the binder searches your current directory before searching any other directory. The next four sections explain how you write a binder control file. These sections describe the following:
specifying required directives specifying optional directives replacing bind command arguments with directives.
For information on how the binder interprets text, punctuation marks, blank lines, and comments in a binder control file, see the description of the bind command in Appendix C.
Specifying Required Directives

This section describes the two directives that every binder control file must contain: modules and end. Declares the object modules to be bound. The module_specifier identifies the names of the object modules and how the object modules are to be bound. You can give one or more module_specifier arguments; they must be separated by commas. The module_specifier argument is in the form:
(module_term) ...[module_attribute] ...
* modules: module_specifier;
where module_term is a file name or the path name of an object module followed by zero or more module attributes separated by spaces. If module_term is a path name, it can be a relative path name or a full path name, and is not subject to search rules. If the path name includes nonalphanumeric characters, you must enclose it in apostrophes. The suffix .obj is optional. If module_term is a file name, the binder searches first in the directories specified in the -search argument, next in the directories specified by the search directive in the binder control file, and finally in the directories specified in the library paths for that process. Module terms are separated by commas. To indicate that one object module has one or more attributes associated with it, you enclose, within parentheses, the path name of the object module and any module attributes. You can factor common attributes from a series of object module terms and put them outside the parentheses.
3-9
The following list shows the values for module_attribute.
compact no_compact table no_table page_aligned
These attributes affect only those object modules with which they are associated. The compact and no_compact attributes have the same effect as the corresponding -compact and -no_compact command arguments. Likewise, the table and no_table attributes have the same effect as the -table and -no_table command arguments. When you specify these attributes, they override the corresponding command arguments for the specified object module or modules. The page_aligned attribute tells the binder to put the first word in the code region for this object module on a page boundary. It is useful in connection with shared memory. For information on page alignment, see the description of the s$connect_vm_region subroutine in VOS COBOL Subroutines Manual (R019). In the following example, the modules directive indicates that the object modules identified by the relative path names >Sales>outstanding.obj and >Jones>paid.obj are to be bound together. This example also gives >Sales>outstanding.obj the page_aligned attribute.
modules: '>Sales>outstanding.obj' '>Jones>paid.obj'; page_aligned,
In the next example, the modules directive gives both >Sales>outstanding.obj and Sales>paid.obj the page_aligned attribute.
modules: ('>Sales>outstanding.obj', '>Sales>paid.obj') page_aligned; * end;
Indicates the end of the binder control file. This directive must be the last one in the file. If you give more than one end directive, the first one in the file effectively ends the binder control file. The following example shows a binder control file that binds four object modules together. The first two object module names are full path names, %s1#d01>Sales>Jones>addition and %s1#d01>Sales>Jones>subtraction. The third and fourth module names are object names, division and multiplication. The modules directive assigns the page_aligned attribute to
3-10
Writing a Binder Control File %s1#d01>Sales>Jones>addition and the no_table attribute to multiplication. modules: '%s1#d01>Sales>Jones>addition' page_aligned, '%s1#d01>Sales>Jones>subtraction', division, multiplication no_table;
end;
Specifying Optional Directives

This section describes directives that may be useful for your application but are not necessary for all programs. Defines the name of the main entry point of the program. The name identifier must be the name of an entry point in one of the object modules being bound. If you do not use the entry directive, the first non-null entry point the binder finds is used as the main entry point for the program module. If you give more than one entry directive, the binder disregards all but the last one. In the following example, the entry point, read_numbers, is an entry within reading.obj.
modules: reading, calculating, writing; entry: end; * name: program_name; read_numbers;
* entry: identifier;
Specifies a name for the bound program module. If you do not use the name directive, the binder gives the program module the same name as the binder control file. If you do not use a binder control file, the binder gives the program module the name of the first object module. In all cases, the binder gives the program module the suffix .pm. If you include more than one name directive, the binder disregards all but the last one.
In the following example, the name directive gives the name calculator.pm to the resulting program module.
name: calculator; modules: reading, calculating, writing; end;
3-11
Writing a Binder Control File * number_of_tasks: number;
Specifies the number of tasks the binder creates in the program module. The number of tasks is limited only by the program modules total size. Each task has its own stack and its own copy of static storage. If you do not use the number_of_tasks directive, the binder creates one task. Note: The number_of_tasks directive is used exclusively in tasking applications. For more information on tasking, see VOS COBOL Transaction Processing Facility (R034) and VOS Transaction Processing Facility Guide (R215).
* retain: entry_name [as new_name] [, entry_name [as new_name]] ...;
Specifies the external entry names for the binder to place in the program modules entry map. This map contains the entry value for each name. You can specify the names of more than one entry point in a retain directive if you separate the names with commas. If no names are specified, the binder places all entry point names in the map. The as new_name option allows you to specify an alternate name under which the entry point is retained. Specifies the names of directories the binder is to search when it looks for object modules. The specified directories are added to the list of directories given in the -search argument of the bind command. You enclose each directory_name in apostrophes and separate multiple directory_name terms with commas.
* search:directory_name ...;
You can include more than one search directive in a binder control file. Each directive adds more directories to the search list. The binder allows as many command line and binder control file search directories as memory permits. In the following example, the search directive adds two directories, >sales>tools>commissions and >sales>tools>expenses.
search: '>sales>tools>commissions', '>sales>tools>expenses';
The binder searches directories in the following order: 1. those directories specified in the -search command line argument 2. those directories specified in the binder control file search directive 3. the object library paths (those directories whose path names are displayed by the list_library_paths command).
stack_size;
* stack_size:
* variables:variable_specifier ...;
Specifies the number of bytes of storage to reserve for the stack. If you do not specify a stack size, the binder allocates 32,768 bytes for each task. For more information on this directive, see the description of the bind command in Appendix C. Identifies a set of external static variables declared in the object modules.
3-12
In a nontasking program, the binder allocates space for an external static variable in the external static region of the program. In a tasking program, the binder allocates shared variables in the external (or shared) region; it allocates unshared variables on a per-task basis in that tasks region of memory. The variable_specifier argument tells the binder the name of an external static variable. It can also specify the number of bytes to allocate for the variable and an initial value to give to the variable. The form of the variable_specifier argument is:
shared name[(size)][initial (initial_value)] unshared [page_aligned]
The name attribute must be the name of an external static variable in at least one of the object modules being bound. The size attribute is an unsigned integer that indicates the number of bytes allocated for the variable. The binder initializes a character string as a nonvarying character string having the length size. It initializes an arithmetic variable as a 16-bit or 32-bit signed integer. Since a 16-bit integer takes 2 bytes of memory and a 32-bit integer takes 4 bytes, the 16-bit integers size is 2, and the 32-bit integers size is 4. The initial attribute specifies an initial value for the variable. You can shorten the word initial to init. The value of initial_value can be either a character string or an arithmetic constant. If the initial value is a character string, it must be enclosed within apostrophes. An initial value you give a variable in a binder control file overrides an initial value given in a program. The following example of a variables directive declares that the external static variable num_records should be allocated 4 bytes, and that the binder is to initialize the variable to the value 100,000.
variables: num_records (4) init (100000);
In a tasking program, you can share a variable among tasks if you specify, in the binder control file, that the variable is shared. The shared attribute defines a shared variable. The unshared attribute defines an unshared variable. The default attribute is unshared. You must declare a shared variable in each task that shares it. You declare the variable with the same name and specify the external key word with each declaration of the variable. If you specify the shared attribute in the binder control file, the binder allocates memory space for that variable only once. However, if you do not specify the shared attribute in the binder control file, the binder allocates memory space for that variable once for each task.
3-13
In the following example, the variables directive defines the variable global_operand to be shared.
variables: global_operand shared;
When you define more than one variable_name to be shared, you specify shared after each shared variable_name and separate the names with commas, as shown in the following example.
variables: global_operand1 shared, global_operand2 shared;
For more information on shared memory, see the description of the bind command in Appendix C.
Replacing bind Command Arguments with Directives

Directives can replace bind command arguments. This section describes the directives that replace these arguments. Table 3-1 shows the directives and the corresponding bind command arguments.
1
Table 3-1. Directives That Replace bind Command Arguments Directive

options: compact options: no_compact options: no_table options: table size: size_code * options:options ...;
bind Argument
-compact -no_compact -no_table -table -size
Specifies four options that correspond to the bind command arguments -compact, -no_compact, -table, or -no_table. The possible values of options are:
compact no_compact table no_table
* size:
These directives have the same effect as the corresponding bind command arguments. You can specify more than one options directive in a binder control file. Because the parser gives the binder control file only one pass, the last set of options given in the file is used in binding all the object modules. These options override the arguments given in the bind command. However, a compact or no_compact attribute in the modules directive takes precedence over compact or no_compact in the options directive.
size_code;
Specifies the size of the address space in which the binder is to bind the object modules. The possible values of size_code are small (2 megabytes), large (8 megabytes), 2mb, 8mb, and 64mb. You must enclose the values 2mb, 8mb, and 64mb in apostrophes. This directive has the same effect as the bind commands -size argument.
3-14
If you include more than one size directive, the binder disregards all but the last one. A size specified in a binder control file overrides a size given as a command argument. In the following example, the size directive specifies a large address space of 8 megabytes.
size: large;
Examples
The following binder control file produces a program module named auction_tasks. The modules directive lists the object modules to be bound together. The program is a tasking program that supports up to 26 tasks; xyz is a shared variable.
name: entry: number_of_tasks: variables: modules: auction_tasks; auction_tasks; 26; xyz shared;
auction_tasks, /* separately compiled objects */ display_bidder_info, user_form, display_task_info, control_task, create_task, initialize_task, start_task, stop_task; /* FMS screen objects, optional */ /* monitor requests */
retain:
user_tasks_entry, monitor_task_entry, task_epilogue, program_epilogue,
/* task entry points */
/* epilogue handlers */
display_bidder_info, /* programmed monitor request */ display_task_info, control_task, create_task, initialize_task, start_task, stop_task; stack_size: end; 20480; /* monitor requests */
/* equals 5000x */
3-15
3-16
Chapter 4: Debugging a Program Module

The debugger is a tool that allows you to check the logic of a program systematically while the program is running. This chapter provides the information you need to start using the debugger. It describes how to perform the following tasks:
4-
preparing a program for debugging invoking the debugger entering requests using breakpoints stepping through a program using additional debugger requests using shortcuts in the debugger.
Each task description shows sample sessions and examples of how you use the debugger requests. Table 4-1 gives a brief description of each debugger request and tells you which sections in this chapter contain more information about each request. If a request is not described in this chapter, you can find descriptions of each request in Appendix C.
1
Table 4-1. Debugger Requests (Page 1 of 3) Request

args
Description Displays the arguments of the current block. Sets a breakpoint. Invokes a procedure. Clears a breakpoint. Selects cobol mode as the source mode. Continues executing the program. Shows the assembly language code for the current line. Shows an expression, variable, or location.
Section or Appendix Location Displaying Arguments Setting Breakpoints Calling a Procedure Clearing Breakpoints Appendix C Continuing Program Execution Examining a Lines Assembly Code Displaying an Expressions Value
break call clear cobol
continue disassemble
display
4-1
Debugging a Program Module

dump
Description Shows a dump of a variable or location. Sets the block environment. Displays online documentation. Executes one or more requests if a condition is met. Executes one or more requests if a condition is met or executes another request or requests if a condition is not met. Saves a keep module of an interrupted program. Lists breakpoints. Sets the current line backwards or forwards in the source code. Ends the debugging session. Displays the contents of all machine registers. Returns your process to break level after entering from break level. Assigns a value to a data item. Displays one or more lines of source code. Specifies or displays the current source path. Begins program execution. Executes the next statement. Shows a variables data type, size, and location. Displays information about a task or tasks.
Section or Appendix Location Displaying a Variables Address and Contents Moving from One Block to Another Getting Online Help Using Conditional Requests at Breakpoints Using Conditional Requests at Breakpoints
env
help if-then
if-then-else
keep
Appendix C Listing Breakpoints Moving Backwards and Forwards in Source Code Ending and Interrupting a Debugging Session Examining Registers Appendix C Changing a Data Items Value Displaying Source Code Checking That the Source Module Corresponds to the Program Starting Program Execution Stepping through a Program Displaying Declaration Information Checking a Tasks Status
list position
quit
regs
return
set source
source_path
start step symbol
task_status
4-2
Preparing a Program for Debugging

trace
Description Displays all active procedures on the stack. Displays the current environment.
Section or Appendix Location Listing Frames on the Stack Displaying a Variables Address and Contents
where
Preparing a Program for Debugging

To debug a program with the VOS debugger in cobol mode, you first compile the source module using the cobol command with one of the following arguments: -table or -production_table. Both the -table and -production_table arguments incorporate a symbol table into the program module. However, the -table argument enables you to use the full functionality of the debugger, while the -production_table argument enables less functionality but faster execution. In particular, a program compiled with -production_table may produce unpredictable results if you issue the set debugger request or alter the flow of control by specifying a new line number with the continue debugger request. When you compile a source module with the -table or -production_table argument, you do not need to specify any additional arguments with the bind command. The binder automatically copies the symbol table into the program module unless you specify the bind commands -no_table argument.
Invoking the Debugger

You can invoke the debugger in one of two ways: from the command level and from the break level. This section describes how to invoke the debugger:
from command level on a program module from command level on a keep module from break level on a program module. From Command Level on a Program Module
From the command level, you can invoke the debugger to control and examine the execution of a program module. When you invoke the debugger from the command level, the operating system loads the specified program module and puts your process at the debugger request level. The following example shows the debug commands syntax.
debug program_name
4-3
Invoking the Debugger
The following example shows the beginning of a debugging session for the program monthly_sales.
debug monthly_sales Entering debug. New language is cobol. db?
From Command Level on a Keep Module

From the command level, you can invoke the debugger to examine a keep module. A keep module is an image of the program that was interrupted and stored in its interrupted state in a file with the suffix .kp. An interruption is caused by a run-time error or by pressing <CTRL> <BREAK>. In both cases, the operating system places your process at break level. If you enter the keep request or its abbreviation k from break level, the operating system stores the interrupted program in a keep module.
BREAK Request? (stop, continue, debug, keep, login, re-enter) k
If you are running a program in batch mode, the operating system automatically freezes the program in a keep module if an error occurs. To invoke the debugger on a keep module, you enter the debug command and specify the name of the module with the .kp suffix.
debug monthly_sales.kp
Note: You must debug a keep module on the same version of the operating system as you created the keep module on.
From Break Level on a Program Module

From the break level, you invoke the debugger on a program module by issuing the debug request or its abbreviation d. The following example shows the break level prompt and the debuggers opening message and prompt.
Request? (stop, continue, debug, keep, login, re-enter) d Entering debug. New language is cobol. db?
Debugging from the break level allows you to check your program at the point where it halted, whether you caused it to stop by pressing <CTRL> <BREAK> or an error in the program caused it to halt. Occasionally, a program error destroys the information in the stack frame needed by the debugger for some requests. If this information is destroyed, you can find the statement that caused the error by invoking the debugger and stepping through the program or dividing the program with breakpoints until you find the statement causing the error. See Stepping through a Program and Setting Breakpoints, later in this chapter, for more information.
4-4 Chapter 4: Debugging a Program Module
Getting Started
Getting Started
This section introduces you to some of the basic debugger requests and concepts, as follows:
defining terms used with the debugger requests entering debugger requests getting online help ending and interrupting a debugging session displaying source code moving backwards and forwards in source code starting program execution listing frames on the stack moving from one block (procedure or task) to another.
Defining Terms
This section defines some terms that are used in this chapter to describe the debugger requests. A procedure is a program defined within the Procedure Division that provides instructions for processing files or data. A block is synonymous with a procedure. Scope is the block of a program in which a particular declared name is known. The current scope is the scope of the block that is executing. If execution has not started, the current scope is the block where you are positioned. A stack frame is an area of storage that is associated with a block activation. The stack frame holds information that is unique to that activation. This information includes the storage of automatic variables declared within the block and the location to which control returns when the activation is completed. A stack is the area of storage that contains all the stack frames associated with an executing program. The current environment is the latest activation of the block that is executing. If no blocks are executing and you have not issued any requests, the current environment is the main program block of the source module. Certain requests, the env and position requests in particular, change the current environment. For more information on changing the current environment, see Moving from One Block to Another and Moving Backwards and Forwards in Source Code, later in this chapter.
Entering Debugger Requests

After you invoke the debugger, the db? prompt appears on the screen indicating that the debugger is ready to process a request. From this prompt, you can enter one or more requests. You use a semicolon (;) to separate one request from the next. The debugger allows as many requests on a line as will fit within the 300-character per line limit.
4-5
Getting Started
Getting Online Help

Within the debugger, you can get online information about all the debugger requests or more detailed information about one of the requests. To get a list and brief descriptions of all debugger requests, you enter the help request with no arguments. For example, the following help request shows the full help screen.
db? help debug: The following requests are available in debug: basic, cobol, pl1 fortran, pascal, c, machine args break call clear continue continue <l> disassemble display dump env help . . .
Selects language. Displays the arguments of the current block. Sets a breakpoint. Calls a procedure. Clears a breakpoint. Continues executing the program. Continues executing at line number <l>. Disassembles machine code. Displays an expression, variable, or location. Dumps a variable or location. Sets the current debugger environment. Displays online documentation.
To get more detailed information about one debugger request, enter help with the name of the request as an argument. For example, the following help request displays information about the set request.
db? help set set (in debug): set <variable> = <expression> or set <substring> = <expression> Assigns the value of <expression> to <variable> or <substring>.
Ending and Interrupting a Debugging Session

The next two sections explain how to end and interrupt a debugging session. To end your debugging session, enter the quit request.
db? quit
The debugger discards the image of the executing program and all frames on the stack.
4-6
Getting Started
To interrupt a program while it is running, press <CTRL> <BREAK>. When you issue this key sequence, you get the following break level prompt.
BREAK Request? (stop, continue, debug, keep, login, re-enter)
From break level, you can choose one of the six requests shown in the prompt. Table 4-2 lists the requests and describes their functions.
2
Table 4-2. Break Level Requests Break Level Request

stop continue
Function Returns your process to command level. Continues the process, if possible, from where you interrupted it. Starts a new debugging session. You may need to use the env request to set the current line to a block in your program. Stores the executable image in a file named
program_module.kp
debug
keep
login re-enter
Creates a subprocess. Reenables the debugger.
If you select the continue request and execution cannot resume, you are returned to break level. If you cannot continue, an error condition has occurred. From this point, you can terminate the session with the stop request or you can reenter the debugger with the re-enter request. The re-enter request resumes execution from a clean point in the program, if another entry point exists. You can specify the re-enter request if you have specified the s$enable_condition subroutine in the source module. The s$enable_condition subroutine allows you to establish a program that you can then call from break level by issuing the re-enter request. For more information on the s$enable_condition subroutine, see VOS COBOL Subroutines Manual (R019).
Displaying Source Code

To display the source code of a program, you issue the source debugger request with or without an argument. Without an argument, source displays the current line of source code. With a number argument, source displays the number of lines of source code specified by number, starting with the current line. When you issue a source request, the debugger resets the current line to the last source line displayed. Note that the source request does not affect the execution of the program. The execution begins at the main entry point of the program if you have not started the program. If you use the source request from a breakpoint, execution starts at the next executable statement after the breakpoint.
Getting Started
The following example shows the use of the source request with and without an integer specification.
db? source 44 db? source 4 44 45 46 47 db? source 2 47 48 procedure division. procedure division. main_paragraph. open input raw_sales. perform add_it until end_flag is equal to 'y'. perform add_it until end_flag is equal to 'y'. close raw_sales.
Moving Backwards and Forwards in Source Code

When you are checking source code with the source debugger request, you may want to move forward or backwards in the code. To move in either direction, you specify the position request with the identifier argument. The identifier argument designates the name in the source at which the debugger should position itself. In the following example, the debugger positions itself at the first occurence of the data name region in an executable statement.
db? position region 58 divide rep_number by 10000 giving region.
The identifier can also be an unsigned integer that specifies the line number or a signed integer that specifies the line relative to the current position. If identifier is an unsigned integer, the debugger makes the line with that source line number the new current line. In the following example, the position request makes line 20 of the source module the current line, but informs you that the current code address is line 44, the beginning of the Procedure Division.
db? position 20 The code address is set to line 44 (the start of the statement). db? source 20 file section.
In the following example, the position request makes line 44 of the source module the current line.
db? position 44 db? source 44
procedure division.
If identifier is a signed integer, the debugger adds it to the current line number to get the number of the new current line. The debugger, by default, does not count lines in include or copy files in this calculation. By specifying a negative number, you can reset the current line to a previous line in the program. If you want the debugger to count the lines in include files, specify the -include argument with the position request. Note that the position request does not affect program execution.
Getting Started
In the following example, the argument +6 in the first position request changes the current line from line 44 to line 50. In the second position request, the argument -2 changes the current line from line 50 to line 48.
db? position 44 db? source 44 db? position +6 db? source 50 db? position -2 db? source 48
procedure division.
call 'write_report'.
close raw_sales.
You can also search for a character string or specify a line in a called program with the position request.
Starting Program Execution

If you select the start request, the debugger starts executing the program, and does not stop until the end of the program or until the debugger finds a breakpoint. Since no breakpoints have been set, the following start request executes an entire program.
db? start
When the program completes execution, the following message is displayed.

Entering debug after program termination. New language is machine.
For more information on setting breakpoints, see Setting Breakpoints, later in this chapter.
Listing Frames on the Stack

The trace request displays information about the environments with frames on the stack. In VOS COBOL, an environment is the main program or a called program or subroutine. If the program is a tasking program, each task has its own stack and its own set of environments. For more information about debugging tasking programs, refer to Checking a Tasks Status, later in this chapter. An environment does not appear on the stack until the execution of that environment has started. Thus, you generally set a breakpoint in the program, enter the start request to begin execution, and at the breakpoint enter the trace request. When you specify the trace request without specifying a number argument, the request displays the entire stack. The following trace request shows information about two active environments, monthly_sales and write_report. It also shows the line numbers of the statements that are currently executing and the name of the module that contains the two environments.
db? trace # 3: write_report (line 65 in module write_report) # 2: monthly_sales (line 50 in module monthly_sales)
4-9
Getting Started
You can limit the number of block activations that the debugger displays by specifying an unsigned integer. In the following example, the first trace request specifies the value 1 to show the most recent block activation. The second trace request specifies 2 to show the last two block activations.
db? trace 1 # 3: write_report (line 65 in module write_report) db? trace 2 # 3: write_report (line 65 in module write_report) # 2: monthly_sales (line 50 in module monthly_sales)
You can also display the arguments associated with each block, if there are any, by specifying the -args argument. For more information on the trace request, see Source Mode Requests, in Appendix C.
Moving from One Block to Another

When you select the env request, the debugger changes the present environment to the environment specified by an environment argument. If the specified block is in a different programming language, the debugger tells you the new language and displays source code in that language if you enter the source request. When you issue an env request in an active block, the debugger sets the current line to the line that is currently executing in the specified block. In an inactive block, the debugger sets the current line to the first line in the block of the new block environment. Note that changing environments does not affect program execution. The execution begins at the specified entry point of the program if you have not started the program. If you change environments from a breakpoint, execution starts at the next executable statement after the breakpoint. The environment argument can be one of the following:
a name specifying a procedure the key word -task with an integer argument an unsigned integer specifying the stack frame number of the block a signed integer specifying a stack frame before (negative) or after (positive) the current environment.
If the environment argument is a name, the argument specifies any procedure that is on the stack frame or that is in the current scope. The new current environment is set to the most recent activation of the block named environment. If the procedure is inactive, the debugger searches for a procedure known in the current scope. If the procedure is not found, the debugger searches for an external procedure having the same name. If the debugger finds none, it displays an error message.
4-10
Using Breakpoints
The following example specifies a name for the environment argument. In this case, the new environment is a called program named write_report.
db? env write_report db? source 3 65 add_totals. 66 read sales_by_region into region_info 67 at end move 'y' to end_flag.
If the environment argument is an unsigned integer, the argument specifies the stack frame number of an active block. To find the stack frame number of a block, enter the trace request. The following example illustrates the use of the trace request to find the stack frame number associated with an active block. The env request, in this example, brings you to line 50 of the procedure monthly_sales. Line 50 is the line of the statement that is presently executing in monthly_sales. The code address in that program is set to the start of line 51, the next executable statement.
db? trace # 3: write_report (line 65 in module write_report) # 2: monthly_sales (line 50 in module monthly_sales) db? env 2 db? source 2 50 call 'write_report'. 51 exit program. The code address is set to line 51 (the start of the statement).
Line 50 of monthly_sales calls the write_report program. For more information on the env request, see Source Mode Requests in Appendix C. If you do not know where you are in a program, you can enter the where request to display the current line, the current statement, the current block environment, and, if you are in a tasking program, the current task. In the following example, the where request shows that the current environment is the monthly_sales program, and shows the debugger mode, the path name of the source module, the source line number, the current statements line number, and the stack frame number.
db? where In monthly_sales, cobol mode (source is %s1#d01>Sales>monthly_sales.cobol). Source line 52 (statement at line 51 in module monthly_sales), stack frame #2.
Using Breakpoints
This section describes how to set breakpoints, and see the values of program variables and the contents of stack frames at those breakpoints. It also describes the commands for clearing and displaying breakpoints.
4-11
Using Breakpoints
Setting Breakpoints
You can set breakpoints before you run a program, when you hit a breakpoint in a program, or while you are stepping through a program. For more information on stepping through a program, see Stepping through a Program, later in this chapter. The following example shows the syntax of the break request.
line break label [(request_list)] [-every n]
The break request sets a breakpoint either on the current statement or on the statement that would be the current statement if line were the current line. The request list is a parenthesized sequence of debugger commands separated by semicolons. These requests are executed every time execution stops at the breakpoint. If you specify -every n, execution stops at the breakpoint only every nth time the statement is reached. There are three ways to set a breakpoint.
Issue the break request without an argument to set the breakpoint at the current line. Issue the break request and specify a line number to set the breakpoint at another line.
For example, the request break 66 sets a breakpoint at line 66.
Issue the break request and specify a label name to set the breakpoint a specific point
in the programs execution. For example, the request break add_it sets a breakpoint at line 55, the line at which the label add_it is defined. To set breakpoints before you run the program, you first determine where to set them by scrolling through the source code with the source request or by looking at a program listing. Second, you set the breakpoints with the break request. Last, you enter the start or continue request to start program execution.
Issuing Requests from Breakpoints

When the debugger stops the program at a breakpoint, you can enter any debugger request. Some of the tasks you are most likely to perform are as follows:
display the values of constants, variables, and expressions with the display request display the data type of a variable with the symbol request set the value of a variable with the set request continue program execution with the continue request set additional breakpoints with the break request execute one statement at a time with the step request perform any of the above tasks in the context of an if request.
Note that the only request you cannot use from a breakpoint is the start request.
4-12
Using Breakpoints
Displaying an Expressions Value If you enter the display request and specify an expression for its argument, the debugger shows you the value of the expression. In cobol mode, an expression can be any of the following:
a constant a variable reference a pointer-qualified variable reference one of four COBOL built-in functions: byte, addr, length, or rank a logical expression consisting of the comparison of two expressions.
For example, 100, city-code, base >= item, and amount >= 100 are valid cobol mode expressions. The permitted relational operators in cobol mode are the VOS COBOL operators <, <=, =, >=, >, ^<, ^=, and ^>. If an expression is a logical expression, it must evaluate to true or false. When the mode is cobol, the logical expression must be a comparison, using a relational operator, consisting of either two variables or a variable and a constant. If an expression is a table, you can display a range of elements in the table with the construct [low:high] in the position where a subscript value would be. The specifiers low and high are integer values indicating the low and high end of the range. Note: In cobol mode, an expression that is a variable reference must be enclosed in parentheses, as shown in the following example.
display array (expression_1:expression_2)
The following example shows the (low:high) construct used to display three elements of a table, starting with the first element and ending with the third element.
db? db? display region_info(1:3) region_info in regional_sales(1) = region_info in regional_sales(2) = region_info in regional_sales(3) = 1025.00 2185.00 9225.00
You can display all the elements in a table by specifying the name of the table. The next example illustrates how to display all the elements in region_info.
db? display region_info
You can use the asterisk (*) to specify all the subscripts in a particular dimension of a table. In the following example, the asterisk specifies all the subscripts in the first dimension of two_dimensional_array.
db? display two_dimensional_array(*,1) two_dim_array(1)(1) = 'a' two_dim_array(2)(1) = 'a' two_dim_array(3)(1) = 'a'
Displaying Declaration Information If you enter the symbol request with the variable argument, the debugger displays the specified variables data type, address, size, and the program in which the variable is declared.
Using Breakpoints
The debugger requests in Figure 4-1 show how to use the symbol request to display declaration information about a data item.
db? break 59 db? start Break in monthly_sales -- line 59 db? symbol region region at 00E031AE: 41 region pic 9. /* size(region) = 1 */ db? symbol region_info region_info in regional_sales at 00E03010: 40 2 region_info pic 9(5)v99 occurs 5. /* size(region_info) = 35 , offset = 0
1
*/
Figure 4-1. Displaying the Declaration Information of a Data Name In Figure 4-1, the break request set a breakpoint in the program monthly_sales at line 59. The start request started the program. The first symbol request shows declaration information about the data item region. In this case, the address of region is 00E031AE. The data item region has the numeric data type, and is one byte long; it was declared on line 41. The second symbol request is for the data item region_info. The phrase in regional_sales indicates that region_info is an elementary item in the group item regional_sales. The specification occurs 5 indicates that it is a table. In this case, the address of region_info is 00E03010, and the first element is located at offset 0. The data type of region_info is numeric, and it is 35 bytes long. Changing a Data Items Value If you select the set request, you can change the value of a data item or a constant value. The following example changes the value of the data item region to 3, and then changes it to 5.
db? set region = 3 db? set region = 5
Continuing Program Execution If you select the continue request, the debugger restarts execution from the line where you interrupted the program. If you select the continue request with the line argument, execution starts from the statement associated with the specified line, if possible. After program termination, the continue request does not work. The line you specify can come before or after the present line; however, it must be within the current scope. The following example shows how to continue execution from a specified line. In this case, line 44 is specified.
db? continue 44
4-14
Using Breakpoints
If the line is in a containing program, the continue request unwinds the stack, having the same effect as a nonlocal goto statement. Setting Another Breakpoint If you select the break request with the line argument, execution stops at the specified line. In the following example, a breakpoint is set for line 59.
db? break 59 -every 3
Execution stops every third time execution reaches that statement. Using Conditional Requests at Breakpoints To issue debugger requests conditionally, you can specify an if-then request and specify the request or requests to be executed as part of the if-then request. Conditional requests are often used with break statements. The following example shows the syntax of an if-then request.
if (expression) then (request_list_1)
The following example shows the syntax of an if-then-else request.

break line (if (expression) then (request_list_1) else (request_list_2))
Both request_list_1 and request_list_2 are enclosed in parentheses, as is the entire if-then-else statement. A request_list consists of one or more debugger requests, separated by semicolons. In the following example, if the variable region is greater than 1, the value of end_flag is set to y, the value of region_info(1) is displayed, and program execution resumes from the breakpoint. If, however, region is not greater than 1, the debugger does not change the value of end_flag and processing resumes.
db? if region > 1 then (set end_flag = 'y'; display region_info(1); continue) else (continue)
To enter a request at a breakpoint before executing a program, you enclose the request or requests in parentheses, as shown in the following example.
break 58 (if region > 1 then (set end_flag = 'y'; display region_info(1)) else (continue))
Note that if the break occurs in a loop, the debugger executes the requests that you specified for each iteration of the loop. If you do not include the continue requests in request_list_1 and request_list_2, the debugger interrupts your program at the specified line each time it goes through the loop.
4-15
Using Breakpoints
The debugger requests in Figure 4-2 show how to issue an if-then-else request at a breakpoint.
1. db? source 6 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). db? break 59 (if region = 3 then (display trans_amount; continue) else (continue)) db? start trans_amount in sales_record = 7000.00 trans_amount in sales_record = 1500.00 trans_amount in sales_record = 725.00 Entering debug after program termination.
2
2. 3. 4.
5.
Figure 4-2. Using Conditional Requests In the following explanation, the numbers correspond to the numbers in Figure 4-2. 1. The source request displays source code and allows you to see where breakpoints should be set. 2. This break request sets a breakpoint and specifies an if-then-else request. The breakpoint is set within the loop that reads the record. The if-then-else request checks the value of region. If the value of region equals 3, one of the values in the record is displayed. (Note that the request is executed each time the condition is met.) If region does not equal 3, the debugger continues to execute the program without stopping at the breakpoint. 3. The start request starts the execution of the program. 4. The display request in the if-then-else request is executed because region equals 3. Thus, the information is displayed in the following message.
trans_amount in sales_record = trans_amount in sales_record = trans_amount in sales_record = 7000.00 1500.00 725.00
5. The message Entering debug after program termination. lets you know that the debugger has executed the rest of the program.
Clearing Breakpoints
There are three ways to clear breakpoints. All three ways use the clear request. If you are at a breakpoint and enter the clear request, the debugger clears that breakpoint. In the following example, a breakpoint is set on line 56. If this breakpoint is not cleared, the debugger interrupts program execution at line 56 every time the repeat loop is executed. However, after the third iteration of the loop, the breakpoint is cleared with a clear request
4-16
Stepping through a Program
and a continue request is issued so that program execution can progress without interruption.
db? start Break in monthly_sales -- line 56 db? continue Break in monthly_sales -- line 56 db? continue Break in monthly_sales -- line 56 db? clear db? continue
To clear a breakpoint before program execution starts or to clear a breakpoint from another point in the program, you issue a clear request and specify the breakpoints line number. In the following example, two breakpoints are set, one on line 45 and one on line 59. When the debugger interrupts the program at line 45, the clear request is issued to clear the second breakpoint at line 59.
db? break 45 db? break 59 db? start Break in monthly_sales -- line 45 db? clear 59 db? continue
To clear all the breakpoints that have been set during a debugging session, enter the clear request and specify the -all argument.
Listing Breakpoints
The list request shows you all the breakpoints and any debugger requests executed in request_list_1 or request_list_2. It also shows how many times the debugger has encountered the breakpoints during the session. For example, the following list request shows information about three breakpoints.
db? list Break at monthly_sales line 56 (00E00120), 16 hits Break at monthly_sales line 47 (00E000AE), 1 hits Break at monthly_sales line 48 (00E000CA), 1 hits Break at write_report line 66 (00E02BA8), 6 hits (if region = 3 then (display region_total; continue) else (continue))

When you are debugging a program, it is often useful to execute one statement at a time and perform some checks before proceeding. The step request allows you to execute one or more statements at a time. At each step, you can perform any tasks you can perform at a breakpoint. The syntax of the step request is:
-in step[number] -no_in
4-17
If you do not supply the number argument, the step request steps through your program one statement at a time. If you supply a number, the debugger executes that number of statements, starting at the statement following the last statement executed. Note that the stepping mechanism can be slow. To step through only a part of a program, set a breakpoint on the statement where you want to start stepping, enter the start request, and then start stepping at the breakpoint. The example in Figure 4-3 shows you how to step through a program.
db? source 8 44 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. db? source 7 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. 1. 2. 3. 4. db? break 49 db? start Break in monthly_sales -- line db? step Step complete at monthly_sales db? step Step complete at monthly_sales db? step . . . Step complete at monthly_sales db? step Step complete at monthly_sales db? step Step complete at monthly_sales
3
49 line 64. line 65.
line 66. line 70. line 49.
5.
Figure 4-3. Stepping through a Program In the following explanation, the numbers correspond to the numbers in Figure 4-3. 1. The break request sets a breakpoint on line 49 in the main procedure. 2. The start request begins execution and signals a break at line 49, which transfers control to the procedure summary_and_cleanup. 3. The first step request begins executing the procedure, which contains a perform loop.
4. The second step continues stepping through the procedure. 5. The last step completes the procedure and returns control to line 49. Procedure calls are treated as single statements by the debugger unless you supply the -in argument with the step request at the statement that calls the procedure. If you select the -in argument, the debugger steps into all procedure blocks. The -in argument acts as a switch so that all subsequent step requests, with or without the -in argument specified, cause the debugger to step into any called procedures encountered. The example in Figure 4-4 shows how to step into a procedure.
db? source 8 44 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. db? break 50 db? start Break in monthly_sales -- line 50 db? step -in Step complete at write_report line 53. db? step Step complete at write_report line 54.
4
1. 2. 3. 4.
Figure 4-4. Stepping Into a Procedure In the following explanation, the numbers correspond to the numbers in Figure 4-4. 1. The break request sets a breakpoint on line 50 in the main procedure. 2. The start request begins execution and signals a break at line 50, which calls the procedure write_report. 3. The step -in request steps into the procedure block. The terminal response notes that the step completes at write_report, not at monthly_sales. 4. The next step continues stepping through the procedure. To prevent the debugger from stepping into other called procedures, you specify the -no_in argument with the step request before you step into another procedure. The -no_in argument acts as a switch that turns off a previously specified -in argument. Consequently,
4-19
the debugger treats subsequent procedure calls as single statements. The example in Figure 4-5 shows how not to step into a procedure.
db? source 8 44 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. db? break 50 db? start Break in monthly_sales -- line 50 db? step -no_in Step complete at monthly_sales line 51. db? step Entering debug after program termination.
5
1. 2. 3. 4.
Figure 4-5. Stepping Past a Procedure In the following explanation, the numbers correspond to the numbers in Figure 4-5. 1. The break request sets a breakpoint on line 50 in the main procedure. 2. The start request begins execution and signals a break at line 50, which calls the procedure write_report. 3. The step -no_in request steps past the procedure block. The terminal response notes that the step completes at the next line of monthly_sales. The write_report procedure does execute, but the debugger does not step into it. 4. The next step executes the last statement in the program. It also possible to specify the -no_in argument with the step request as soon as you step into a procedure block to avoid stepping through procedures unintentionally. The following list explains how to step into procedure blocks without stepping through lengthy called programs. 1. Set a breakpoint at the procedure call. 2. Start the program. 3. Use the step request with the -in argument when the debugger stops the program at the breakpoint. 4. Use the step request with the -no_in argument immediately after you enter the procedure block. 5. Use the step or continue requests from this point on.
4-20
Using Additional Debugger Requests

This section describes additional functionality that the debugger provides. It explains and gives examples of the following:
calling a procedure displaying the arguments of a procedure checking that the source module corresponds to the program checking the status of a task examining a programs assembly code.
Calling a Procedure
To call a procedure, you specify the call request and specify the procedure argument. You can specify the step request or set a breakpoint to get to the block that contains the procedure declaration or external procedure declaration. If the procedure takes arguments, you must pass these arguments to it. If there is more than one argument, separate them with commas. If you are calling a procedure with a parameter that is passed by content, you can pass any of the following arguments to the procedure: an actual value, a variable that has an assigned value, or an expression that evaluates to a value. For example, the following call request passes the values 5664 and 399,998 to the procedure named adder.
db? call 'adder' using 5664, 399998
If you are calling a procedure with a parameter that is passed by reference, you pass a variable declared within the block that contains the procedure call or a variable that is known in the current scope. For example, the following call request passes the variables anum and bnum to the procedure named level2, which returns the variable anumber.
db? call 'level2' using anum, bnum giving anumber
Displaying Arguments
To display the values of the arguments associated with a procedure, you specify the args debugger request within the block of the particular procedure. There are two ways to stop program execution in a particular procedure block. The first way is to step into the block by specifying the -in argument with the step request. The second way is to set a breakpoint in the block with the break request. After stopping execution in the specified block, you can issue the args request to display the values of the blocks arguments. The example in Figure 4-6 illustrates the use of the args request to display the arguments of the procedure level1 and the called procedure level2. In this example, a breakpoint is set in the called procedure.
4-21
Note: This example is not from the sample programs, monthly_sales and write_report, which do not pass arguments, but store data in common files.
db? source 8 8 procedure division. 9 display before: 10 display anumber. 11 call level2 using anum, bnum 12 giving anumber. 13 display after: 14 display anumber. 15 db? env level2 db? source 6 9 procedure division using anum, bnum 10 giving anumber. 11 multiply anum by bnum giving anumber. 12 exit program 13 end program level2. 14 db? break 11 db? start Break in level2 -- line 11 db? args Arguments for level2(anum,bnum). anum = 10 bnum = 20
6
1. 2. 3.
Figure 4-6. Displaying the Arguments Associated with a Procedure In the following explanation, the numbers correspond to the numbers in Figure 4-6. 1. The break request sets a breakpoint in the procedure level2. 2. The start request starts the program. 3. The args request displays the arguments anum and bnum associated with the procedure level2. For further information about passing arguments, see Passing Data, in Chapter 6.
Checking That the Source Module Corresponds to the Program

Two situations cause a source module to differ from a program module. The first situation occurs when you have edited the source module but have not compiled and bound it: the debugger shows the latest revision of the source code but executes the last version that was compiled and bound. To determine whether the source module matches the program module, enter the source request. If the source module and program module do not match, the debugger issues a message that explains when the source module was last modified and when the program
4-22
module was last compiled. The following example shows a message displayed by the debugger for a source module that does not match the program module.
db? source Date-time modified for %s1#d01>Sales>monthly_sales.cobol was 89-06-01 11:24:38 EDT when compiled, but is now 89-06-06 09:57:15 EDT. 40 procedure division.
The second situation that causes a source module to differ from a program module occurs when, after compiling the source module and binding, you move it to a different directory. The debugger cannot access it because the symbol table directs the debugger to the directory in which the source module was compiled. If there is another source module with the same path name as specified in the symbol table, the debugger uses it. If there is not, the source request issues the following error message: Object not found. If this occurs, use the source_path request without an argument to determine the path name of the source module.
db? source_path File # Lines Path 0 70 %s1#d01>Sales>monthly_sales.cobol
To give the debugger the information it needs to find the source module that corresponds to the executing program module, you use the source_path request and include the path_name argument. The path_name argument specifies the name of the file or directory where the source module is located. If path_name is a file name, the debugger searches for the source module in the current directory. If path_name is a directory name, the debugger searches for the original file name in the specified directory.
Checking a Tasks Status

If you are debugging a tasking program, specifying the task_status request without an argument displays the task ID, terminal port, and state of the current task. The current task is the task currently being debugged. If you specify the argument task_id, the debugger displays the task status of the specified task. The task_id argument is an integer. To see the status of all the tasks, you specify the -all argument with the task_status request. To see the tasks stack base, stack length, static address, and static length, you specify the -long argument.
4-23
The following example uses the task_status request to show information about the task identified by task ID 1.
db? task_status 1 Task id: Terminal Port: State: db? task_status -long Task id: Terminal Port: State: Stack Base: Stack Length: Static Address: Static Length: 1 5 Running 1 5 Running 00FD7000x 32768 00E04000x 2180
If you select the env request with the -task argument and a tasks ID number, the debugger sets the current line to the block environment associated with the top stack frame of the specified task. You can then enter the source request to see the new tasks source code. Note that the specified task must be active. The following example sets the current line to the block environment associated with the top stack frame of the task identified by number 4.
db? env -task 4
Examining a Programs Assembly Code

This chapter explains source mode debugging. If you do not compile a source module with the -table or -production_table arguments, you can still use the debugger in object mode, sometimes called machine mode. In this mode, you refer to data values and stack frames by address instead of by name. This section explains how to look at the assembly code and the addresses of variables without changing to object mode. In particular, this section describes the following:
examining a line of assembly code examining the contents of registers displaying a variables address and hexadecimal representation.
For more information on object mode debugging, refer to Machine Mode Request, in the Explanation of the debug command, in VOS Commands Reference Manual (R098). Examining a Lines Assembly Code To see the assembly code translation of a specified source code line, you use the disassemble request and, optionally, a line argument. If you leave out the line argument, disassemble shows you the assembly code for the current line. The example in Figure 4-7
4-24
shows the assembly code for the move operation on line 67 of the sample program monthly_sales.
db? position 67 db? source 67 move region to region_out db? break 67 db? start Break in monthly_sales -- line 67 db? disassemble /* Line 67
7
1. 00E00300 00E00304
2. 1B6D 81AE 81B0
3. move.b
4. -32338(a5),-32336(a5)
5.
Figure 4-7. Displaying the Assembly Code Translation of a Line In the following explanation, the numbers correspond to the numbers in Figure 4-7. 1. The first column shows the hexadecimal representation of the instructions address. 2. The second column is the object code for line 67. Since the Stratus processor has a varying-length instruction set, some instructions are one word long and some are two words long. 3. The third column shows the mnemonic for the assembly language instruction. 4. The fourth column shows the operands. In the first line:
-32338 is an offset to the address contained in a5. This offset address is where
the data to be moved is stored.
-32336 is an offset to the address contained in a5. This offset address contains
the longword to be moved. 5. The fifth column contains comments, if any. Examining Registers To see the contents of the eight data registers and the eight address registers at any time during your debugging session, you use the regs debugger request. In addition to the contents of registers, the regs request provides machine condition information, which is explained in Figure 4-8.
4-25
In the example in Figure 4-8, note that the column containing the data registers is labeled by the letter D, and the column containing the address registers is headed by the letter A.
db? regs MC data at 00FD6E88, time 1DB3443A D 00000000 004D0000 000002DE 0000FFD4 00000100 00000020 00000002 00000031 A 00E03046 00E04000 00FD6F12 00E03038 00FD6F20 00E0B000 00FD6F38 00FD6EF0
0 1 2 3 4 5 6 7 1. 2. 3. 4. 5. 6.
Flags: fault usp: 00FD6EF0 Standard 68010 Exception Stack Frame: fault no: 35 (trap 3 instruction) status: 0019 (ccr=XNC, mask=0) pc: 00E00300 (line 67 in module monthly_sales)
8
Figure 4-8. Displaying the Contents of Registers In the following explanation, the numbers correspond to the numbers in Figure 4-8. 1. Flags: indicates whether a fault or an interrupt occurred. In this case, a fault occurred. 2. usp: shows the hexadecimal representation of the contents of the user stack pointer. In this case, it contains the address 00FD6EF0. 3. This line shows the type of processor being used and the type of exception stack frame associated with the processor. Exception handling is machine-specific; thus, each processor has a different type of exception stack frame. In this case, the processor is an MC68010, and the exception stack frame is the standard one for that processor. 4. fault no: shows the number of the fault and the trap instruction that caused the fault. In this case, the operating system executed a trap 3 instruction. A trap 3 instruction causes the debugger to stop at a breakpoint. 5. status: shows the hexadecimal representation of the status register, the condition code in the condition code register (ccr), and the interrupt priority mask number. The condition codes can be any one of the following: X for extend, N for negative, Z for zero, V for overflow, and C for carry. In this case, the condition code is XNC (extend, no carry). 6. pc: shows the hexadecimal representation of the contents of the program counter at the time of the fault. In this case, the program counter contains the address 00E00300. Displaying a Variables Address and Contents To see the address and hexadecimal representation of a variable or constant, you use the dump request with a variable argument and, optionally, a number argument. The variable
4-26
Using Shortcuts in the Debugger
argument specifies the name of a constant or a variable. The number argument specifies an integer that indicates the number of bytes to be displayed. If you do not specify the number argument, a minimum of 16 bytes of data are dumped, and the debugger attempts to determine how much data to dump based on the type of variable. The example in Figure 4-9 shows the dump display of the integer variable rep_number.
db? source 58 not at end divide rep_number by 10000 giving region. db? break 58 db? start Break in monthly_sales -- line 58 db? dump rep_number
9
1. 00E051B0
2. 0
3. 31303130
4. 31416262 6F74742C 2057696C
5. 10101Abbott, Wil
Figure 4-9. Displaying a Dump of a Variable In the following explanation, the numbers correspond to the numbers in the Figure 4-9. 1. The first column shows the hexadecimal representation of the variables base address. 2. The second column shows the offset from the address. Knowing the offset is useful for determining the real address of one element of a table or structure. 3. The third column shows the contents of the first longword of memory, starting from the base address. 4. The fourth column shows the contents of the second, third, and fourth longwords, respectively. 5. The fifth column shows the graphic representation of the bytes contained in each longword. If a byte cannot be represented as a graphic character, the debugger displays a period (.). Note: If the variable or constant does not take up four longwords, the unused longwords may contain data from another program. In this case, the extraneous data has no effect on the debugger. In Figure 4-9, the second, third, and fourth longwords contain extraneous data.

The following sections explain how to abbreviate debugger requests and use VOS internal commands from within the debugger.
4-27
Abbreviating Requests
The debugger replaces first abbreviation directives in your debugger requests if you have compiled an abbreviations file with the use_abbreviations command. For example, if you write the following abbreviation in an abbreviations file and compile it with use_abbreviations, you can use the abbreviation t in place of the trace request.
first t by trace
However, the debugger does not replace subsequent abbreviations. Thus, you can use abbreviations only to abbreviate the names of the debugger requests.
Using VOS Commands

While your process is in the debugger, you can issue internal commands as if you were at command level. To issue an internal command from debugger request level, type the name of the command preceded by two periods. The following example shows how to enter the internal command help with the -type argument to list all VOS internal commands.
db? ..help -type internal
You can use abbreviations for internal commands if you specify the abbreviation in your abbreviations file. For example, you can abbreviate the command ..list to ..l.
4-28
Chapter 5: The VOS COBOL I/O System

This chapter explains the relationship between the I/O system and VOS COBOL-defined I/O facilities. The VOS I/O System is the hardware and software that moves data between a processing modules central processors or primary storage, on one hand, and the modules peripheral I/O devices or secondary storage, or the network, on the other hand. The I/O system software is constructed so that, from the users viewpoint, reading and writing to a disk file appear to be the same operations as reading and writing to an I/O device. VOS COBOL also defines a method of defining files and their attributes, opening files, and reading and writing data. There are many similarities between the VOS I/O system and the VOS COBOL I/O rules, and you can use either, but you must be aware of certain differences when writing VOS COBOL programs.
5-
I/O System Objects

The I/O system manages several kinds of data structures and I/O devices. The term object refers to any structure or device that can be named and accessed in the I/O system. Some important kinds of objects are files, file indexes, I/O devices (such as terminals, printers, and tape drives), and I/O ports.
Files
The file is the fundamental I/O system object. It is the logical unit of storage on a disk pack. A file is a sequence of records and a record is an array of bytes. The maximum number of bytes permitted in any record is 32,767. Every file, being an object, has a name. Records do not have names and are not classified as objects in the I/O system. You cannot directly refer to a record from command level (the system state in which you issue commands). Instead, records are accessed from within VOS COBOL (and other programming language) programs through service subroutines.
5-1
I/O System Objects
The VOS I/O system defines a files organization as how the files records are stored on disk. There are four types of file organization.
Sequential Stream Fixed Relative
The length of a sequential or stream file record determines the length of the disk region in which the record is stored. The records of a fixed or relative file, however, are stored in disk regions that are all the same length. This length is set when the file is created. A file of any organization except stream can be associated with one or more indexes. An index is an ordered list of the locations of file records sorted on an associated key. The associated key is normally a subfield in a fixed location within each record of the file. To access a file means to read, write, rewrite, delete, or position the file. How a record is specified in an access request is called the access mode of the request. There are three types of access mode.
Sequential Random Indexed

Note: Do not confuse the terms organization and access mode as defined by the I/O System with the identical terms used in a VOS COBOL source program. The relationship between I/O terminology and VOS COBOL terminology is explained in VOS COBOL I/O Summary, later in this chapter. Sequential File Organization A sequential file is organized so that records can be accessed in the physical sequence in which they are stored. This restricted type of access means the file can be stored on the disk with no unused space. Records consist of a variable number of data bytes with a two-byte record count at the beginning and end of each record. (The record count enables you to search forwards and backwards in a file to locate a record.) A record in the file begins where the immediately preceding record ends (see Figure 5-1), so that the location of a record, relative to the beginning of the file, depends on the lengths of all the preceding records. For this reason, you cannot randomly access records in a sequential file. Files manipulated by a text editor are usually organized sequentially.
5-2
I/O System Objects

1
eb
eb
eb
cc t t
cc t t
cc t t
= data b = beginning of record e = end of record ct = count PD0034
Figure 5-1. Sequential File Organization Stream File Organization A stream file is also organized so that records can be accessed in the physical sequence in which they are stored. This restricted type of access means the file can be stored on the disk with no unused space. Records consist of a variable number of data bytes delimited by the ASCII line-feed or carriage-return character. This means that a record cannot contain the ASCII line-feed or carriage-return character. A record in the file begins where the immediately preceding record ends (see Figure 5-2), so that the location of a record, relative to the beginning of the file, depends on the lengths of all the preceding records. For this reason, you cannot randomly access records in a stream file.
2
Stream File Organization

e b e b e b e b
l f
l f
l f
l f
= data b = beginning of record e = end of record lf = line-feed character
Figure 5-2. Stream File Organization
5-3
I/O System Objects
Fixed File Organization Fixed file organization is designed to permit the fastest average access to any record and, at the same time, to use disk space most efficiently. A fixed file has fixed-length records that cannot be deleted. The records are stored in fixed-length disk regions, as shown in Figure 5-3. The fixed length of file records is called the record size of the file. No control information is stored with the records. In random access mode, the record to be accessed is specified by its number. This number identifies its position in the record sequence. The disk location of a record can be quickly computed from its record number. Some system files, such as program modules (.pm files), have this organization.
3
e b
eb
e b
eb
eb
= data b = beginning of record e = end of record
Figure 5-3. Fixed File Organization Relative File Organization Relative file organization is similar to both sequential file and fixed file organizations. In a relative file, the records can have various lengths, like those in a sequential file, but the records are stored on the disk in fixed-length regions, like those in a fixed file, as shown in Figure 5-4. The fixed length is called the maximum record size of the relative file. The actual length of each record is stored on the disk with the record. It is possible to delete a record in a relative file simply by marking it as deleted.
5-4
I/O System Objects
Relative
4
e b r l
e b r l
e b r l
e b r l
e b r l
= data b = beginning of record e = end of record rl = record length
Figure 5-4. Relative File Organization
Access Modes
VOS I/O conventions and VOS COBOL I/O conventions both define access modes. Unlike open mode and I/O type, however, these are not exactly equivalent. The VOS COBOL access mode is a fixed property of the file similar to organization. It determines what operations are allowed on a file and also affects the result of some operations. VOS COBOL defines three access modes: sequential, random, and dynamic (both sequential and random). I/O access mode also controls allowable operations, but it is specified when the file is opened. The VOS I/O conventions also define three access modes: sequential, random, and indexed. A file may be closed and then reopened in a different access mode. A file of any type may be opened in any access mode, with two restrictions.
Sequential files may not be opened in random access mode. To be opened in indexed access mode, a file must have at least one associated index.
When VOS COBOL run-time support routines call the s$open subroutine to open a file, an I/O access mode is selected based on both the VOS COBOL organization and the access mode of the file, as shown in Table 5-1.
5-5
I/O System Objects

1
Table 5-1. Run-Time Access Modes VOS COBOL Organization/Access Mode Sequential/sequential Relative/sequential Relative/random Relative/dynamic Indexed/sequential Indexed/random Indexed/dynamic Sequential Sequential Random Random Indexed Indexed Indexed I/O Access Mode
File Indexes
Files of any organization except stream can be indexed. To index a file, you associate a key with each of the records of the file. A key is a constant value that identifies a record, similar in some respects to a name of the record. An index is an ordered list of the relative disk locations of records sorted on the associated keys. A file can have many indexes. A records key is stored in the index along with the records disk location. In indexed access mode, you specify a record by giving its key. Using the key, the I/O system looks up the location of the record in the index. There are three types of indexes: embedded-key indexes, separate-key indexes, and item indexes. VOS COBOL indexed files use embedded-key indexes exclusively. The corresponding keys are defined as fields in the files record description. VOS I/O additionally allows keys to be made up of noncontiguous components. In this case, the key value is defined in terms of noncontiguous subfields within the record. These subfields are concatenated to form the value of the full key. However, although VOS COBOL I/O can access a file containing noncontiguous keys, there is no way to define such keys within a VOS COBOL source program. This means that the file must be created before the program is executed and then opened in either I/O or extend mode.
File Errors
You can specify procedural code to be executed, should an error occur during the execution of an I/O statement. There are two ways to do this: define one or more use procedures in the declaratives portion of the program, or specify a sequence of imperative statements following a specific I/O statement for at end and invalid key errors. When use procedures are specified, the program must be divided into sections. Each section in the declaratives portion of the program is referred to as a use procedure and can be associated with one or more specific files, or with file opening modes. If an error occurs during the execution of an I/O statement, control transfers to the applicable section and that code executes as though it were the subject of a perform statement.
5-6
I/O System Objects
If more than one use procedure applies to a file, the more specific procedure executes, not both procedures. For example, suppose file F is opened in input mode, and a use procedure exists for file F and another use procedure exists for input mode. In this case, the use procedure for file F executes. For specific statements that can result in an end-of-file condition or an invalid-key condition (read, write, delete, etc.), there are two means of handling file errors.
A specific group of imperative statements can be associated with the I/O statement by
appearing after the key words at end or invalid key. Should such a condition occur during the execution of that particular statement, those statements are executed in place of any applicable use procedure. If a use procedure is available, then the use of these phrases is optional, because an end-of-file condition or invalid-key condition causes execution of the applicable use procedure. If a use procedure is not available, then the use of one of these phrases is often mandatory, depending on the particular statement.
If an error occurs for which the at end or invalid key phrase is not applicable and
no use procedure exists (for example, an attempt to open an input file that does not exist), then program execution stops and the error condition is signaled. At this point, a number of options are available to the user. For more information, see Error Handling, later in this chapter. Any file can have an associated file status field and/or an error code field that is set to a status code following each I/O statement or locking operation involving that file. Make this association in the file control entry as follows:
select file_name assign to port_name organization is . . . file status is data_name_1 error code is data_name_2. . . . 77 data_name_1 pic xx. 77 data_name_2 usage is comp-4.
Normally the value 00 in the file status field indicates successful completion of the operation. For a complete list of values that are defined for each file organization, refer to VOS COBOL Language Manual (R010). A one-word binary integer data item associated with error code holds a system-defined error code. Unlike the file status field, this is a VOS COBOL extension that provides a more precise explanation of the cause of the error. The value of error code can be passed to the subroutine s$error, which interprets and returns the type of error encountered in descriptive phrases. Normally the value 0 in the error code data item indicates successful completion of the operation.
5-7
I/O System Objects
Refer to File Organization, later in this chapter, for a discussion of the file status and error code values relating to file indexes.
Error Handling
Various errors may occur during the execution of a program. Some of the errors are related to the processing of a file.
Should a file error occur, the program can use the at end or invalid key phrase
with various I/O statements, as well as more general use procedures, in order to take specific action.
Should an invalid arithmetic operation or data conversion occur, the on size error
phrase can be used with arithmetic statements. A use procedure can be defined in the program to be executed when a general type of error condition occurs. When errors occur and no program-defined action is specified for them, the operating system reports the error on default_output. The process goes to break level and you can choose from the following requests.
stop continue debug keep login re-enter
For more information on break level requests, see Table 4-2.
I/O Ports
Within the I/O system, every disk file has a unique name by which the I/O system identifies it. The operating system limits such names to 256 characters in length. For convenience and organization, users usually catalog related disk files into directories. Within a containing directory, file names must be unique. File names are limited to 32 characters in length. Directories are hierarchical structures; directories contain the names and attributes of subordinate directories as well as file names. When you log into a system, your current directory is both your home directory and the top directory in your processs directory hierarchy. I/O devices also have path names. The system administrator determines device names in the system. The name of each device must be different from the name of every other device and the master disk directory in the system. A file name defined within a VOS COBOL program is not necessarily related to the name used by the I/O system to identify the object of I/O traffic. The connection between a VOS
5-8
File and Record Locking
COBOL file and the actual source or destination is made through an I/O port, the name of which can be specified in the select clause. An I/O port is an object that represents an I/O source or destination. You create and name an I/O port, and associate it with an actual source or destination, such as a file or an I/O device. When you need to refer to the file or device for reading or writing data, you refer to the port by its name. Thus, the actual source or destination of I/O traffic does not have to be specified when a program is written. A single program can process many different files or read and write data on many different devices without having to be recompiled. You simply change the file or device associated with the port named in the program before (or even during) the execution of the program. A port is created during a process and, unlike other I/O system objects, exists only for the lifetime of the process. Associating a port with a file or I/O device is called attaching the port; you attach a port with the attach_port command. The reverse operation is called detaching the port; the command is detach_port. A port that is explicitly attached remains attached until you explicitly detach it or until your process terminates (unless you specify that it be held attached). This allows a sequence of programs to be executed with a common set of port attachments. Most of the time, it is unnecessary to use the attach_port and detach_port commands because a port is automatically created and attached when a program opens a file that is not connected to a port. A port attached in this manner is detached when the program closes the file or when the process creating the attachment returns to command level. If an open statement executes in a VOS COBOL program and the associated port is not attached, it is automatically attached at that time. In this case, the port is also detached on the next close statement for that file or when the program returns control to command level with either: (1) a stop statement, (2) an exit program statement in some program invoked at command level, or (3) an error condition.

VOS COBOL provides a number of file locking and record locking options. File locking allows a process to lock a file for reading or writing, and prevent other processes from reading or writing the file until the calling process releases its lock. The file is locked when you specify the set lock statement. The lock on the file is released when one of the following circumstance occurs.
The lock is released by the release lock statement with the file phrase. The locked file is closed.
Record locking allows a process to lock a single record in a file; other processes have access to other records in that file, but cannot read or write that record until the calling process releases its lock. In addition, you can specify that the record be unlocked as soon as the operation is performed. Note: In order to use record locking, you must have specified the with lock or with lock mode 5 phrase with the open statement.
5-9
The lock on the record is released when one of the following circumstances occurs.
The reset option of the with record lock phrase is specified in the open
statement.
The record is rewritten with the rewrite reset statement. The file containing the locked record is unlocked by including the release lock
phrase with the I/O statement.
The file containing the locked record is closed by the process holding the lock. The reset phrase of the I/O statement specifies release of the lock upon completion
of the operation. In addition, the operating system provides a special input mode in which records can be read, even if a file is being concurrently updated by another process. The following example shows how the with lock off phrase of the open statement can be used to indicate that this type of input mode is desired.
open input file_name with lock off
Read operations in such a mode are referred to as dirty reads, because the record being read can be changed after it is read. The record read is always in an internally consistent state. Processing a file in this way is problematic only if the file contains records that contain interdependent information. When a file is open with the with lock off phrase, no locking mode, as described below, is applicable. Also, the with lock off phrase should only be used with an open statement that opens a file in input mode. Note: Locking attributes must be specified for each file in the open statement, as the following example shows.
open input file1 with lock off file2 with lock off.
Refer to VOS COBOL Language Manual (R010) for the complete syntax of the open statement. The operating system allows for various file and record locking modes that take effect when a file is opened. Such locking modes are specified by the with record lock or with lock mode phrase of the open statement, as follows.
open mode file_name with record lock open mode file_name with lock mode expression
As shown in the second example above, lock mode can be an expression. At the time the open statement is executed, the expression must yield an integer value corresponding to one of the lock mode values in Table 5-2.
5-10

2
Table 5-2. Lock Mode Values Value 1 Lock Mode set lock dont wait Description Tries once to lock the file according to the I/O type (default). Waits to lock the file until it becomes available. Does not lock the file; you must lock it with the set lock statement if desired. Locks and unlocks the file each time an I/O operation is performed. Enables you to lock individual records as you update them (same as opening the file with the with record lock phrase).
2 3
wait for lock dont set lock
implicit locking
record locking
Refer to Locking Modes in the description of the s$open subroutine, in VOS COBOL Subroutines Manual (R019), for additional information. In addition, VOS COBOL enhances several of the standard COBOL I/O statements so that they include one or more of the features that follow:
The reset lock phrase enables any I/O statement that accesses a record to optionally
unlock that record when the operation is completed.
The reset option of the record lock phrase can be specified in the open statement
so that all I/O operations that access that file unlock records when the operation is completed. Conversely, several I/O statements can override this with the with lock phrase.
The time limit phrase specifies the maximum time that the process should wait to
obtain a record. Refer to the discussion of the appropriate I/O statements in VOS COBOL Language Manual (R010) for more information. In most cases, the specified lock mode applies until the file is closed. However, VOS COBOL supports special locking options for files that are stored on disk devices. Further information on locking is given in VOS COBOL Programmers Guide (R077), and also in the description of the s$open subroutine in VOS COBOL Subroutines Manual (R019).
5-11
I/O Type
I/O Type
When a file is opened, the I/O system requires an I/O type to be specified that describes the type of operations to be allowed on the file during this opening. I/O type is not a fixed file characteristic like organization. Therefore, it can be changed any time the file is opened. The I/O types are input, output, append, and update.
Input I/O type allows records of an existing file to be positioned to and read. Output I/O type indicates that a new file is to be created and records are to be written. Append I/O type indicates that records are to be added to the end of an existing file. Update I/O type allows record positioning and reading, as well as any type of updating
operation: writing, deleting, or rewriting.
VOS COBOL I/O Summary

The terms organization and access mode have a distinct meaning in the ANSI COBOL Language standards. The organization of a file is a fixed property of that file and can be either sequential, relative, or indexed. The access mode of a file is a fixed property in the sense that it cannot be modified during program execution. However, different programs may be written that describe the same file with different access modes. The open mode of a file is not a fixed property of the file in any sense. The same file may be opened in one mode, closed, and then opened in another mode during the execution of the program. This mode is specified with the open statement and can be input, output, extend, or I/O.
Opening a File
When opening a file in a VOS COBOL program, select one of the following four VOS COBOL open modes.
Input (input) mode is used when records are to be read from the file. The only
statement allowed is read; with relative and indexed files, the start statement is also available to position the file for any subsequent read.
Output (output) mode is used to build new files. If a file exists and is opened for
output, it is overwritten; if it does not exist, it is created. The only I/O statement allowed when the file is opened in this mode is write.
Extend (extend) mode is used to sequentially add to the end of an existing file. It is
identical to output mode except that if the file in question exists, it is not overwritten. It is positioned to its logical end for subsequent output. Only write statements are allowed in this mode.
I/O (i-o) mode is used primarily to update a disk file. In COBOL-74 programs, I/O
mode creates the file if it does not exist. In I/O mode, all I/O statements are allowed: read, write, rewrite, start, and delete. There are certain restrictions and
5-12 Chapter 5: The VOS COBOL I/O System
File Organization
implications, however, based on organization and access mode. Refer to I/O Incompatibilities, in Appendix B, for more information about the different handling of I/O mode in COBOL-74 and COBOL-85. The system subroutine s$open, invoked by VOS COBOL run-time support routines, requires that you supply a VOS I/O type. There is direct mapping of VOS COBOL open mode to VOS I/O type, as shown in Table 5-3.
3
Table 5-3. Mapping of VOS COBOL Open Mode to I/O Type VOS COBOL Open Mode
input output extend i-o
I/O Type
input output append update
Although differently named, these are functionally equivalent. Any type of file may be opened in any one of these modes, closed, and then reopened in another mode.
File Organization
As described in the previous section, VOS COBOL defines three types of file organization (sequential, relative, and indexed) and the VOS I/O system defines four types (fixed, relative, sequential, and stream) and allows one or more indexes to be applied to any of these files. The existence of such indexes does not affect the essential file type. Table 5-4 shows the types of files that are supported when a file is opened in output mode with the given VOS COBOL organization. In the table, the parenthetical notes have the following meaning: 1 2 3 4
4
indicates the default type of the file created if a file does not already exist indicates a restriction: fixed-length records only indicates a restriction: records may not be deleted indicates files with at least one associated index.
Table 5-4. Files Supported Using Output Mode (Page 1 of 2) VOS COBOL Organization Sequential COBOL-74 Implementation Sequential (1) Relative Fixed (2) Stream Relative Relative (1) Fixed (2,3) COBOL-85 Implementation Sequential (1) Relative Fixed (2) Stream Relative (1) Fixed (2,3)
5-13
File Organization
Table 5-4. Files Supported Using Output Mode (Page 2 of 2) VOS COBOL Organization Indexed COBOL-74 Implementation Sequential (1,4) Relative (4) Fixed (2,3,4) COBOL-85 Implementation Sequential (4) Relative (1,4) Fixed (2,3,4)
In the case of an indexed file, one or more file indexes are also created for the file, as defined in the VOS COBOL source program through the record key and alternate record key clauses of that files file control entry. These indexes can be ordered in ascending or descending sequence. Note that it is possible to access a file with a different organization than the one used to create it. For example, a relative file having at least one associated file index can be attached to the port of a VOS COBOL indexed file as well as a sequential file. Additionally, a relative file can be read or written as a VOS COBOL sequential file. Fixed files are the most efficient files and can be accessed from within a VOS COBOL program if certain restrictions are adhered to. They can be accessed as VOS COBOL sequential files, provided all records in the file are of the same length. They can be accessed as VOS COBOL relative files if all records are the same length and program logic does not require the deleting of records. If they have at least one associated file index, they can be accessed as VOS COBOL indexed files, assuming the same restrictions as for relative files. It is possible to perform output to files that do not match the default file type. To do this, the file of the desired organization must be created before the VOS COBOL program is executed. Then the program merely opens the file in extend or I/O mode, whichever is applicable, and performs write statements. Note that if a file is opened for output, a new file with the default organization is always created (any existing file is deleted). For programs compiled with the ansi74 or compatible language option, this is true also for files opened in extend or I/O mode that do not already exist. For programs compiled with the ansi85 or full_ansi85 language option, this is true for files opened in extend mode only; if a nonexisting file is opened in I/O mode, it is not created. In this case, the error code field is set to the system error code e$object_not_found (1032) and the file status field is set to 35. When a VOS COBOL program attempts to open a nonexistent indexed file and the file is automatically created, an index for each record key specified in the file description entry is also created. By convention, each index is named according to its position in the record area; the index associated with the record key starting at the beginning of the record is called 1, the index for a key at offset 10 is called 11, and so forth.
5-14
Integrating File System Commands with VOS COBOL
When opening an existing indexed file in input, I/O, or extend mode, the file indexes associated with it are checked against those that are defined in the source program. As long as the file has embedded indexes whose starting positions in the record area match those defined in the program, no error occurs and the file is accessed correctly. The following situations involving file indexes are not by themselves errors.
More indexes actually exist than are defined in the source. The length of the key associated with an index does not match the length defined in the
source.
The key associated with an index is multicomponent (it is not possible to specify this
in the source).
More than one key starts at the same location (in this case, the key with a length
corresponding to the key defined in the source is used, or, if no lengths match, the first key defined is used).
The key allows duplicates, but is not so described in the source program (or vice versa).
You can detect these types of mismatches by specifying an error code field associated with the file. Should such a mismatch occur, the error code field is set to the system error code e$index_mismatch (1802). The file status field is set to 00 in this case. A use procedure, if specified, does not execute. The following situations, however, are considered to be errors.
An index does not exist for the record key and all alternate record keys defined in the
source.
A key is defined in the program as ascending or descending, when it is actually the

reverse. In these cases, the error code field is set to the system error code e$index_mismatch (1802), and the file status field is set to 90 in a COBOL-74 program, or 39 in a COBOL-85 program. A use procedure, if specified, does execute.

In summary, the VOS I/O system and VOS COBOL both have requirements for files related to file organization, I/O type (open mode), access mode, locking mode, and indexes. As described in the preceding sections, these terms are related, but do not necessarily have exactly the same meaning in VOS I/O and VOS COBOL.
5-15
There are several VOS commands and subroutines that you can use to create files and define their characteristics. These are defined in Table 5-5, along with a reference to where each is documented.
5
Table 5-5. File System Commands and Subroutines VOS I/O Characteristics File organization Command/Subroutine
create_file
Where Documented VOS Commands Reference Manual (R098) VOS COBOL Subroutines Manual (R019) VOS COBOL Subroutines Manual (R019) VOS COBOL Subroutines Manual (R019) VOS COBOL Subroutines Manual (R019) VOS COBOL Subroutines Manual (R019) VOS Commands Reference Manual (R098) VOS COBOL Subroutines Manual (R019)
s$create_file
s$open
I/O type Access mode Locking mode Indexes
s$open
s$open
s$open
create_index
s$create_index
VOS COBOL uses the following COBOL statements to create files and define their characteristics. The format and use of these statements is described in VOS COBOL Language Manual (R010). VOS COBOL Characteristics File organization Open mode Access mode Locking mode Indexes Where Defined
file-control paragraph open statement file-control paragraph open statement
Data description entry

file-control paragraph
Once you have created the files, you can access them from your COBOL program, but you must use COBOL statements that are compatible to the VOS file characteristics you have specified.
5-16
Tape Handling Requirements

In general, VOS COBOL supports I/O in a device-independent manner, so that a file may or may not be directed to tape depending entirely on the attachment of its associated port. Programs containing sequential file processing statements need not be edited or recompiled to run successfully in the tape processing environment, provided no special tape-oriented statements are required in the source. The operating system supports single-reel and multi-reel files and multi-file reels and can position a tape to the beginning of a specified file either by absolute file number or relative file number. On labeled tapes, it can position to a file by reading the file label. The operating system supports sequential access to both ANSI and IBM format tape files, as well as unlabeled tape files. The operating system assumes that IBM format tapes are written in 8-bit EBCDIC character code and optionally translates records on I/O from ASCII to EBCDIC and vice versa. VOS COBOL includes an extension to standard file record formats, undefined length format (U). Undefined format defines one record per tape block, with the tape block length equal to the record length. IBM tape support allows fixed-length (F), variable-length (V), and undefined (U) record format files. Both fixed- and variable-length record format files may be blocked. Variable-length format files can be blocked or spanned. Each tape format (ANSI, EBCDIC, and unlabeled) supports slightly different file and record formats. See VOS Tape Processing Users Guide and Programmers Reference (R052). In the standard labels, users may supply the volume-id, owner-id, and file-id fields of tape labels. The operating system enters default information into all other label fields on output and ignores such fields on input. It does not make any special provision for user label writing or reading. The operating system provides the following tape I/O commands.
set_tape_defaults display_tape_defaults mount_tape dismount_tape position_tape write_tape read_tape
See VOS Commands Reference Manual (R098) for details of arguments associated with these commands. If you set defaults for a tape file before a VOS COBOL program attempts to open the file, those default characteristics override file characteristics specified in the VOS COBOL program.
5-17
On the other hand, VOS COBOL provides language constructs that specifically control these tape file I/O functions. The following sections summarize VOS COBOL-defined tape file processing constructs.
File Characteristics
Within a VOS COBOL program, the select clause of the Environment Division can specify a file assigned to tape (if the word tape occurs in the assign clause, either as the port name or the word following the port name). This assignment must be made for files named in special tape-oriented clauses elsewhere in the program, such as in the multiple file clause and the close reel statement. Otherwise, the tape oriented actions are ignored by the compiler and cause no action at run time. The i-o control paragraph of the Environment Division specifies the location of sequential files on a multiple-file tape. The multiple file clause is required when more than one file shares the same physical reel of tape. Regardless of the number of files on a single reel, only those files that are used by the object program need to be specified. If all file names in the i-o control paragraph are listed in consecutive order, the position clause need not be given. If any file in the sequence is not listed, the position relative to the beginning of the tape must be given. The labels clause specifies that label records are standard or omitted. In a COBOL-74 program, if the labels clause is not specified, no labels are assumed; in a COBOL-85 program, standard label records are assumed. If label records are specified but not present or if label records are not specified but present, an error occurs unless you explicitly override the labels clause using the set_tape_defaults command.
Mounting the Tape

Normally, if a tape is not mounted when the open statement executes, the operating system issues a request to mount the tape. However, the fact that a file defined as optional is not mounted indicates that it is not present. In this case, no mount request is made. Instead, the file is treated as an empty file and the first read statement results in an at end condition.
File Positioning at open

The open input statement causes input labels to be checked. The open output statement causes labels to be written. The open extend statement positions the current record pointer immediately following the last logical record of the file so that subsequent write statements add records to the end of the file as though it were opened with the output phrase. You cannot specify the extend phrase for a multi-reel file. If you specify the extend phrase, and the label records clause indicates that label records are present, execution of the open statement on tape files includes the following steps.
Beginning file labels are processed only in the case of a single-reel file.
5-18
Beginning volume labels on the last existing reel are processed as though the file is
being opened with the input phrase. These labels are then deleted.
Processing then proceeds as described above. File Positioning at close

The close statement, with the with lock phrase or with no optional phrase, positions single-reel files, multi-reel files and multi-file reels to their physical beginning. The statement close with lock leaves both a single-reel file and the current reel of a multi-reel file unavailable for the remainder of a run unit. The statement close reel with no rewind leaves both a single-reel file reel and the current reel of a multi-reel file in their current positions. For multi-reel files, the close reel statement with no optional phrases causes an input or output file reel-swap and performs both beginning and ending reel label processing. The next executed read or write statement for that file makes available the next data record on the new reel. Do not use this phrase for a single-reel file.
Positioning the Reel During Multi-reel File Processing

If the end of a reel is recognized during the execution of a read statement and the logical end of the file has not been reached, the following operations are executed.
The standard ending reel label procedure is executed. A reel swap occurs. The standard beginning reel label procedure is executed.
The first data record of the new reel is made available. After recognition of an end-of-reel condition for a multi-reel file, the write statement performs the following operations.
The standard ending reel label procedure is executed. A reel swap occurs. The standard beginning reel label procedure is executed.
Most calls for processing tape files are identical to those for processing sequential disk files, with the restriction that neither random nor indexed tape file access is supported. If a program defines a file as tape, it makes an additional call to s$control at open to establish or supplement the default tape characteristics using information supplied in the VOS COBOL source. Thus you may decide at execution time whether to attach the port associated with the file to a tape or to another device. If the port is not attached to a tape, then the close reel statement and the no rewind option of the close statement have no effect.
5-19
Printer Files
Printer Files
Within a VOS COBOL program, the select clause of the Environment Division can specify a file assigned to printer (by including the word printer in the assign clause, either as the port name or the word following the port name). This assignment must be made for printer files; otherwise, the printer-oriented actions are ignored by the compiler and cause no action at run time. Normally, ports are not attached directly to printer devices; rather, a printer file is output to a sequential mass storage file and then queued for printing. Thus, the fact that a file is a printer file refers to the contents of the file (line spacing information), not the actual I/O object. When a file is to be directed to a printer, then line spacing information is embedded in the file in the form of generic output sequences. These are interpreted by the spooler in a way that is consistent with the particular device it is servicing. The characteristics of this device are defined in an associated print queue. When a file containing these sequences is directed to a terminal (with the display command, for example), most of them have no effect. They are invisible except in contexts where they are meaningful. Up to 16 channels can be defined that map into particular line positions in the body of a page. These channels may be associated with user-defined mnemonic names in the special-names paragraph of the Configuration Section. For example:
special-names. channel-1 is address-position, channel-2 is channel-2.
Channels are logical entities associated with a print queue. They can be defined as required for any print queue that is to be serviced by the spooler with the create_print_queue command (see VOS Commands Reference Manual (R098)). This command allows the association of a channel with a line number on the page being printed. In a VOS COBOL program, statements such as:
write record-name after advancing address-position.
or
write record-name before advancing channel-2.
cause the specified generic output sequences to be associated with the line being written so that the spooler servicing the print queue in question advances to the line associated with that channel in the queue definition. If the linage clause is specified, the program exerts complete control over the format of the page. In this case, a mnemonic name must not be specified with the advancing phrase. Note: The linage clause and the write before/after advancing statement are allowed only if the file is a printer file.
5-20
Chapter 6: Calling Programs in Other VOS Languages

In VOS COBOL, programs can be developed in a modular fashion; units within a program can be written as separately compiled subprograms (subroutines). Although they might be compiled separately, all user-defined subroutines associated with a program must be bound with the main program. This produces a single executable program module. You can bind a VOS COBOL object module with object modules written in any of the following VOS languages.
6-
COBOL PL/I Pascal C FORTRAN BASIC
You activate a subprogram (procedure or function) by specifying the COBOL call statement. If the calling program passes arguments to the subprogram, you must specify the using phrase with the call statement. If the called subprogram is a function, you must specify the giving phrase with the call statement to receive the returned value. The call statement is described in VOS COBOL Language Manual (R010). This chapter demonstrates how a COBOL program calls subprograms from any of the six VOS languages. Two types of subprograms are discussed and illustrated. The first type illustrates a calling program that passes three arguments to the called subprogram, which modifies one of these arguments. The second type shows a calling program that passes two arguments to the subprogram and accepts a return value from the subprogram. A subprogram that returns a value is commonly called a function. The arguments and returned variables passed between subprograms in different VOS languages must have compatibly defined data types. Table 6-1 summarizes the mapping between VOS COBOL data types and data types in other VOS languages.
6-1
Calling Programs in Other VOS Languages

1
Table 6-1. Cross-Language Compatibility BASIC

name=7
C
float
COBOL
comp-1
FORTRAN
real*4
Pascal N/A
real
PL/I
float binary(24) float binary(53)
name=15
double
comp-2
real*8
N/A
N/A
comp-3, packeddecimal comp-4
N/A
N/A
N/A
name%=15
short
integer*2, logical*2 integer*4, logical*4
-32768..32767
fixed binary(15) fixed binary(31)
name%=31
long, int, enum
comp-5
integer
name# =(p,q)
N/A
comp-6, binary, pic s9(i)v9(f) display, pic x
N/A
N/A
fixed decimal(i + f, f)
name$=1
char
character* 1, logical*1 character* n string*n
char
character( 1)
name$=n
char id [n] char_varyi ng(n)
display, pic x(n) display-2, pic x(n)
array [1..bn] of char string (n)
character( n) character( n) varying entry variable label pointer
name$<=n
N/A N/A N/A
(*id )()
entry
N/A N/A N/A
N/A N/A
^ type_name
N/A
type *id
label pointer
Note: VOS PL/I fixed binary(15) does not support the value -32,768.
6-2
Calling a Subprogram
Calling a Subprogram
The following example is the COBOL calling program call_proc.cobol, which calls a subprogram called sample_proc. The subprogram sample_proc is illustrated in each of the VOS languages throughout this chapter. This program uses the call...using statement to pass three arguments to a subprogram. The subprogram modifies the value of the total argument.
identification division. program-id. call_proc. data division. 01 name 88 done 01 hours 01 rate 01 total 01 wages
picture x(12) display-2. value 'zz'. comp-4. comp-2. comp-2. picture $zz9.99.
procedure division. perform until done display 'Enter the employee last name (enter zz to end): ' accept value of name if not done display 'Enter (whole) number of hours for ' name ': ' accept value of hours display 'Enter pay rate for ' name ': ' accept value of rate call 'sample_proc' using hours rate total move total to wages display 'Wages for ' name ' are ' wages. exit program.
6-3
Calling a Function
Calling a Function
The following example is the VOS COBOL calling program call_funct.cobol, which calls a function called sample_funct. The function sample_funct is illustrated in each of the VOS languages throughout this chapter. This program uses the call statement with the using and giving phrases to pass two arguments to a function and accept a return value.
identification division. program-id. call_funct. data division. 01 name 88 done 01 hours 01 rate 01 total 01 wages
picture x(12) display-2. value 'zz'. comp-4. comp-2. comp-2. picture $zz9.99.
procedure division. perform until done display 'Enter the employee last name (enter zz to end): ' accept value of name if not done display 'Enter (whole) number of hours for ' name ': ' accept value of hours display 'Enter pay rate for ' name ': ' accept value of rate call 'sample_funct' using hours rate giving total move total to wages display 'Wages for ' name ' are ' wages. exit program.
Passing Data
COBOL, like all other VOS languages except C, passes arguments by pushing their addresses on the stack. (The method by which C passes arguments is discussed in Referencing VOS C Functions, later in this chapter.) When a COBOL program references a parameter, it actually references the storage location whose address is passed. By default, COBOL passes the address of the storage location of a variable. This method of passing arguments is known as by reference; it is the default. When the called program modifies the corresponding parameter, it modifies the contents of the storage location; therefore, the variable in the calling program is also modified. You can pass the value of a variable instead of the storage location, so that if the corresponding parameter in the called program is modified, the value of the argument in the calling program is not affected. This is known as passing parameters by content; to use this method, specify the by content phrase with that argument in the call statement. When you specify the by content phrase with an argument, the compiler makes a temporary copy of the argument and passes its address to the called program. If the called
6-4
Referencing VOS COBOL Programs
program modifies a parameter that has been passed by content, the modification will not be visible to the calling program, because the temporary storage that holds the value is released at the point of return. In VOS COBOL, you can pass expressions and constant values (literals), as well as variables. When you pass an expression or constant, you cannot specify it following the by reference phrase. Since expressions and constants are defined as values, not storage locations, it makes no sense to pass these arguments by reference. If you do not explicitly specify the by content phrase, the compiler assumes that data is passed by reference. For information about passing data by reference and by content, refer to VOS COBOL Programmers Guide (R077). For information about the relationship between arguments that are constants or expressions and the data type of the corresponding parameter, refer to the description of the call statement in VOS COBOL Language Manual (R010).
Referencing VOS COBOL Programs

You call a VOS COBOL subprogram from the VOS COBOL calling program with the call statement. The calling program defines the arguments to be passed to the subprogram and lists them in the using phrase with the call statement. The subprogram lists the parameters in the using phrase of the Procedure Division header, and defines them in the Linkage Section. This establishes the correspondence between the data items that are passed by the calling program and received by the called program.
A VOS COBOL Subprogram

The following example program sample_proc.cobol is the called program written in VOS COBOL. It lists the parameters in the using phrase of the Procedure Division header and defines them in the Linkage Section. This program is translated to the other VOS languages in the rest of this chapter.
identification division. program-id. sample_proc. data division. linkage section. 01 hours comp-4.proc. 01 rate comp-2. 01 total comp-2. procedure division using hours rate total. if hours greater than 40 then compute total equals ((hours * rate) + ((hours - 40) * 1.5 * rate)) else compute total equals hours * rate. exit program.
A VOS COBOL Function

The following example program sample_funct.cobol is the called function written in VOS COBOL. It lists the data items in the using and giving phrases of the Procedure Division header, and defines them in the Linkage Section. Note that it is not necessary to define the return variable, the object of the giving phrase, in the Linkage Section. This
Referencing VOS PL/I Programs
function is translated to VOS PL/I, VOS Pascal, VOS C, and VOS FORTRAN later in this chapter. Because VOS BASIC does not support external functions, you cannot activate a BASIC function from COBOL.
identification division. program-id. sample_funct. data division. working-storage section. 01 total comp-2. linkage section. 01 hours comp-4. 01 rate comp-2. procedure division using hours rate giving total. if hours greater than 40 then compute total equals ((hours * rate) + ((hours - 40) * 1.5 * rate)) else compute total equals hours * rate. exit program.

You activate a VOS PL/I program with the VOS COBOL call statement. The data types of the arguments and corresponding parameters must be as listed in Table 6-1. The following restrictions also apply.
You can pass a structure to a VOS PL/I program only if all elementary items are of the
common types listed in Table 6-1. A COBOL group is passed as though it were a character string with a length equal to the total number of bytes in the members of the group.
If the corresponding parameter in the PL/I program uses a star extent with character
or character varying items, the with dope phrase must be used with that argument. Note: In PL/I, an extent is the bounds specification of an array or the declared length of a string variable. If the extent of the parameter is an asterisk, its corresponding argument can have extents of any value; the parameter takes on the extents of the corresponding argument.)
Any level-1 or level-77 argument or alphanumeric argument of display usage that

corresponds to a PL/I character parameter defined with the aligned attribute must be defined with the synchronized left phrase. Note: In VOS PL/I, all static and automatic data that is not contained in an array or structure is aligned on a word boundary. Within arrays and structures, some data may not be word-aligned. For example, storage for pictured data and unaligned, nonvarying character-string data is byte-aligned -- storage begins on the first available byte. Refer
6-6
to the description of the usage clause in VOS COBOL Language Manual (R010) for information about the default alignment of specific data types. The default alignments for all types are identical in the two languages. The allocation for structures containing noncontiguous elements is also identical in PL/I and COBOL. The COBOL group items are equivalent to the PL/I level 01 structures, and the COBOL elementary items are equivalent to the members of the PL/I structures. Normally, COBOL passes arguments by reference; that is, the storage address of each argument is pushed on the stack. In the case of a parameter that is passed by content, a COBOL program makes a copy of the argument and places the copys address on the stack. VOS PL/I, like VOS COBOL, assumes that data is passed by reference.
A VOS PL/I Procedure

The following PL/I program sample_proc.pl1 shows the example subprogram in VOS PL/I. The VOS COBOL program passes three arguments to sample_proc.pl1, which modifies the value of one argument.
sample_proc: procedure (hours, rate, total); dcl hours dcl rate dcl total fixed binary (15); float binary (53); float binary (53);
if hours > 40 then total = (hours * rate + (hours - 40) * (3 * rate)/2); else total = hours * rate; end sample_proc;
A VOS PL/I Function

You call a VOS PL/I function from a COBOL program as you would call a COBOL function, using the call statement. A function is a special kind of procedure that returns a value. In COBOL, when you call a function, you must specify the giving phrase with the call statement. In the PL/I procedure statement, you declare the data type of the returned value with the returns option. The following PL/I function sample_funct.pl1 shows the example function in VOS PL/I. It returns a value of data type decimal(5,2).
sample_funct: procedure (hours, rate) returns (float binary(53)); dcl hours dcl rate fixed binary (15); float binary (53);
if hours > 40 then return (hours * rate + (hours - 40) * (3 * rate)/2); else return (hours * rate); end sample_funct;
6-7
Calling a PL/I Program with Dope

In a PL/I program, the declared length of a string variable is called the extent of the variable. For example, if a character string is declared as character(256), the extent of the variable is 256. A character string in PL/I can have a dynamically determined extent, called a star extent. In the items declaration, the extent is represented by an asterisk (*). The actual length of the character string is resolved at run time. The following PL/I program, pl1_extent, declares star extents for two parameters. The first parameter is declared as character(*) aligned. It is a fixed-length character string corresponding to COBOLs display usage; the length is determined by the calling program, which must specify the with dope phrase with that argument in the call statement. The second parameter is declared as character(*) varying. It is a varying-length character string corresponding to COBOLs display-2 usage; the maximum length is determined by the calling program.
pl1_extent: procedure(in_str1, in_str2); dcl in_str1 character(*) aligned; dcl in_str2 character(*) varying; put skip list ('The length of' , in_str1, 'is' , length(in_str1)); put skip list ('The length of' , in_str2, 'is' , length(in_str2)); return; end;
The following COBOL program calls pl1_extent using the with dope phrase. The with dope phrase is used with the items that are declared with star extents in the PL/I program.
identification division. program-id. cobol_with_dope. data division. 01 string-1 picture x(30) display. 01 string-2 picture x(30) display-2. procedure division. display 'Enter two character strings, separated by a space.'. accept value of string-1 string-2. call 'pl1_extent' using string-1 with dope string-2 with dope. exit program.
Specifying PL/I Data Types

The following example is the PL/I procedure statement for the subprogram sample_proc.pl1. Note that the parameters are listed in the order in which they are passed. Their position corresponds to the arguments in the COBOL call statement.
sample_proc: procedure (hours, rate, total);
6-8
Referencing VOS Pascal Programs
The COBOL call statement is:

call 'sample_proc' using hours rate total.
The following table shows the data type of each PL/I parameter in the parameter list and the data type of the corresponding VOS COBOL argument. Data Item
hours rate
PL/I
fixed binary(15) decimal(4,2)
COBOL
comp-4 comp-6 picture s99v99
Description Integer Four-digit decimal with two places to the right of the decimal point Five-digit decimal with two places to the right of the decimal point
total
decimal(5,2)
comp-6 picture s999v99
Note: It is not necessary that these parameters have the same name, only that they be of compatible data types.

You call VOS Pascal procedures and activate VOS Pascal functions from within a VOS COBOL program. VOS Pascal procedures and functions use two kinds of parameters: variable parameters and value parameters. Variable parameters can be altered by the called procedure or function; these correspond to COBOL arguments that are passed by reference (the default). Value parameters cannot be altered; these correspond to COBOL arguments that are passed by content. To pass a COBOL argument by content (value) specify the by content phrase with the call statement. Earlier in this chapter, Table 6-1 shows how VOS COBOL data types correspond to VOS Pascal data types. You can pass a table or record to a VOS Pascal program only if all elementary items or members are of the common types listed in Table 6-1.
A VOS Pascal Procedure

The following Pascal procedure, sample_proc.pascal shows the example subprogram in VOS Pascal. The VOS COBOL program passes three arguments to sample_proc.pascal, which defines two of these as value parameters and one as a variable parameter. (The variable parameter is declared by specifying the Pascal key word var.) The Pascal program modifies
6-9
the variable parameter. Note that the data type short is defined as the subrange -32768..32767 to correspond to the comp-4 COBOL data type.
type short = -32768..32767; procedure sample_proc (hours: short; rate: real; var total: begin if hours > 40 then total := hours * rate + (hours - 40) * 1.5 * rate else total := hours * rate; end. real);
A VOS Pascal Function

You call a VOS Pascal function from a COBOL program as you would call a COBOL function, using the call statement. In Pascal, a function is a type of subprogram that returns a value. In COBOL, when you call a function, you must specify the giving phrase with the call statement. The following Pascal function sample_funct.pascal shows the example function in VOS Pascal. It returns a value of data type real.
type short = -32768..32767; function sample_funct (hours: short; rate: real): real;
begin if hours > 40 then sample_funct := hours * rate + (hours - 40) * 1.5 * rate else sample_funct := hours * rate; end.
Specifying Pascal Data Types

The following example is the Pascal procedure statement for the subprogram sample_proc.pascal. Note that the parameters are listed in the order in which they are passed. Their position corresponds to the arguments in the COBOL call statement.
procedure sample_proc (hours: short; rate: real; var total: real);
The COBOL call statement is:

The following table shows the data type of each Pascal parameter in the parameter list and the data type of the corresponding VOS COBOL argument. Since Pascal does not have a fixed-point decimal data type, the sample program uses a real data type.
6-10
Referencing VOS C Functions
Data Item
hours rate total
Pascal
-32768..32767 real real
COBOL
comp-4 comp-2 comp-2
Description Short integer Real number Real number

All routines in the C language are called functions. C functions can be treated as subprograms and can be activated by a VOS COBOL call statement. COBOL passes the address of arguments by reference (the storage address of each argument is pushed on the stack). C passes arguments by value (the actual value is pushed on the stack, instead of the address of that value). To pass arguments to a C function, you define the parameters of the C function to be pointers. See Table 6-1 for the C language data types that correspond to COBOL data types.
A VOS C Function That Does Not Return a Value

To write a VOS C function that does not return a value, (that is, behaves like a COBOL or PL/I procedure), you must define the function with the void type specifier. You specify the functions formal parameters as pointers. In the COBOL program, you activate the function with a COBOL call statement. The following C function sample_proc.c shows the example subprogram in VOS C. The VOS COBOL program passes three arguments to sample_proc.c, a void function that modifies the storage location pointed to by one of these parameters.
void sample_proc(short *hrs_ptr, double *rate_ptr, double *total) { short double
hours; rate;
hours = *hrs_ptr; rate = *rate_ptr; if (hours > 40) *total = hours * rate + (hours - 40) * 1.5 * rate; else *total = hours * rate; return; }
6-11
In this example, note that the argument hours in the COBOL program has the comp-4 data type; whereas, the corresponding parameter hrs_ptr in the C function sample_proc.c is a pointer to a value of the short data type.
A VOS C Function That Returns a Value

You activate a VOS C function within a COBOL program in the same way you activate a COBOL function. You must write the C function to expect addresses instead of values. Therefore, you declare the C parameters to be pointers. The following C function, sample_funct.c, shows the example function in VOS C. The VOS COBOL program passes two arguments to sample_funct.c, which returns a value of data type double.
double sample_funct(short *hrs_ptr, double *rate_ptr) { short double
hours; rate;
hours = *hrs_ptr; rate = *rate_ptr; if (hours > 40) return hours * rate + (hours - 40) * 1.5 * rate; else return hours * rate; }
Again, note that the arguments in the COBOL program are not pointers; but the corresponding parameters in the C program are pointers.
Specifying C Data Types

The following example is the C procedure statement for the void function sample_proc.c. Note that these parameters are listed in the order in which they are passed. Their position corresponds to the arguments in the COBOL call statement.
void sample_proc(short *hrs_ptr, double *rate_ptr, double *total)
The following example shows the COBOL call statement.

The following table shows the data type of each C parameter in the parameter list and the data type of the corresponding VOS COBOL argument. Since C does not have a fixed-point decimal data type, the sample program uses a floating-point data type.
6-12
Referencing VOS FORTRAN Programs
Data Item
hrs_ptr/hours rate_ptr/rate
C
short * double *
COBOL
comp-4 comp-2
Description Integer Binary floating-point value Binary floating-point value
total
double *
comp-2
Notes: 1. It is not necessary that these parameters have the same name, only that they be of compatible data types. 2. The C language null pointer value is not equivalent to the VOS COBOL null pointer value.
Referencing VOS FORTRAN Programs

You call VOS FORTRAN subroutines and activate external VOS FORTRAN functions from within VOS COBOL programs as long as the data types of the arguments and their corresponding parameters are as shown in Table 6-1. Arguments in FORTRAN are passed by reference, so compatibility with COBOL is not a problem. However, you should be aware of the following limitations.
The dimensions of FORTRAN arrays are stated in the reverse of the order in which they
are stated in COBOL. Therefore, you must reverse the subscripts of any table arguments.
You cannot use a VOS FORTRAN assumed-size dummy array. To achieve the same
affect, declare a dummy array with dummy bounds. Then pass the first element of the COBOL table to the dummy array and the bounds of the table to the dummy bounds (remembering to reverse the order of the dimensions).
A VOS FORTRAN Subroutine

FORTRAN subroutines are activated by COBOL call statements. The following VOS FORTRAN subroutine sample_proc.fortran shows the example subprogram in VOS FORTRAN. The VOS COBOL program passes three arguments to sample_proc.fortran, which modifies the value of one argument.
subroutine sample_proc (hours, rate, total) integer*2 real*8 real*8 hours rate total
6-13
Referencing VOS FORTRAN Programs if (hours .gt. 40) then total = ((hours * rate) + ((hours - 40) * 1.5 * rate)) else total = (hours * rate) end if end
A VOS FORTRAN Function

You call a VOS FORTRAN function from a COBOL program as you would call a COBOL function. You indicate that you are calling a VOS FORTRAN function in the calling program by specifying the giving phrase with the COBOL call statement. The following FORTRAN function sample_funct.fortran shows the example function in VOS FORTRAN. The VOS COBOL program passes two arguments to sample_funct.fortran, which returns a value of data type real*8.
real*8 function sample_funct (hours, rate) integer*2 real*8 hours rate
if (hours .gt. 40) then sample_funct = ((hours * rate) + ((hours - 40) * 1.5 * rate)) else sample_funct = (hours * rate) end if return end
Specifying FORTRAN Data Types

The following example is the FORTRAN subroutine statement for the subprogram sample_proc.fortran. Note that these parameters are listed in the order in which they are passed. Their position corresponds to the arguments in the COBOL call statement.
subroutine sample_proc (hours, rate, total)

The following table shows the data type of each FORTRAN parameter in the parameter list and the data type of the corresponding VOS COBOL argument passed to the FORTRAN routine. Since FORTRAN does not have a fixed-point decimal data type, the sample program uses a real data type.
6-14
Referencing VOS BASIC Programs
Data Item
hours rate total
FORTRAN
integer*2 real*8 real*8
COBOL
comp-4 comp-2 comp-2
Description Integer Real number Real number

You can use the COBOL call statement to activate a VOS BASIC subprogram. Because VOS BASIC does not support external functions, you cannot activate a BASIC function from COBOL. All arguments must have data types that are supported by VOS BASIC. You can also pass an array as an argument provided that VOS BASIC supports the data type of the array components. See Table 6-1 for the BASIC language data types that correspond to COBOL data types.
A VOS BASIC Subprogram

BASIC subprograms are defined by a sub statement. The format of a BASIC sub statement consists of the BASIC key word sub or subprogram, the name of the subprogram, and an optional parameter list. The following VOS BASIC subprogram sample_proc.basic shows the example subprogram in VOS BASIC. The VOS COBOL program passes three arguments to sample_proc.basic, which modifies the value of one of the arguments.
sub sample_proc (hours%=15, rate=15, total=15) & &
if hours%>40 then total = ((hours% * rate) + ((hours% - 40) * 1.5 * rate)) else total = hours% * rate subend
Specifying BASIC Data Types

In BASIC, the last character in a name indicates the data type of the parameter, as shown in the following table.
6-15
Last Character
$ # %
Data Type Character string Fixed decimal Integer Floating-point
All others
In BASIC, you also can declare the precision of a parameter. The precision of a parameter follows an equal sign (=) or less-than-or-equal-to sign (<=) after the name. Array parameters have a set of parentheses between the name and the precision. If the array is one-dimensional, the parentheses contain nothing; for example, name%()=p. If the array is two-dimensional, the parentheses contain a comma; for example, name#(,)=(p,q). The following example is the BASIC sub statement for the subprogram sample_proc.basic. Note that these parameters are declared in the order in which they are passed. Their position corresponds to the arguments in the COBOL call statement.
sub sample_proc (hours%=15, rate#=(4,2), total#=(5,2))

The following table shows the data type of each BASIC parameter in the parameter list and the data type of the corresponding VOS COBOL parameter. Data Item
hours rate
BASIC
hours%=15 rate#=(4,2)
COBOL
comp-4 comp-6 picture s99v99
Description Integer Four-digit decimal with two places to the right of the decimal point Five-digit decimal with two places to the right of the decimal point
total
total#=(5,2)
comp-6 picture s999v99
6-16
Chapter 7: National Language Support and VOS COBOL

VOS COBOL provides complete support for National Language Support (NLS) software. NLS enables you to write a program that can manipulate character strings from character sets other than the ASCII character set. NLSNational Language Support VOS COBOL supports eight supplementary character sets:
7-
the Korean hangul character set, as defined by the Korean Standard (KS) C 5601 the Japanese kanji character set, as defined by the Japanese Industrial
Standard (JIS) C 6226
the Japanese katakana character set, as defined by JIS C 6220 the characters added to the ASCII character set to complete Latin alphabet No. 1, as
defined by the International Organization for Standardization document ISO 8859/1.
the PRC Chinese Graphic character set, as defined by the Chinese Association of
Standards (CAS) GB 2312
the ROC Chinese Graphic character set (Part 1), as defined by the Central Bureau of
Standards (CBS) General Hantz Standard (GHS)
the ROC Chinese Graphic character set (Part 2), as defined by the Central Bureau of
Standards (CBS) General Hantz Standard (GHS)
the user-defined, double-byte character set.

Non-ASCII character sets are called supplementary character sets, and strings containing characters from these sets are called NLS strings. Non-ASCII characters, except for those in Latin alphabet No. 1, cannot be displayed on an ASCII terminal screen. However, you can compile, bind, and run programs that contain NLS strings. To display NLS strings, you must have a terminal that has the correct keyboard mapping to display the non-ASCII characters. This chapter describes the following aspects of NLS strings:
NLS string representation shift characters and NLS strings default character sets of string constants checking the contents of strings character sets and NLS functions.
7-1
National Language Support and VOS COBOL
NLS String Representation

An NLS string is a sequence of bytes that represents a sequence of character codes. Unlike codes for ASCII characters, some NLS character codes occupy more than one byte. Table 7-1 shows the number of bytes per character for each character set.
1
Table 7-1. Number of Bytes per Character Character Set ASCII Latin alphabet No. 1 kanji katakana hangul Simplified Chinese ROC Chinese Part 1 ROC Chinese Part 2 user-defined, double-byte Number of Bytes Per Character 1 1 2 1 2 2 2 2 2
The hexadecimal values that represent the ASCII characters and the non-ASCII characters are shown in Figure 7-1. These values are called character codes. Each value at the top of the table indicates the first hexadecimal digit of a character code, and each value to the left of the table indicates the second hexadecimal digit of a character code. For example, the character Y (uppercase letter Y) is represented by the code 59. The left half of Figure 7-1 contains the ASCII character codes. These character codes are denoted by hexadecimal values in the range 00 to 7F. The right half of Figure 7-1 contains the non-ASCII character codes. The non-ASCII character codes are denoted by hexadecimal values in the range 80 to FF.
7-2

1
0 0 1 2 3 4 5 6 7 8 9 A B C D E F
2 SP ! " # $ % & ' ( ) * + ' . /
3 4 0 1 2 3 4 5 6 7 8 9 A B C D E F @ A B C D E F G H I J K L M N O
5 6 P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g h
8 SSI SS4 SS5 SS6 SS7 SS8 SS9 SS10 SS11 SS12 SS13 SS14 SS15 SS2 SS3
9 LSI WPI XCI BDI
C D
BEL BS HT LF SUB VT ESC FF CR
p q r s t u v w x i y j z k { l | m } n o DEL
SUPPLEMENTARY
SET OF
GRAPHIC
CHARACTERS
CONTROL GRAPHIC LEFT-HAND
CONTROL
GRAPHIC
RIGHT-HAND
tx005
CHARACTER SETS
Figure 7-1. The VOS Internal Character Coding System Each half of Figure 7-1 can be divided into codes that represent control characters and graphic characters. Control characters perform a control function, such as the carriage return function. These characters cannot be printed or displayed on a terminal screen. Graphic characters, on the other hand, can be printed by a printer or displayed on a terminal screen. The control characters in the right half of Figure 7-1 are the right control characters. Certain of these control characters, called shift characters, specify that the subsequent byte or series of bytes represent a character or characters from a particular character set. Because of these shift characters, you can create an NLS string that contains characters from more than one character set. The graphic characters in the right half of Figure 7-1 are the right graphic characters. These character codes represent all the characters in the supplementary character sets.
Shift Characters and NLS Strings

There are two types of shift characters: single-shift characters and locking-shift characters. A single-shift character operates on one character. A locking-shift character operates on all subsequent characters until another shift character unlocks the shift.
7-3
With a combination of single-shift characters and locking-shift characters, there are a number of ways you can represent the same NLS string. However, there are two forms, the canonical form and the common form, that are used in storing character data. Canonical Strings A canonical string is a string in which every right graphic character is preceded by a single-shift character. The disadvantage to using canonical strings is that they require a large number of bytes. The following list explains the advantages to using canonical strings.
Every character has a unique and unambiguous representation. An algorithm can be developed to examine characters proceeding forward or backward
from any point within a canonical string.
Certain predefined string-handling functions operate as expected on canonical strings

(for example, the index function). The VOS COBOL compiler provides a predefined shift function that takes any valid NLS string as an argument and yields the equivalent canonical string. Common Strings A common string is a string in which every right graphic character, except those from Latin alphabet No. 1, is preceded by a single-shift character. If the string contains only Latin alphabet No. 1 characters, the common string contains no shift characters. If a common string contains only Latin alphabet No. 1 characters, no special programming considerations are necessary. VOS COBOL supports text files containing characters from the NLS character sets. If a program reads data from a text file, it interprets NLS strings as common strings. VOS COBOL provides a predefined unshift function that converts any valid NLS string to an equivalent NLS string with a default character set. All shift characters for the default character set are removed.
Default Character Sets of String Constants

By default, the compiler stores string constants as common strings. However, if you do not specify the latin_1 option, the compiler does not check to ensure that all character string constants are valid, unless you specify a default character set. VOS COBOL allows you to store string constants as shown in Table 7-2.
2
Table 7-2. Default Character Set Options Character Set No specification

latin_1 none
String Type Common Common Canonical
Checking No Yes Yes
7-4
You can specify a default character set in the object-computer paragraph of the Configuration Section of your program. The entry for specifying the default character set has the following syntax.
object-computer. stratus character set [default] [is] none latin_1 alphabet-name .
The VOS COBOL compiler also allows you to specify latin_1 to define an alphabet name in the special-names paragraph. If you specify one of the other VOS COBOL-supported alphabet names (native, ascii, ebcdic, standard-1, standard-2, or a user-defined alphabet consisting of a series of literal definitions), it has the same effect on interpreting NLS strings as specifying latin_1. If you specify latin_1 or an equivalent, the compiler stores all string constants as common strings and checks all string constants to ensure that they are valid. If you specify none, the compiler stores all string constants as canonical strings. If you do not specify either option, the default character set is Latin alphabet No. 1. If you use the none option with a program that consists of more than one source module, you should specify the none option in each source module that contains string constants to ensure compatibility. However, if you use the latin_1 option, you need not specify it in each module because latin_1 is the default option.
Checking the Contents of Strings

Often it is useful to determine whether or not a string is an ASCII string, since faster and simpler algorithms can be used with such strings. For example, suppose you want to determine whether one string is contained in an array of strings. The following algorithm assumes an equivalency of one character to one byte.
accept value of str. move 'no' to found. perform varying i from 1 by 1 until found = 'yes' or i = n if !index(array(i), str) not equal zero move 'yes' to found.
This algorithm gives the correct results for ASCII strings and simple strings, but not for other types of NLS strings. The following equivalent algorithm gives the correct results for an array that contains NLS strings in canonical form.
accept value of str. move 'no' to found. move !shift(str) to canon_str. perform varying i from 1 by 1 until found = 'yes' or i = n if !index(array(i), canon_str) not equal zero move 'yes' to found.
7-5
However, the following algorithm gives the correct results for an array that contains NLS strings in common form.
accept value of str. move 'no' to found. move !shift(str) to canon_str. perform varying i from 1 by 1 until found = 'yes' or i = n if !index(!shift(array(i)), canon_str) not equal zero move 'yes' to found.
If the array is large and the search string is often an ASCII string, it may be useful to look first at the string being compared and then optimize the preceding algorithms. You can combine the collate function with the non-match function for this purpose. The collate function returns a string that is 128 bytes long (256 bytes if you specify full-ascii); each byte contains the decimal value of the ASCII character that corresponds to the ASCII character having that position in the character set, from 0 (NUL) through 127 (DEL). For example, position 49 contains the number 1, and position 78 contains the uppercase letter N. The non-match function compares the string str, from the previous example, to this string to determine whether it contains any characters that are not in the ASCII character set. If all characters in the string are ASCII, the non-match function returns zero; if one or more characters is non-ASCII, the non-match function returns the character position of the character in the first argument (str) that is non-ASCII. For example:
accept value of str. move 'no' to found. if !non-match(str, collate()) equal zero All characters in str are ASCII perform varying i from 1 by 1 until found = 'yes' or i = n if !index(array(i), str) not equal zero move 'yes' to found end-perform else At least one character in str is non-ASCII move !shift(str) to canon_str perform varying i from 1 by 1 until found = 'yes' or i = n if !index(!shift(array(i)), canon_str) not equal zero move 'yes' to found end-perform.
For complete information about the VOS COBOL functions, refer to VOS COBOL Language Manual (R010).
Character Sets and NLS Functions

Each character set has an integer, called a character set ID, associated with it. These character set IDs are used as arguments to certain VOS COBOL predefined functions. For example, a character set ID is an argument to the shift and unshift functions to specify the default
7-6
character set of a string. Table 7-3 shows the mnemonic name and character set ID for each of the character sets.
3
Table 7-3. NLS Mnemonic Names and Character Set IDs Mnemonic Name
ASCII_CHAR_SET LATIN_1_CHAR_SET KANJI_CHAR_SET KATAKANA_CHAR_SET HANGUL_CHAR_SET SIMPLIFIED_CHINESE CHINESE1 CHINESE2 USER_DBCS
Character Set ID 0 1 2 3 4 5 6 7 8
To use any of these mnemonic names, you must include the file char_sets.incl.cobol in your program with the copy statement. For information on NLS functions, see VOS COBOL Language Manual (R010).
7-7
7-8
Appendix A: The VOS Character Code Set

Table A-1 shows the VOS Character Code Set. The left side is the ASCII character set, and the right side is Latin alphabet No. 1.
1
A-
Table A-1. VOS Character Code Set
Hex Digits 1st 0 2nd
2 SP ! " # $ % &
3 0 1 2 3 4 5 6 7
4 @ A B C D E F G H I J K L M N O
5 P Q R S T U V W X Y Z [ \ ] ^
7 p q r s t u v w x y z { | } ~
A NBSP
0 1 2 3 4 5 6 7 8 9 A B C D E F
`
a b c d e f g h i j k l m n o
` A
2 3
D ^ O ~ O .. O X U .. U Y P
~ A .. A E
y p
PD0005
( ) * +
8 9 : ; < = > ?
SHY

1 / 4 1 / 2 3/ 4
, _ .
/
__
Control characters that do not have a graphic representation in ISO 8859/1
A-1
The VOS Character Code Set
A-2
Appendix A: The VOS Character Code Set
Appendix B: Differences Between COBOL-74 and COBOL-85

The VOS COBOL compiler now supports the ANSI Programming Language COBOL standards X3.23-1985 (COBOL-85) and X3.23-1974 (COBOL-74). In addition, VOS-specific extensions to ANSI Standard COBOL have been implemented. Users can compile using a COBOL-74 option that includes the VOS extensions available with previous releases, a full ANSI COBOL-85 option, or two options that invoke intermediate subsets of COBOL-85, which have been implemented for compatibility. This appendix describes the differences between the subsets of ANSI COBOL that are supported by the VOS COBOL compiler. This appendix has three sections that describe the following:
B-
compiler language options VOS COBOL language differences a simple procedure for upgrading a VOS COBOL program from COBOL-74 to
COBOL-85. Note: The VOS COBOL compiler that has been available prior to Release 10.0 supports COBOL-74 and many VOS extensions, which are also elements of COBOL-85. In this manual, this version of the language is referred to as pre-Release 10.0 VOS COBOL. Where it is necessary to define incompatibilities between the ANSI standards, the terms COBOL-74 and COBOL-85 are used.
VOS COBOL Compiler Language Options

The -language argument of the cobol command enables you to select from the following subsets of VOS COBOL.
full_ansi85. This option provides complete ANSI COBOL-85 support. ansi85. This option provides complete COBOL-85 support except for the use of call
identifier statements to reference nested programs and the static reinitialization of ends of perform ranges.
B-1
compatible. This option provides the COBOL-85 functionality that is compatible,

except for the introduction of new reserved words, with COBOL-74.
ansi74. This option includes full COBOL-74 support and the VOS extensions
provided in pre-Release 10.0 VOS COBOL. Note: If you do not specify a language option in the command line form, the program is compiled with the compatible option.
The full_ansi85 Language Option

If the full_ansi85 language option is specified, the program compiles and executes in accordance with ANSI Standard COBOL-85 (except where other options are required for unusual or incompatible situations, as specifically noted below). Most existing programs compile and execute as if compiled by the pre-Release 10.0 COBOL compiler. See Substantive Changes Potentially Affecting Existing Programs in VOS COBOL Language Manual (R010) for a list of potential differences in program execution. If you specify the -level compiler argument with the full_ansi85 language option, the levels diagnosed are based on ANSI Standard COBOL-85 as follows:
-level 1. All elements not in the ANSI Standard COBOL-85 low subset are
diagnosed.
-level 2. All elements not in the ANSI Standard COBOL-85 intermediate subset are
diagnosed.
-level 3. All elements not in the ANSI Standard COBOL-85 high subset are
diagnosed (this includes ANSI-defined obsolete elements, as well as VOS COBOL extensions).
-level 4. All elements not in the ANSI Standard COBOL-85 high subset nor in the
ANSI-defined list of obsolete elements (that is, VOS COBOL extensions only) are diagnosed. To achieve full compatibility with ANSI Standard COBOL-85, specify the -mapcase compiler argument so that uppercase and lowercase letters are treated equivalently. If the obsolete segmentation facility is used and the special behavior associated with independent segments is required, then the -segmentation compiler argument must be specified. Note: This requirement is very rare. In this situation, you must specify the -segmentation compiler argument even if you use the pre-Release 10.0 COBOL compiler.
B-2
If you do not want the exit program statement to return control when the program is invoked by the operating system, then the -main compiler argument must be specified. Note: This requirement is very rare. In this situation, you must specify the -main compiler argument even if you use the pre-Release 10.0 COBOL compiler.
The ansi85 Language Option

If the ansi85 language option is specified, the program compiles and executes in accordance with ANSI Standard COBOL-85 except as specifically noted below. Most existing programs compile and execute as if compiled by the pre-Release 10.0 COBOL compiler. See Substantive Changes Potentially Affecting Existing Programs in VOS COBOL Language Manual (R010) for a list of potential differences in program execution. Note: An important difference between this option and the compatible language option is the treatment of the global key word. If you specify ansi85, global no longer indicates shared external data (applicable only to tasking environments). Instead, global indicates the global meaning specified by ANSI Standard COBOL-85. Any instances of global that occur in existing programs to indicate external shared data must be changed to the word shared. If you specify the -level compiler argument with the ansi85 language option, the levels diagnosed are based on ANSI Standard COBOL-85 as described in the full_ansi85 Language Option above. The ansi85 option provides the same complete ANSI COBOL-85 support as the full_ansi85 option with the following exceptions.
full_ansi85 allows the user to specify the cancel and call identifier
statements to reference a nested COBOL program that is not externally visible. (Note that any accessible nested program can always be called by specifying call literal, regardless of the language option.) At run time, cancel and call identifier, as implemented by pre-Release 10.0 COBOL (and by Release 10.0 COBOL when full_ansi85 is not specified), utilize existing information provided by the binder in the program module. This information is not available for programs that are not externally visible (that is, nested programs). Thus, all compiled programs, regardless of whether they use these features, contain significant additional information and so may execute more slowly under certain circumstances. A user who requires this special functionality must explicitly indicate so, allowing users who do not require this functionality to avoid the accompanying performance degradation and program-module size increase.
full_ansi85 causes all ends of perform ranges to be considered complete when the
program executes an exit program. This behavior is required by ANSI Standard COBOL-85, but it provides little benefit with significant loss of performance. Also, this behavior is inconsistent with the behavior of programs compiled with the pre-Release 10.0 VOS COBOL compiler. VOS COBOL provides the capability of defining recursive programs as an extension to ANSI. Such programs always retain end of perform range information applicable
B-3
to their particular invocation. Thus, if full_ansi85 is not specified, the cost of dynamic reinitialization of end of perform ranges can be borne by only those programs that require this behavior. Note: It is extremely rare for the occurrence of this reinitialization to affect the execution of a nonrecursive program. The object code produced by the compiler using the ansi85 option executes as efficiently as that produced by the pre-Release 10.0 COBOL compiler and adheres to all ANSI Standard COBOL-85 specifications except for the two discussed above, which suffices for most COBOL programs. The ansi85 option will probably be the language option specified when a decision is made to migrate existing programs to ANSI Standard COBOL-85.
The compatible Language Option

If the compatible language option is specified, the program is compiled as if the pre-Release 10.0 COBOL compiler were invoked, with the following exceptions.
Any ANSI Standard COBOL-85 functionality that is compatible with ANSI Standard
COBOL-74 functionality is supported, with the exception of the capability to define global data.
Any use of those ANSI Standard COBOL-85 reserved words that were user-defined
words in pre-Release 10.0 COBOL is diagnosed. If the -level compiler argument is specified, it functions as described in The full_ansi85 Language Option above. Existing programs that were successfully compiled with the pre-Release 10.0 COBOL compiler and that successfully compile using the compatible option (that is, that contain no invalid usage of new reserved words) are guaranteed to execute identically. In a few cases, this execution may not conform to the behavior required by ANSI Standard COBOL-85. See Substantive Changes Potentially Affecting Existing Programs, in VOS COBOL Language Manual (R010), for a list of behaviors that do not occur when compatible is specified. The compatible option is the default. It will probably be used to compile existing programs, since program execution is not affected by COBOL-85 incompatibilities. In addition, you can use all new COBOL-85 functionality except for a few language elements that are incompatible with ANSI Standard COBOL-74.
The ansi74 Language Option

If the ansi74 language option is specified, the program is compiled as if it were compiled by the pre-Release 10.0 COBOL compiler. The language extensions already supported by the pre-Release 10.0 COBOL compiler are supported when this option is used (that is, this does not restrict programs to use only elements of COBOL-74). However, no other COBOL-85 language elements are supported. If the -level compiler argument is specified with the ansi74 language option, it functions based on ANSI Standard COBOL-74 as follows:
B-4
VOS COBOL Language Differences
-level 1. All elements not in the 1974 FIPS (Federal Information Processing
Standard) low subset are diagnosed.
-level 2. All elements not in the 1974 FIPS low-intermediate subset are diagnosed. -level 3. All elements not in the 1974 FIPS high-intermediate subset are diagnosed. -level 4. All elements not in the 1974 FIPS high subset (that is, VOS COBOL
extensions) are diagnosed. If you specify the ansi74 option, existing programs that were successfully compiled with the pre-Release 10.0 COBOL compiler are guaranteed to compile successfully and to execute identically.

This section describes the VOS COBOL language differences that are introduced in Release 10.0. These differences fall into the following categories:
new functionality introduced with Release 10.0 differences between the full_ansi85 and ansi85 language options differences between the ansi85 and compatible language options differences between the compatible and ansi74 language options.
New Functionality
This section describes changes to VOS COBOL that are new in Release 10.0, but are not unique to any of the language options. These changes apply whether you compile with the ansi74, compatible, ansi85, or full_ansi85 option. These features are as follows:
specifying -ansi_replace defining default class storage using label variables using entry variables defining functions with Procedure Division syntax specifying recursive programs eliminating words with the %replace directive.
Specifying -ansi_replace VOS 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 using the ANSI replace statement requires that the source file be preprocessed. Release 10.0 VOS COBOL introduces the -ansi_replace compiler argument. If you specify this argument, the compiler initially preprocesses the entire source file, so that all replace statements are treated consistently: if the file contains only simple replace statements, they are all treated as %replace compiler directives; if it contains any complex replace statements, they are all treated as ANSI replace statements.
B-5
For further information about the replace statement and the %replace compiler directive, refer to VOS COBOL Language Manual (R010). Defining Default Class Storage In pre-Release 10.0 VOS COBOL, automatic data is defined using the key word dynamic; based data is defined in the Linkage Section. In Release 10.0, you can first define the storage class of data by specifying the
-default_class compiler argument to indicate that all uninitialized working-storage data should be allocated as automatic or static. Or you can override the -default_class argument, and explicitly define based, auto, or static within your program by specifying the class clause.
Note: If you specify the ansi74 language option, you must not specify the class key word. This word is optional in the class clause when the data description entry contains an explicit data name. Refer to Specifying the Default Allocation Type, in Chapter 2, for more information about the -default_class argument. Refer to VOS COBOL Language Manual (R010) for more information about specifying the class clause to define data. Note: You can still define storage as in pre-Release 10.0 VOS COBOL, but at some point in the future, this method may no longer be supported. Using Label Variables The Release 10.0 compiler supports label variables in limited contexts. You can pass and receive label variables as arguments, and set and compare label variables to each other using move and if statements. You can also set a label variable to a procedure name defined in either the current program or a containing program by specifying the set statement. For example:
set label label_variable to [global] procedure_name .
Refer to VOS COBOL Language Manual (R010) for additional information about the set statement. The go to statement provides an option for transferring program control through a label variable. For example:
go to label label_variable.
Refer to VOS COBOL Language Manual (R010) for additional information about the go to statement. The debugger supports label variables in the display, set, and symbol requests. Using Entry Variables The Release 10.0 VOS COBOL compiler supports additional functionality for entry variables.
B-6
Previously, users could pass and receive entry variables as arguments, set and compare them using move and if statements, and use them as the target of a call statement. To convert a character string to an entry variable, you had to call the operating system subroutine s$find_entry. Because the Release 10.0 compiler supports nested programs, and a character-string variable may contain the name of an internal entry not visible to the binder, the entry variable might not be accessible to s$find_entry. The Release 10.0 compiler enables you to specify the compute entry statement to set entry variables from character-string variables:
compute entry entry_var = alphanumeric_expression [on exception ...]
[not on exception [end-compute]
...]
You can also convert an entry-constant name to an entry-variable name using the set entry statement.
set entry entry_var to program_name.
Unlike the compute entry statement, which requires the binder to retain all entry names, the set entry statement involves no computation. If the value of program_name cannot be resolved at bind time, the binder issues an error. Refer to Specifying Optional Directives, in Chapter 3, for additional information about retaining entry names. For additional information about the set and compute statements, refer to VOS COBOL Language Manual (R010). Defining Functions with Procedure Division Syntax In Release 10.0 VOS COBOL, the syntax of the Procedure Division header has been extended to allow the definition of functions using the giving key word. When an exit program statement is executed in a program defined with the giving phrase, the value of the data name specified with the giving phrase is returned as the function result to the caller. Such a program must be invoked as a function. Refer to VOS COBOL Language Manual (R010) for more information about the Procedure Division header. Specifying Recursive Programs In Release 10.0 VOS COBOL, the method of indicating a recursive program has been changed. The mode is recursive phrase of the object-computer paragraph is now obsolete, and at some time in the future, may no longer be supported. Recursive behavior is now achieved by specifying the word recursive following the program-id statement. Refer to VOS COBOL Language Manual (R010) for additional information about the recursive clause.
B-7
Eliminating Words with the %replace Directive The %replace compiler directive can be specified to eliminate existing words in the source text using the word void. For example, the following %replace directive results in the elimination of the word global.
%replace global by void; . . . 01 data_name global. . . .
Differences Between the full_ansi85 and ansi85 Options

This section describes the differences between the full_ansi85 option and the ansi85 option. The differences are as follows:
support of the cancel statement reinitialization of perform ranges.

Support of the cancel Statement If you specify the full_ansi85 option, an additional, externally visible entry name is generated for every externally visible program. Because every program can be potentially canceled by a separately compiled program, the compiler creates a name consisting of the program-id name with the prefix x$, (for example, x$monthly_sales). The prefix is referenced when a request is made to cancel the program identified by the program-id. Refer to VOS COBOL Language Manual (R010) for additional information about the cancel statement. Reinitialization of perform Ranges COBOL-85 requires that when a program is exited, all perform statement ranges are reinitialized. In COBOL, paragraphs can be either executed sequentially (falling through from top to bottom) or under the control of a perform statement. The exit point of every end of a perform range must have an associated location to which control is transferred. The first time a program is executed, these locations are set so that control passes to the next statement. VOS COBOL-74 provides the capability of defining recursive programs as an extension of ANSI. The recursive clause causes this initialization to be performed each time the program is entered. Such programs always retain the end of perform range information applicable to their particular invocation. For a large program that is invoked frequently, the ongoing reinitialization required by COBOL-85 can slow execution. This type of reinitialization is done only with the full_ansi85 option. The other language options implement static initialization as it has been performed by the pre-Release 10.0 compiler.
B-8
Differences Between the ansi85 and compatible Options

This section describes the differences between the ansi85 option and the compatible option. The compatible option is an implementation of COBOL-85 that is compatible, with the exception of new reserved words and the ability to define global data, with the pre-Release 10.0 version of VOS COBOL. The ansi85 option represents a more complete implementation of COBOL-85. The differences are as follows:
support for global data names and file names I/O incompatibilities nested programs obsolete elements the perform...varying statement alphabetic class test variable-length assignments restrictions generating compiler errors.
Support for global Data Names and File Names Pre-Release 10.0 VOS COBOL uses the key word global to designate external shared data; Release 10.0 VOS COBOL uses global as specified in ANSI Standard COBOL-85 and uses the key words external shared to indicate shared data. Shared data is a nonstandard extension to VOS COBOL. Refer to VOS COBOL Language Manual (R010) for information about the use of the key word global to define data. I/O Incompatibilities There are subtle differences in the setting of file status codes and other file-handling behaviors between COBOL-74 and COBOL-85. The run-time behavior of an external file depends on the language option specified in the compilation of the program that first opens the file. It is possible to bind two or more programs that reference the same external file, even when one is compiled with the compatible language option (or using a pre-Release 10.0 compiler) and the other is compiled with the ansi85 language option. The differences are as follows:
file status codes I/O mode changes label records clause.

File Status Codes. Following various I/O situations, COBOL-85 and COBOL-74 define different file status codes. Table B-1 shows the file status codes that are generated for ansi85, and for compatible under the same conditions.
B-9

1
Table B-1. COBOL-85 and COBOL-74 File Status Codes (Page 1 of 2) COBOL-85 Codes COBOL-74 Codes Description
04 05 07 14
00 00 00 10
A record length error has occurred on a read statement. An optional file is not present in an open statement. An open or close statement contains a tape-oriented option, but the file accessed is not a tape file. A sequential read statement for a relative file returns a relative key number that does not fit in the specified relative key. A sequential write statement is attempted that would cause the relative key number to be larger than will fit in the specified relative key. An open input statement is attempted on a required file that is not present. An open statement is attempted on a file that is required to be mass storage but is not. An open statement is attempted on a file previously closed with lock. An open statement is unsuccessful due to a conflict between the fixed-file attributes and the attributes specified for that file. An open statement is attempted on a file that is already open. A close statement is attempted on a file that is not open. For a file in sequential access mode, the last I/O operation prior to a delete or rewrite statement was not a successfully executed read statement, as required. A boundary violation exists because an attempt is made to rewrite a record to a sequential file. A sequential read statement is attempted, but no next record exists because either: (1) the preceding start statement was unsuccessful, (2) the preceding read statement was unsuccessful, but did not cause an at end condition, or (3) the preceding read statement was unsuccessful, but caused an at end condition.
24
30
35 37 38 39
90, 92 90, 92 92 90, 92
41 42 43
92 93 30
44 46
30 30
B-10
Table B-1. COBOL-85 and COBOL-74 File Status Codes (Page 2 of 2) COBOL-85 Codes 47 48 COBOL-74 Codes 30 30 Description A read or start statement is attempted on a file not opened in input or I/O mode. A write statement is attempted for (1) a sequential file not opened in output or extend mode, or (2) a relative or indexed file not opened in I/O, output, or extend mode. A delete or rewrite statement is attempted on a file not opened in I/O mode.
49
30
I/O Mode Changes. In COBOL-74, when a file that is opened for I/O cannot be found, the compiler creates the file. Under COBOL-85 rules, an error occurs when a file that is opened for I/O cannot be found. The error code field is set to the system error code e$object_not_found (1032), the file status field is set to 35, and the compiler does not create the file. This behavior occurs only when you compile with the ansi85 or full_ansi85 language option. The label records clause. In COBOL-85, if the label records clause is omitted, the compiler behaves as if label records are standard were specified. In COBOL-74, it is an error to omit this clause, but as an extension, the VOS COBOL compiler behaves as if label records are omitted were specified. Note: Label records are relevant only to tape files. Nested Programs COBOL-85 supports nested programs. This feature does not introduce any incompatibilities. As an extension to ANSI Standard COBOL, the Release 10.0 compiler allows you to reference procedure names defined in containing blocks for the purpose of nonlocal transfer of control. That is, direct transfer can be made to a containing program with implicit stack unwinding as an alternative to a return by means of the exit program statement. The simple form of the go to statement is extended as follows:
go to [global] procedure_name.
The key word global preceding a procedure name indicates that it is defined in a containing program. The containing program need not directly contain the program in which the go to statement is executed. Obsolete Elements A number of language elements that were supported in the pre-Release 10.0 VOS COBOL compilers have been defined as obsolete in the COBOL-85 standard. One of these is the Communication module. This module, as defined in COBOL-74, is supported by the Release 10.0 compiler only if you compile with the ansi74 or compatible language option. Other obsolete elements, such as the Debug and Segmentation facilities, are included
B-11
for compatibility regardless of the language option, but at some time in the future, may no longer be supported. The perform ... varying Statement Within the varying... after phrase of the perform statement, the identifiers are incremented differently for COBOL-85 than for COBOL-74. The following is part of the syntax of the perform...varying statement that is affected:
perform procedure_name_1 varying identifier_1 from identifier_2 by identifier_3 until condition_1 [after identifier_4 from identifier_5 by identifier_6 until
condition_2] In COBOL-85, identifier_1, the object of varying, is augmented before identifier_4, the object of after, is set; in COBOL-74, identifier_1 is augmented after identifier_4 is set.
In COBOL-85, if identifier_1 and identifier_4 are subscripted, the subscript is reevaluated each time the identifier is set or augmented. If any of the following are subscripted, the subscript is reevaluated each time the value of the identifier is used in a setting or augmenting operation:
identifier_2, the object of varying ... from identifier_3, the object of varying ... by identifier_5, the object of after ... from identifier_6, the object of after ... by.
None of these subscripts are reevaluated in COBOL-74. The COBOL-85 behavior occurs if you compile with the ansi85 or full_ansi85 language option. The COBOL-74 behavior occurs if you compile with the ansi74 or compatible language option. Alphabetic Class Test If you compile with ansi85 or full_ansi85, the alphabetic class test is for uppercase letters, lowercase letters, and the space character. If you compile with compatible or ansi74, the alphabetic class test is for uppercase letters and the space character. Variable-Length Assignments In COBOL-85, when an assignment is made to a variable-length data item that contains the object of the depending on phrase, the maximum length of the data item is used. In
B-12
COBOL-74, the current length is used. For example, consider the following program data structure.
01 a_group. 02 a_count 02 a_table pic 99. pic x occurs 1 to 10 times depending on a_count.
If ansi74 or compatible is specified, then when data is moved to a_group, the current value of a_count is used to determine the number of bytes of data actually moved. Since a_count itself is affected by the move, the resulting value of a_group may not be consistent. For example, suppose a similarly defined structure named b_group is moved to a_group. If a_count contains the value 01 and b_count the value 05, only one element of b_table, along with b_count, would be moved (3 bytes in all); since the receiving field is shorter, right truncation occurs. However, the value of a_count after the move would be 05. Before COBOL-85, COBOL programmers typically avoided this potential problem by first moving the depending on field in such a structure, as the following example shows.
move b_count to a_count. move b_group to a_group.
If ansi85 or full_ansi85 is specified, then the maximum length of the variable occurrence table is implicitly moved to the object of the depending on phrase immediately preceding any move involving a containing group. Thus, if the sending field is shorter, the receiving field will be always filled to its maximum length with space characters, the defined behavior for alphanumeric moves. Although this action guarantees that the receiving field is always consistent, it causes the amount of data actually moved to be often larger than necessary and provides no way (other than reference modification) to code efficient moves to variable-length items. The performance difference is significant only for groups containing variable-length tables in which the maximum number of occurrences is very large in comparison with the number of occurrences of the table contained in typical sending items. This COBOL-85 required behavior introduces a possible incompatibilty, and performance degradation. It implicitly affects the read...into and return...into statements, as well as the move statement. To avoid problems with variable-length assignments, use the compatible language option or restructure the affected data records. Restrictions Generating Compiler Errors COBOL-85 introduces the following additional restrictions that generate error messages if you compile with the ansi85 or full_ansi85 language option. These restrictions do not apply to programs compiled with the ansi74 or compatible language option.
Relative key data items cannot contain the letters P or p in their picture clauses. Figurative constants cannot be used to define the currency sign ($). Data items that are the subjects of a redefines clause cannot be named as parameters. You cannot specify the all phrase with a literal whose length is greater than 1.
B-13
You cannot specify the into phrase for a file with multiple record descriptions when
either the into data item or one of the record descriptions describes an elementary item that is not alphanumeric.
You cannot specify the no rewind clause in a close reel/unit statement. A pair of file names in a merge statement cannot be specified in the same same area,
same sort area, or same sort-merge area clause.
Also, a pair of file names in the same same record area clause of a merge statement must be associated with a giving phrase.
A write statement cannot contain both the advancing page and at end-of-page
phrases.
A file defined with a linage clause cannot be opened in extend mode. Differences Between the compatible and ansi74 Options
This section describes the differences between the ansi74 option and the compatible option. The ansi74 option causes the compiler to behave identically to the pre-Release 10.0 VOS COBOL compiler, with the addition of the VOS-specific extensions that are listed in New Functionality, earlier in this appendix. The compatible option supports those elements of COBOL-85 that are compatible, with few exceptions, with pre-Release 10.0 VOS COBOL. The differences between compatible and ansi74 are as follows:
the program-id name restriction new reserved words.

Lifted Restriction on program-id Since multiple programs can appear in the same source file, if you compile with the compatible option, the compiler does not require that the program-id name be the same as the object file name. New Reserved Words COBOL-85 introduces a large number of new reserved words. Some of these were reserved as VOS extensions in pre-Release 10.0 VOS COBOL compilers. The others that were added in Release 10.0 are not reserved words in programs compiled with the ansi74 language option. However, if any of these are used in the context of user-defined words when a
B-14
Upgrading Programs from COBOL-74 to COBOL-85
language option other than ansi74 is specified, the compiler issues an error diagnostic. The following list shows the reserved words.
alphabetic-lower alphabetic-upper alphanumeric alphanumeric-edited binary class common end-evaluate evaluate false initialize numeric-edited order packed-decimal purge replace test true

To take advantage of many COBOL-85 features without risking any potential change in the behavior of existing COBOL-74 programs, compile your programs using the compatible language option. This option is the default. However, because of the number of new reserved words, it is possible that existing programs will generate error diagnostics with the compatible option. If this happens, modify the program, replacing identifiers that conflict with reserved words, or compile with the ansi74 language option. Once the program compiles successfully, the program compiled with the compatible option will behave at run time as if it had been compiled using the pre-Release 10.0 compiler. To upgrade to COBOL-85, compile with the ansi85 language option. You need to be aware that there are subtle run-time differences, previously described in this document, which may cause an existing application to behave differently. The use of the call identifier and cancel statements to reference a nested program, and the reinitialization of the ends of perform loops upon the execution of an exit program statement require the use of the full_ansi85 option.
B-15
B-16
Appendix C: Summary of VOS COBOL Commands

This appendix discusses the commands that are specific to VOS COBOL. It provides a brief reference for the cobol, bind, and debug commands, which are described in previous chapters of this manual, as well as in VOS Commands Reference Manual (R098). It also gives a complete description of the format_cobol_source command.
C-
C-1
cobol
cobol
C-
Purpose
The cobol command compiles a VOS COBOL source module.
Display Form
------------------------------------- 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
Arguments
* source_file_name
Required
* -processor processor_string * -language language_string * -level number * -list
The path name of a VOS COBOL source module. <CYCLE> Specifies on which processor the program module is to run. The possible values are mc68000, mc68010, mc68010/arithmetic_processor, mc68020, mc68020/mc68881, mc68030, mc68030/mc68882, and default. <CYCLE> Specifies the subset of ANSI COBOL with which to compile the program. The possible options are ansi74, compatible, ansi85, and full_ansi85. <CYCLE> Displays a message whenever the compiler detects a language element whose level exceeds number. <CYCLE> Creates a compilation listing, which shows all source statements from the source module and include files, as well as a summary of all data definitions and the path names of include files used.
C-2
cobol * -full * -xref
<CYCLE> Creates from the compiled object code an assembly language listing (with added comments) in addition to a compilation listing. <CYCLE> Creates a compilation listing and a cross-reference listing of all data actually referenced in the program. If you choose this argument, you can specify the format of the listing with the -xref_format argument.
* -xref_format * -table
<CYCLE> Specifies the format of the cross-reference listing. The possible values are standard, sorted, and all_sorted. <CYCLE> Creates a symbol table in the object module, for use by the debugger. <CYCLE> Creates a symbol table in the object module, for use by the debugger in a production environment. Only variables actually referenced in the program are placed in the symbol table. <CYCLE> Generates the object code without optimizing it. Optimization produces more compact object code by removing unnecessary or redundant computations. Note: Certain optimization causes code motion; for example, removing invariant computations from loops. Errors are reported against the line numbers to which the code was moved. <CYCLE> Checks for out-of-bounds array subscripts, indexes, and reference modifiers. <CYCLE> Compiles a source module whose textual format differs from the standard COBOL format.
* -production_table * -no_optimize
* -check
* -format
* -mapcase
* -profile
<CYCLE> Causes the compiler to be case insensitive and interpret all uppercase letters as lowercase letters, except those in nonnumeric literals. If you choose the -mapcase argument, and the source module contains an external variable name or entry name, you may not be able to bind the resulting object module. <CYCLE> Inserts code in the compiled program that counts the number of times each source statement is executed when the program runs. You cannot choose both this argument and the -cpu_profile argument. <CYCLE> Inserts code in the compiled program that counts the number of times each source statement executes, the amount of CPU time spent executing each statement, and the number of page faults taken executing each statement when the program runs. You cannot choose both this argument and the -profile argument.
* -cpu_profile
C-3
cobol * -statistics
* -silent
<CYCLE> Displays statistics about the compilation as it proceeds. The compiler displays the elapsed amount of CPU time and real time, the number of page faults taken, and the amount of storage used during each phase. If the compiler produces a listing, it puts the statistics in the listing. <CYCLE> Suppresses the warning messages of severity-1 errors on your terminal during the compilation. The compiler, nevertheless, puts the messages in an error file and in any listing it produces.
* -default_comp number
* -default_sign sign_type * -debugging_mode
<CYCLE> Produces data in the specified comp format where number is an integer from 1 through 6. If you do not use the -default_comp argument to specify a comp format, the compiler selects the most efficient computational type for each variable defined with computational usage that is compatible with the variables picture. <CYCLE> Sets the default sign for a compilation. The possible values are leading_separate, trailing_separate, leading_embedded, and trailing_embedded. <CYCLE> Compiles the program as though the debugging-mode clause were specified in the special-names paragraph. <CYCLE> Specifies how uninitialized working-storage data should be allocated. The possible values are static and auto. <CYCLE> Compiles the source module in a form that identifies the program as a main program, thereby allowing the setting of external switches.
* -default_class class * -main
* -segmentation
<CYCLE> Inserts code in the object module that initializes every independent segment each time control is transferred to it, if required. An independent segment requires initialization if it contains, for example, an alterable go to statement.
Explanation
The cobol command compiles a VOS COBOL source module into an object module. The name of the source module must have the suffix .cobol; you can either supply or omit the suffix when you give source_file_name. The compiler generates an object module, puts it in your current directory, and names it. The name of the object module is source_file_name.obj. The compiler always overwrites an existing object module having the same name as the object module it produces. If you select the -level argument, the type of validation performed depends on the language option you have specified: if you specify ansi74, validation is according to the 1974 Federal Information Processing Standard (FIPS) levels; if you specify compatible, ansi85, or full_ansi85, validation is according to the 1985 ANSI Standard.
C-4
cobol
If you choose the -full, -list, or -xref argument, the compiler creates a compilation listing file and puts it in your current directory. The name of the listing is source_file_name.list. The compiler always overwrites an existing listing file having the same name as the object module it produces. If you select the -table argument, the compiler creates a symbol table, and allocates storage and generates addresses for all external references, including any that are not used. It also generates internal subroutines. These internal subroutines calculate size, offset, and bound expressions that determine the characteristics of adjustable data. This allows the debugger to display and modify variable-length data according to its current length. In addition, the compiler suppresses interstatement code optimization. If you select the -production_table argument, the compiler performs all the same operations, except that it does not suppress interstatement code optimization, and only variables actually referenced in the program are placed in the symbol table (most unreferenced variables are from include files). Code produced with the -table argument executes more slowly than code produced with the -production_table argument. Code produced with the -production_table argument may yield unpredictable results if you invoke the debugger set and continue line requests. When you compile a source module using 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. After compiling with the -mapcase argument, the external variable or entry will be represented by a name with all lowercase letters.
Example
This command compiles the VOS COBOL source module make_report.cobol in the current directory.
cobol make_report -list -xref_format standard -table
Since the -language argument is not specified, the program is compiled with the compatible language option. The compiler creates the object module make_report.obj and puts it in the current directory. A symbol table is produced for debugging. The compiler makes the compilation listing make_report.list, which includes a sorted cross-reference listing, and puts it in the current directory. If the compiler finds any errors, it creates the error file make_report.error, writes error messages to it, puts the file in the current directory, and appends the error file to the compilation listing.
Related Information
See VOS COBOL Language Manual (R010) for a complete description of the VOS COBOL language.
C-5
bind
bind
C-
Purpose
The bind command binds one or more object modules into one executable program module, after the compiler has translated the source module into an object module. You must bind the object module or set of object modules into a program module before you can execute the program.
Display Form
------------------------------------- bind ------------------------------------object_modules: -control: -search: -compact: yes -map: no -retain_all: no -size: small -statistics: no -table: yes
Arguments
* object_modules
* -control control_file_name
One or more path names of object modules to be bound, any of which can be a star name. If you do not use the object_modules argument, you must use the -control argument. (Note that, unlike object modules named in a control file, object_modules are not subject to search path rules; they must be relative or full path names.) Indicates that a binder control file with the path name control_file_name will be used to specify the binding parameters. The name of the binder control file must have the suffix .bind, though you can omit this suffix when you specify the path name. If you do not use the -control argument to specify a binder control file, you must use the object_modules argument. Specifies a directory or directories for the binder to search for object modules named as entry points in the object modules being bound.
* -search search_directories * -no_compact
<CYCLE> Binds the objects without condensing the code in the bound program module. If you do not use the -no_compact argument, the binder replaces long jump instructions with short jump instructions in the bound code wherever possible.
C-6
bind * -map
* -retain_all * -size size
<CYCLE> Creates a bind map, which lists the directories searched, minimum stack size, main entry points, external name definitions, as well as the starting address and length of the code, symbol table, and shared and unshared static storage. <CYCLE> Places all external entry names in an entry map for the program module. This map contains the entry value for each name. If you do not specify the -retain_all argument, the binder does not create an entry map. <CYCLE> Specifies the size of the address space in which the binder is to place the bound program. The options are small, large, 2mb, 8mb, and 64mb. <CYCLE> Displays various statistics about the binding. <CYCLE> Omits symbol table information in the program module. If you choose this argument, you cannot use the debugger in source mode.
* -statistics * -no_table
Explanation
The bind command binds a specified set of object modules into one program module. The object module or modules are specified in the command or in a binder control file. Each object module name must have the suffix .obj, which you can omit when you give the object_modules argument or when you list the object modules in the binder control file. If the programs main entry point (usually the first object module specified) accepts parameters, the binder issues a warning. Thus the binder alerts you if you inadvertently list a subroutine as the main entry point instead of the main program. The binder also warns you if variables have been initialized to different values in different object modules. The binder generates the program module, but you should edit and recompile the source modules containing the incorrect initial value. By default, the binder generates a program module for a 2-megabyte address space. If you choose the large option, the size of the address space is 8 megabytes. There are two cases in which you must bind in an 8-megabyte address space:
if the generated code of all the object modules needs more than 2 megabytes. (The
binder tells you when this occurs.)
if a bound program module fits in the smaller space, but insufficient dynamic storage
space remains. When this is true, the operating system aborts the program when you try to run it and notifies you. In either case, you can rebind the object modules with the large option. There is no difference in how fast a program runs with a 2-megabyte or an 8-megabyte address space.
C-7
Binder Control File
If your program declares as an external variable a name that is identical to a message name in the current message file, and if the program does not assign an initial value to the variable, the binder initializes it to the message code corresponding to the message name. For example, if you declare e$end_of_file as an external 2-byte integer, and if you are using the standard message file, the binder initializes the variable to 1025. Similarly, if you set a nonstandard message file with the use_message_file command, the binder can assign the status code number of a message in that message file to an external variable that has the same name as the status code name of a message in that file. External variables whose names begin with e$, m$, q$, or r$ are shared in a tasking program. The bind command does not have a -mapcase argument; it is case sensitive. If you compile a source module using a -mapcase argument, you may not be able to bind the resulting object module. In particular, if the source module contains an external variable name or entry name, and the name has one or more uppercase letters, the binder will not recognize the original name and its lowercase version as the same name. (References to the original name might appear in a binder control file.) The binder chases links before forming a module name from a file name.
Binder Control File

A binder control file is a text file containing control directives to the binder. If you choose the -control argument, the binder takes its instructions from the file control_file_name. The name of the control file must have the suffix .bind. In the file, you can specify the content and the order of the program modules components.
Syntax, Comments, and Empty Lines

The binder interprets a text line in a binder control file by first parsing the line into words. Words are separated by spaces, colons, semicolons, commas, or apostrophes. You must enclose a name or other identifier in apostrophes if it contains a nonalphabetical or nonnumeric character. For example, you must enclose a path name containing a greater-than or less-than sign in apostrophes.
'%s1#d01>Sales>Jones>sept.obj'
A comment begins with the two-character sequence /* and ends with */. The binder disregards comments. An empty line is not significant. You can use empty lines to increase the readability of the control file.
Directives
Directives specify information that controls the bind process. All the directives are described next. Every directive has a default value or action, given in the descriptions of the directives, which the binder uses when you do not specify that directive. Indicates the end of the binder control file. This directive must be the last one in the file.
* end;
C-8
Directives * entry: identifier;
* modules:module_specifier ...;
Defines the program modules main entry point. The name identifier must be the name of an entry point in one of the object modules being bound. If you do not use the entry directive, the first non-null entry point the binder finds is used as the main entry point for the program module. Declares the object modules to be bound. The specifiers identify the path names of the object modules and how the object modules are to be bound. Specifiers must be separated by commas. The module_specifier has the following form.
(module_term) ...[module_attribute] ...
A module_term is the path name of an object module followed by zero or more module_attribute terms separated by spaces. If you specify a path name, it must be enclosed in apostrophes. Module terms are separated by commas. You can factor common attributes from a series of object module terms and put them outside the parentheses. The path name of module_term can be a relative path name or a full path name. When specifying a module_term, you can include or omit the suffix .obj. The following list shows the allowed values of module_attribute.
compact no_compact table no_table page_aligned
* name:
The module_attribute terms override the corresponding attributes set either by command arguments or by the options directive.
program_name;
* number_of_tasks:
Specifies a name for the bound program module. The program_name can be a file name or a path name. If program_name is a path name, you must enclose it within apostrophes, as in '%s1#d01>Sales>Jones>account'.
number;
Specifies the number of tasks the binder creates in the program module. The number of tasks is limited only by the total available memory on the module. See the description of multitasking in VOS COBOL Transaction Processing Facility (R034) for more information.
* options: option [, option] ...; Specifies some of the bind command-line arguments. The possible values of the options directive are compact, no_compact, table, and no_table. These options
have the same effects as the command arguments described earlier in the Arguments section of the bind command description.
C-9
Directives * retain: entry_name [as new_name] [, entry_name [as new_name]] ...;
* retain;
* search: directory_name [, directory_name] ...; * size:
Specifies the external entry names that the binder places in the program modules entry map. This map contains the entry value for each object module name and alternate entry points specified with entry statements. Specifies the names of directories that the binder searches when looking for object modules.
size_code;
* stack_size:
Specifies the size of the address space in which the binder binds the object modules. The possible values of size_code are small (2 megabyte), large (8 megabyte), 2mb, 8mb, and 64mb. Any of the values 2mb, 8mb, or 64mb must be enclosed in apostrophes. This directive has the same effect as the bind commands -size argument.
stack_size;
* synonym:[synonym_specifier] ...;
Specifies the number of bytes of storage to reserve for the stack. The number of bytes must be an even number that is equal to or greater than 512. If you do not specify a stack size, the binder allocates 32,768 bytes for each task. Specifies an entry name to which one or more names are resolved. Each synonym_specifier is of the form:
old_name[*] for entry_name
All external references matching old_name are resolved to entry_name. The old_name term can have an asterisk as its last character, representing any sequence of zero or more valid identifier characters. Generally, old_name appears in a variable_arg_count directive, and old_name defines a set of declarations with
* variable_arg_count:identifier ...;
different numbers or types of arguments.
* variables:variable_specifier ...;
Indicates that the program (entry point) named identifier can be called with an indefinite number of arguments. Designating the program identifier suppresses the warning message the binder normally displays on your screen when you call a program with the wrong number of arguments. Identifies a set of external static variables declared in the object modules. A specifier tells the binder the name of an external static variable. It can also specify the number of bytes to allocate for the variable and an initial value to assign the variable. The form of a variable_specifier is:
shared name[(size)][initial (initial_value)] unshared [page_aligned]
C-10
Directives
Example
The following binder control file is named make_reports.bind.
name: make_reports; entry: get_report_files; size: small; modules: get_report_files, update_reports_files, process_reports, put_reports; variables: version init ('2.1'); end;
This file binds the object modules get_report_files, update_reports_files, process_reports, and put_reports into the program module make_reports; the main entry point is get_report_files. The program is bound in a small (2 megabyte) address space. The variable version is assigned an initial value of 2.
C-11
debug
debug
C-
Purpose
The debug command invokes the debugger from both command level and break level. There is no display form for the debug command.
Command Line Form

From command level:
debug program
From break level:

debug
Arguments
* program
The name of a command, program module, or saved image. If program is the path name of a program module, you can start the program under the control of the debugger with the start request. If program is a command, you can supply arguments along with the command name.
If program is the path name of a saved executable image (keep module), you must include the suffix .kp.
Explanation
The debug command invokes the debugger. You can invoke the debugger in two ways. From command level, you can invoke the debugger to control program execution or to examine a saved image. The operating system loads the named program module or saved image and puts your process at debugger request level. From break level, you can invoke the debugger by typing debug. Your process goes to debugger request level, where you can issue the requests described in the Source Mode Requests section of this command description and the machine mode requests described in the description of the debug command in VOS Commands Reference Manual (R098). When issuing debugger requests, you can use either commas or spaces to separate arguments. A debugger request line cannot extend over more than one line; the maximum line length is 300 characters. Use semicolons to separate more than one debugger request in a request line.
C-12
Source Mode Debugging
The debugger replaces first token abbreviations in your debugger requests if you enable abbreviation replacement in your process. However, the debugger uses only the first word of the output of the abbreviation directive. You can thus use abbreviations in debugger requests only to abbreviate the names of the debugger requests. See the VOS Commands Users Guide (R089) for detailed information on using abbreviations. While your process is in the debugger, you can issue operating system internal commands as if you were at command level. To issue an internal command from debugger request level, you enter the name of the command preceded by two periods. For example, enter ..list to issue the list command. The set of internal commands may change in subsequent releases of the operating system. To display a list of internal commands, enter the following command.
..help -type internal
Note that you can use abbreviations for internal commands (for example, ..l for ..list).

The source modes of the debugger correspond to the VOS high-level languages VOS COBOL, VOS BASIC, VOS FORTRAN, VOS Pascal, VOS C, and VOS PL/I. You can debug a program written in one of these languages in the corresponding debugger mode. The requests that change the mode of the debugger to the source modes are cobol, basic, fortran, pascal, c, and pl1. The mode determines how the debugger interprets your requests and how it displays information about the program you are debugging. For example, when the debugger displays the data type of a variable, the form is in the language associated with the mode. To debug a program in a source mode, you must have compiled the program with a symbol table. The symbol table contains information about the names of variables and their locations in the compiled program. Use the compilers -table or -production_table argument to incorporate a symbol table into the program module.
Frequently Used Arguments

When you enter the source mode requests (which are described later in this appendix), certain arguments are frequently used as part of the requests. This section describes the following arguments. An unsigned integer constant. One or more debugger requests separated by semicolons and enclosed within parentheses. A source statement line number. It must be the number of a source line on which a statement begins, on which a then clause begins, or on which an else clause begins.
* number
* request_list * line
C-13
* label
Note: Do not use a colon as the terminator for line. In this case, using a colon causes the debugger to interpret the number as a label, not as a line number. Any valid entry point constant or label constant. To distinguish statement labels from line numbers, you must append a colon (:) to a statement label.
* variable The variable argument stands for a variable reference as defined by the language that * expression The expression argument stands for an expression.
corresponds to the debugger mode.
In cobol mode, expression can be a constant, a variable reference, a pointer-qualified variable reference, or a logical expression consisting of the comparison of two expressions. For example, 100, city-code, base >= item, and amount >= 100 are valid cobol mode expressions. The permitted relational operators in cobol mode are the VOS COBOL operators <, <=, =, >=, >, ^<, ^=, and ^>.
Source Mode Requests

From debugger request level, you can enter any of the source mode requests. In addition, you can use the help request to display online information on all the source mode requests or detailed information on one request. The args request displays the values of all the arguments passed to the block of the current environment.
label[:] [(request_list)][-every number] line
* args
* break
* call 'procedure' [using argument ...] The call request calls the program with the entry name procedure, passing it arguments if given. When the mode is cobol, an argument must be a variable
The break request sets a breakpoint and, optionally, allows you to give a list of requests that the debugger executes after stopping for a breakpoint.
reference.
* clear label[:] line -all
* continue
The clear request clears one or more breakpoints. When you omit an argument, the clear request clears the current breakpoint.
label[:] line
C-14
* disassemble
The continue request resumes program execution after the debugger stops for a breakpoint.
label[:] line
* display expression The display request displays the value of expression. The expression must be
The disassemble request displays the instructions generated for the statement specified by label or line or for the current statement if you do not include a label or line value. The debugger displays the instructions in assembly language code.
valid for the mode of the debugger. In general, it can be a computational expression that evaluates to a scalar, or it can be a reference to any of the following types of variables:
* dump variable[number] The dump request displays the value of variable as a hexadecimal number and as an ASCII character string. If you include the number argument, the debugger displays the
a scalar a group a group member an array an array element.
specified number of bytes of data.

* env
procedure stack_frame -frameptr memory_reference -task task_id
* help[request_name] The help request displays online documentation. If you omit request_name, the help request displays the names and uses of all debugger requests. If you supply request_name, help provides information about the particular request.
The env request sets the current environment to the environment you specify. The mode changes to the language of the new environment. The debugger tells you the new mode whenever it changes the mode.
* if expression then (request_list_1) [else (request_list_2)] The if request executes request_list_1 if the expression specified in expression is true. If you include an else clause and the expression is false, the if request executes request_list_2. * keep * list
The keep request creates a keep module (.kp) that you can use later for debugging. The list request displays the following information about all breakpoints:
where you set the breakpoint
C-15
-include * position identifier -no_include
how many times the debugger encountered the breakpoint what debugger requests you issued at the breakpoint.
* quit
The position request resets the current line to the line specified by identifier. Resetting the current line resets the current statement and the current environment. The quit request ends the debugging session, returning your process to command level.
* return * regs
The return request returns your process to break level after you have entered the debugger from break level. The regs request displays the current contents of the processor registers. In addition to the contents of the data and address registers, the regs request displays machine condition information, such as the contents of the user stack pointer and the program counter.
variable * set substring = expression
-include * source[number] -no_include
The set request assigns the value of expression to variable or substring. The expression and the variable (if a variable is specified) must be scalar. Multiple assignments, such as a = b = 0, cannot be used.
* source_path[path_name][-file_number number]
The source request displays one or more lines of source code. When you omit a number argument, the source request displays the current line of source code. When you supply a number argument, it displays the specified number of source lines, starting with the current line. The debugger resets the current line to the last line displayed.
* start
When you move or rename a source module, the debugger is not able to find the source module file because the program modules symbol table indicates the wrong path name. To give the debugger the information it needs to find the source module, you use the source_path request and include the path_name argument and, optionally, the -file_number argument. The start request starts execution of the program specified in a debug command issued from command level.
-in * step[number] -no_in
C-16
Object Mode Debugging
* symbol variable The symbol request displays the declaration information about variable. The
The step request executes one or more program statements. When you omit the number argument, the step request executes the current statement. When you supply the number argument, the debugger executes the specified number of statements, starting at the current statement.
* task_status [task_id] [-long] [-all] The task_status request displays the task ID, terminal port, and state of a specified task. If you specify the -long argument, the debugger also displays the tasks stack * trace[number][-all][-args][-on_units] The trace request displays information about the environments with frames on the stack. If you do not supply any arguments or you omit the number argument, the debugger displays information about the entire stack. If you include a number
declaration information consists of the name of the block in which the variable was declared and the variables base address, data type, and size.
base, stack length, static base, static length, and the CPU time and page-fault count (if they are nonzero).
* where
argument, it displays information about the specified number of block activations, starting with the most recent block activation.
The where request displays information about the current line, the current statement, the current block environment, and the current task (if the program is running in a tasking environment).
Object Mode Debugging

You can debug any program when the debugger is in its object mode. The object mode is also called the machine mode of the debugger. In this mode, you can refer to code and data values by address instead of by name, and you can examine the contents of processor registers. The debugger request to start object mode debugging is machine. If a module in the program you are debugging does not have a symbol table, the debugger resets its mode to machine automatically. To understand machine mode debugging, you must be familiar with the processor and the object module format. Refer to VOS Hardware Reference Manual (R008) for more information about the processor.
C-17
format_cobol_source
format_cobol_source
C-
Purpose
The format_cobol_source command converts a VOS COBOL source text file to either the standard COBOL format or to free format. A source module in free format can be indented into standard COBOL format, and a source module in standard format can be put into free format. You can insert or delete line numbers and map lowercase letters in the body of the program to uppercase letters or vice versa.
Display Form
------------------------------ format_cobol_source -------------------- --------source_file_name: output_file_name: -case: same -format: standard -line_numbers: no -retain_indentation: yes -truncate: yes
Arguments
* source_file_name * output_file_name * -case case
Required
The path name of the VOS COBOL source module. The path name of the file to which the operating system is to write the formatted source module. If you do not specify output_file_name, the operating system overwrites source_file_name. <CYCLE> Converts the case of the source text. The options are as follows: alphanumeric literals to uppercase letters
upper, which converts all program source text except comment lines and lower, which converts all program source text except comment lines and
alphanumeric literals to lowercase letters
same, which does not change the case of any text.

* -format
If you omit this argument, the case of the source text is not changed.
format <CYCLE> Sets the format of the converted source module text. The options are as follows:
C-18
format_cobol_source
standard, which converts a source module in free format to a source module in

standard COBOL format
free, which converts a source module in standard COBOL format to a source module
in free format, removing line numbers if necessary
same, which does not change the format of the source module.
* -line_numbers
If you omit this argument, the operating system uses the default value standard. <CYCLE> Puts line numbers, with an increment of 10, on the source module lines in columns 1 through 6. If you omit this argument, the operating system puts space characters in columns 1 through 6. You can specify this argument only when the source module is already in standard COBOL format or is being converted to standard COBOL format with the -format standard argument. <CYCLE> Does not retain the indentation of each line relative to the preceding line when converting the source file to standard format. If you omit this argument, the operating system retains the indentation of the lines except when it must move a line so that it begins in its proper area. <CYCLE> Does not truncate nonsignificant trailing spaces on source lines. If you omit this argument, trailing spaces in the source file are truncated.
* -no_retain_indentation
* -no_truncate
Explanation
The format_cobol_source command converts a VOS COBOL source text file so that it is either in standard COBOL format or in free format. A source module in free format can be put into standard format, and a source module in standard format can be put into free format. You cannot specify the -format standard argument unless the source is in free format, and you cannot specify the -format free argument unless the source is in standard format. Note: Standard VOS COBOL format implements ANSI COBOL conventions; therefore free format lines that extend into column 72 are diagnosed during the compile. You can insert line numbers in a standard format source module by specifying the -line_numbers argument. You cannot specify the -line_numbers argument when the source module is not in standard format or is not being converted to standard format. You can specify the -case argument to convert the case of the text in the source module to uppercase or lowercase. The operating system does not change the case of comments or alphanumeric literals.
C-19
format_cobol_source
Examples
The following sample program, convert.cobol, is in free format.
identification division. program-id. convert. data division. 01 degrees_c comp-5. 01 degrees_f comp-2. 01 out_value pic zz9v9. procedure division. display 'Enter a temperature in Celsius: '. accept value of degrees_c. call 'convert_c_to_f' using degrees_c degrees_f. move degrees_f to out_value. display value of degrees_c 'c' ' = ' out_value 'f'. exit program.
After executing the command format_cobol_source convert -line_numbers, the source file appears in the following format.
000010 000020 000030 000040 000050 000060 000070 000080 000090 000100 000110 000120 000130 000140 000150 identification division. program-id. convert. data division. 01 degrees_c comp-5. 01 degrees_f comp-2. 01 out_value pic zz9v9. procedure division. display 'Enter a temperature in Celsius: '. accept value of degrees_c. call 'convert_c_to_f' using degrees_c degrees_f. move degrees_f to out_value. display value of degrees_c 'c' ' = ' out_value 'f'. exit program.
C-20
Glossary
77-level description entry A data description entry that describes a noncontiguous data item with the level number 77. access mode The manner in which records are retrieved and stored in a file. The three COBOL access modes are sequential access, random access, and dynamic access. actual decimal point The physical representation of the decimal point position in a picture clause or literal data item. A period (.) or comma (,) indicates the decimal point. See also assumed decimal point. alphabet name A user-defined word that assigns a name to a specific character set and/or collating sequence in the special-names paragraph of the Environment Division. alphabetic character Any of the uppercase letters A..Z, the lowercase letters a..z, or the space character. alphanumeric character Any character in the ASCII character set. alphanumeric expression An identifier, a function that returns an alphanumeric value, an alphanumeric literal, or an alphanumeric expression enclosed in parentheses. The identifiers appearing in an alphanumeric expression must represent alphanumeric, alphabetic, or alphanumeric-edited items, or group items containing only display data. alphanumeric item A data item whose description permits its contents to be composed of any combination of characters. Certain categories of alphanumeric items may be formed from more restricted character sets. alphanumeric literal A character string composed of up to 256 characters enclosed in quotation marks or apostrophes. The string of characters may include any character. A single quotation
Glossary-
Glossary-1
Glossary
mark or apostrophe within an alphanumeric literal (when the literal is delimited by quotation marks or apostrophes, respectively) is represented by two contiguous quotation marks or apostrophes, respectively. alternate record key In COBOL, a key, other than the prime record key, whose contents identify a record within an indexed file. See also prime record key. argument An identifier, literal, or expression occurring in the list associated with a function identifier, or in the using phrase of a call statement. The value of the argument is used by the function being referenced or the program being called. arithmetic expression See numeric expression. arithmetic operation The process caused by the execution of an arithmetic statement, or the evaluation of an arithmetic expression, that results in a mathematically correct solution to the arguments presented. arithmetic statement A statement that causes an arithmetic operation to be executed. The arithmetic statements are add, compute, divide, multiply, and subtract. array See table. ascending key A key whose values are used to order data, starting with the keys lowest value, and ending with the keys highest value, in accordance with the rules for comparing data items. See also descending key. assumed decimal point A decimal point position that has a logical meaning, but no physical representation. The picture character v represents an assumed decimal point. See also actual decimal point. attach To associate a port with a file or device, creating the port, if necessary, and generating a port ID. The port ID can then be used to refer to the file or device. automatic data Data that is dynamically allocated when the program is called, and freed when the program returns to its caller. Automatic data loses its current value whenever the program executes an exit program statement.
Glossary-2
Glossary
based data Data that is not allocated storage. Based data must not appear in the using phrase of the Procedure Division header or entry header. bind To combine a set of one or more independently compiled object modules into a program module. Binding compacts the code and resolves symbolic references to external programs and variables that are shared by object modules in the set and in the object library. binder A program that combines a set of independently compiled object modules into a program module. The binder is called with the bind command. binder control file A text file that directs the binders actions. block The system disk block (sector) size is fixed at 4096 bytes. Disk I/O does not equate specified logical record size with physical record size; therefore, COBOL programs can read or write records regardless of block boundaries. The operating system calculates tape block size as equal to the largest record size specified in the program, or with the set_tape_defaults command. Boolean literal A literal composed of up to 256 characters enclosed in apostrophes or quotation marks, and immediately preceded by either an uppercase or lowercase b. The characters allowed in a Boolean literal are 0 and 1. called program A program that executes under the control of a call statement. calling program A program containing a call statement in its Procedure Division. character string A character or sequence of contiguous characters that forms a COBOL word, a literal, a picture character string, or a comment entry. class condition The proposition, for which a truth value can be determined, that the content of an item is wholly alphabetic or is wholly numeric or consists exclusively of those characters listed in the definition of a class name.
Glossary-3
Glossary
class name A user-defined word defined in the special-names paragraph of the Environment Division that assigns a name to the proposition, for which a truth value can be defined, that the content of a data item consists exclusively of those characters listed in the definition of a class name. clause An ordered set of consecutive COBOL character strings whose purpose is to specify an attribute of an entry. collating sequence The sequence in which characters are ordered for purposes of sorting, merging, or comparing. compile time The time at which the COBOL compiler is invoked to translate a source program into an object program. compiler A program that translates a source module (source code) into machine code. The generated machine code is stored in an object module. compiler-directing statement The copy, replace, and use statements, and the % replace, % page, % list, and % nolist compiler directives are not directly compiled, but cause the compiler to perform specific actions. compiler directive See compiler-directing statement. conditional expression A simple condition or a complex condition specified in an if, perform, evaluate, or search statement. conventional reference format A format that provides a standard method for describing COBOL source programs in terms of the traditional 80-column character positions on a source line. currency sign The character $ of the COBOL character set. currency symbol The character defined by the currency sign clause in the special-names paragraph of the Environment Division; otherwise, the currency symbol is the character $.
Glossary-4
Glossary
current directory A directory currently associated with the process. The operating system uses the current directory as the default directory when searching for an object and no other directory has been specifically named. For example, if a relative path name is supplied in a command, the operating system uses the current directory as the reference point from which to locate the object in the directory hierarchy. When a user first logs in, the current directory is set to the home directory. The current directory can be changed with the change_current_dir command or the s$change_current_dir subroutine. data item A unit of data (excluding literals) defined by the program or by the rules of an intrinsic function. data name A user-defined word of up to 30 characters that names a Data Division item. default value The value that the operating system uses if a specific value is not supplied. descending key A key whose values are used to order data, starting with the keys highest value and ending with the keys lowest value, in accordance with the rules for comparing data items. See also ascending key. detach To dissociate a port from a file or device. directory A segment of disk storage containing files, links, and subdirectories and having its own access limitations. dynamic access An access mode in which specific logical records can be read or written to an indexed or relative file in a nonsequential manner, and read from the file sequentially during a single open statement. elementary item A data item described in the Data Division as having no logical subdivisions. Any set of consecutive clauses terminated by a period that appears in the Identification, Environment, or Data Division of a COBOL program.
Glossary-5
Glossary
entry point A location in a program where execution can begin when the program is activated. An entry point can be the target of a call statement, and it can be specified in a binder control file. entry variable A variable that can be used in a program to hold the value of an entry point. error code A value indicating an error condition that is made available to a program during the execution of an I/O statement and prior to the execution of an imperative statement associated with that I/O statement, or prior to the execution of any exception declarative. The value is placed into a data item specified in the error code clause of the select clause, when that clause is specified for a given file. execution time The time at which an object program is executed. expression An alphanumeric, numeric, or conditional expression. extend mode The state of a file after the execution of an open statement, with the extend phrase specified, and before the execution of a close statement without the reel or unit phrase specified. external data Data to be shared among separately compiled COBOL programs, when each of the programs defines the data item with an identical data name using the external clause in the data description entry. External data can be shared with programs written in other languages that support external data and that allow data types that are compatible with those used in COBOL. external data item A data item described as part of an external record in one or more programs of a run unit that may be referenced from any program in which it is described. external data record A logical record, described in one or more programs of a run unit, whose constituent data items may be referenced from any program in which they are described. external file A file to be shared among separately compiled COBOL programs, when each of the programs defines the file with an identical file name using the external clause in the file description entry. All attributes of the file description for the file must be identical, except for the names used in the record description entries.
Glossary-6
Glossary
external switch A software device used to indicate that one of two alternate states exists. file A collection of logical records. file name The name by which a file is known to a COBOL program. A file name is related to a port name in the select clause of the Environment Division. file organization The permanent logical file structure established when a file is created. file status Codes returned by the system to indicate that the I/O operation executed successfully or that an error condition occurred. The file status clause of the select clause allows the user to check the status of I/O operations. fixed file attributes Information about a file that is established when a file is created and cannot subsequently be changed during the existence of the file. These attributes include the organization of the file (sequential, relative, or indexed), the prime record key, the alternate record keys, the code set, the minimum and maximum record size, the record type (fixed or variable), the collating sequence of the keys for indexed files, the blocking factor, the padding character, and the record delimiter. fixed-length record A record associated with a file whose file description or sort-merge description entry requires that all records contain the same number of character positions. See also variable-length record. free format A format that suspends the conventional format rules for entering source text. function 1. A routine that is invoked to determine a value at the time the function is referenced during a statements execution. 2. A compiler-recognized name that returns a value based on a predefined algorithm. function identifier A syntactically correct combination of character strings and delimiters that uniquely identifies a function. Arguments are additionally specified, as required, to determine the value that the function returns. A function identifier may be specified anywhere in the general formats that an identifier or literal of the same type may be specified, subject to certain restrictions.
Glossary-7
Glossary
global name A name that is declared in only one program but that may be referenced from that program and from any program contained within that program. Condition names, data names, file names, record names, and some special registers can be global names. group item A data item with logical and/or physical subdivisions that can be manipulated as a single unit. hexadecimal literal A literal composed of up to 256 characters enclosed by apostrophes or quotation marks and immediately preceded by either an uppercase or lowercase h. The characters allowed in a hexadecimal literal are the digits 0..9 and the uppercase or lowercase letters a..f. identifier A syntactically correct combination of character strings and delimiters that names a data item. When referencing a data item that is not a function, an identifier consists of a data name with its qualifiers, subscripts, and reference modifiers, as required for uniqueness of reference. When referencing a function, a function identifier is used. The rules for an identifier associated with a general format may specifically prohibit reference to functions, qualification, subscripting, or reference modification. implicit locking A VOS locking mode in which the operating system does not lock the file or record for either reading or writing when it opens the file, but instead locks it for the appropriate access mode each time a process performs an I/O operation on the file or record. index Indicates the position of a data item in a table. index name A user-defined name that associates an index with a particular table. indexed file A file with the organization is indexed clause in its select clause. An indexed file may be accessed randomly by a record key. indexed organization The logical file structure in which each record is identified by the value of one or more keys within that record. initial state The state of a program when it is first called in a run unit.
Glossary-8
Glossary
input file A file opened in the input mode. input mode The state of a file after the execution of an open statement, with the input phrase specified, and before the execution of a close statement without the reel or unit phrase specified. input procedure In COBOL, a set of statements that executes during the execution of the sort statement. An input procedure releases records to the sort file. integer A numeric literal or data item that does not include any character positions to the right of the assumed decimal point. Where the term integer appears in the general formats, the referenced integer must be a numeric literal and must not be signed or zero unless explicitly allowed by the rules for that format. internal data The data described in a program excluding all external data items and external file connectors. Items described in the Linkage Section are treated as internal data. internal data item A data item that is described in one program in a run unit. An internal data item may have a global name. invalid key condition The condition returned during an I/O operation on an indexed or relative file, when a specified record key is either duplicated or not found. I/O mode The state of a file after the execution of an open statement, with the i-o phrase specified, and before the execution of a close statement. I/O statement A statement that causes files to be processed by performing operations upon individual records or upon the file as a unit. The I/O statements are: accept (with the identifier phrase), close, delete, display, open, read, rewrite, set (with the to on or to off phrase), start, and write. I/O status See file status.
Glossary-9
Glossary
key A data item that identifies a record, or whose contents determine the ordering of records in a file. See also alternate record key, ascending key, descending key, key of reference, prime record key, and relative key. key of reference In COBOL, the key, either primary or alternate, currently used to access records in a file. key word A reserved word whose presence is required when the format in which the word appears is used in the source program. label variable A variable that can hold the value of a procedure name (such as a section or paragraph). letter One of the uppercase letters A..Z or one of the lowercase letters a..z. library name A user-defined word identifying a directory name that contains files that may be copied into a given source program at compile time. literal A character string whose value is implied by the ordered set of characters comprising the string. See also alphanumeric literal, Boolean literal, hexadecimal literal, and numeric literal. lock A system data structure associated with a file, file record, or device that can be set to restrict the use of the object; the restriction remains in effect until the lock is released. logical operator One of the reserved words and (&), or (|), exor, or not (^). The words and, or, and exor can be used as logical connectives in the formation of a condition. The word not is used for logical negation. logical record See record. mnemonic name A user-defined word assigned to an external switch or other system name. These associations are established in the special-names paragraph of the Environment Division.
Glossary-10
Glossary
nonnumeric item A data item whose description permits its content to be composed of any combination of characters taken from the computers character set. Certain categories of nonnumeric items may be formed from more restricted character sets. nonnumeric literal A literal bounded by quotation marks. The string of characters may include any character in the computers character set. numeric character One of the ten digits 0..9. numeric expression An identifier for: a numeric or numeric-edited elementary item; a numeric literal; an intrinsic function that returns a numeric value; a user-defined function; two numeric expressions separated by an arithmetic operator; or a numeric expression enclosed in parentheses. Any numeric expression may be preceded by a unary operator. A numeric expression is also referred to as an arithmetic expression. numeric item An item that consists of the digits 0..9 and an optional operational sign. numeric literal A quantity that is data rather than a reference to a data item; also, a string of characters consisting of the digits 0..9, a decimal point, and/or an algebraic sign. The decimal point cannot be the rightmost character of a numeric literal. An algebraic sign, if used, must be the leftmost character. object In the VOS operating system, any data structure or device that you can refer to by name or by some other identifier. For example, all of the following are objects: directories, files, links, systems, modules, devices, groups, persons, ports, queues, locks, file indexes, and file records. object module A file produced by a compiler, containing the machine code version of one or more procedures. This file usually contains symbolic references to external variables and programs. An object module must be processed by the binder to produce a program module, and then must be loaded by the loader. obsolete element A COBOL language element in ANSI Standard COBOL that is to be deleted from the next revision of the ANSI COBOL standard.
Glossary-11
Glossary
open mode The state of a file after the execution of an open statement and before the execution of a close statement. The particular open mode is specified in the open statement by either the input, output, i-o, or extend phrase. operand Any word used in a statement, condition, or computation that references data in such a way that the referenced value is operated upon. operational sign A plus (+) or minus (-) sign associated with a data item, indicating that the items value is positive or negative. optional file A file that is declared as being not necessarily present each time the object program is executed. The object program causes an interrogation for the presence or absence of the file. organization See indexed organization, relative organization, and sequential organization. output file A file opened in either the output or extend mode. output mode The state of a file after the execution of an open statement, with the output or extend phrase specified, and before the execution of a close statement without the reel or unit phrase specified. output procedure A set of statements to which control is given during the execution of a sort statement after the sort function is completed, or during the execution of a merge statement after the merge function has selected the next record in merged order. Normally, an output procedure returns records from a sort or merge file. See also input procedure. path name A unique name that identifies a device or locates an object in the directory hierarchy. phrase An ordered set of one or more consecutive COBOL character strings that form a portion of either a COBOL procedural statement or a COBOL clause. pointer An elementary data item defined with the usage is pointer clause and used to reference a based data item.
Glossary-12
Glossary
port A data structure, identified by a name or ID, attached to a file or device for the purpose of accessing the file or device. When an executing program refers to a file or device, the operating system uses the port having the same name or ID. A port is created when it is attached, and it is eliminated when it is detached. port attachment See attach. port detachment See detach. port name The name by which the operating system identifies a file. Port names are related to an internal file name in the select clause of the Environment Division. prime record key In COBOL, a key whose contents uniquely identify a record within an indexed file. See also alternate record key. privileged process A process that allows a user who is logged in with the privileged attribute to use certain commands, requests, and subroutines. You can be privileged or not depending on your status as defined in the registration databases and on how you logged in. procedure A paragraph or group of logically successive paragraphs, or a section or group of logically successive sections, within the Procedure Division. procedure branching statement A statement that causes the explicit transfer of control to a statement other than the next executable statement in the sequence in which the statements are written in the source program. The procedure branching statements are: alter, call, exit, exit program, go to, merge (with the output procedure phrase specified), perform, and sort (with the input procedure or output procedure phrase specified). procedure name A user-defined word used to name a paragraph or section in the Procedure Division. It consists of a paragraph name (possibly qualified) or a section name. program module A file containing an executable form of a program. The program module consists of one or more object modules (compiled source programs) bound together. The program module always has the suffix .pm.
Glossary-13
Glossary
program name In the Identification Division and the end program header, a user-defined word that identifies a COBOL source program. random access An access mode in which the program-specified value of a key identifies the logical record that is obtained from, deleted from, or placed into a relative or indexed file. record The most inclusive data item. The level number for a record is 01. A record may be either an elementary item or a group item. record key A key whose contents identify a record within an indexed file. Within an indexed file, a record key is either the prime record key or an alternate record key. record name A user-defined name that identifies a particular record described in the File Section of the Data Division. record number The ordinal number of a record in the file whose organization is sequential. recursive program A program that calls itself either directly or indirectly. You specify that a program is recursive in the program-id paragraph of the Identification Division. relative file A file with an organization is relative clause in its select clause. Records in this type of file are keyed in ascending order relative to the first record in the file. A relative file may be accessed sequentially, randomly, or dynamically. relative indexing An index name followed by a plus or minus operator, followed by an unsigned integer, delimited by a balanced pair of parentheses, and used as a subscript. relative key A key whose contents identify a logical record in a relative file. The key must be numeric. relative organization The logical file structure in which each record is uniquely identified by an integer value, greater than zero, that specifies the records ordinal position in the file.
Glossary-14
Glossary
relative record number The ordinal number of a record in a file whose organization is relative. This number is treated as a numeric literal that is an integer. reserved word A word that has special meaning for the COBOL compiler and therefore cannot be used as a user-defined identifier. run unit One or more object programs that execute as a unit to provide problem solutions. secondary entry An entry point defined in the Procedure Division by the entry header. sentence A sequence of one or more statements, the last of which is terminated by a period. separately compiled program A program that, together with its contained programs, is compiled separately from all other programs. sequential access An access mode in which logical records are stored in or retrieved from a file in a predecessor-to-successor sequence determined by the order of the records in the file. sequential file A file with an organization is sequential clause in its select clause. Records in this type of file may be accessed according to the order in which they were created. Keys cannot be used. sequential organization The logical file structure in which a record is identified by a predecessor-successor relationship established when the record is stored in the file. star name A name that contains one or more asterisks or consists solely of an asterisk. A star name can be used to specify a set of objects. Star names function in the following manner.
An asterisk can be in any position in a star name. In a path name, a star name can be in the final name position only. When the operating system matches nonstar names to a star name, each asterisk
represents zero or more characters.
A name cannot contain consecutive asterisks; there must always be an

intervening character.
Glossary-15
Glossary
statement A syntactically valid combination of words, literals, and separators, beginning with a verb, written in a COBOL source program. static data Data that exists throughout the execution of a run unit, always retaining the last value assigned to it. subscript An integer value that identifies a particular element of a table. A subscript is represented by a numeric expression that yields an integer value or a value that is truncated to an integer value. subscripted data name An identifier composed of a data name followed by one or more subscripts enclosed in parentheses. switch status A user-defined name in the special-names paragraph of the Environment Division that tests the status of an external switch. When an external switch is on, the associated on condition name is true and the off condition name is false. switch-status condition The proposition, for which a truth value can be determined, that an on or off switch has been set to a specific status. symbol table The part of a program module containing data used for debugging the program. The symbol table allows the debugger to convert names of variables given by the user to locations of data or instructions. system name A COBOL word used to communicate with the operating environment. table A set of logically consecutive data items defined in the Data Division by means of the occurs clause. Other languages use the term array. table element One of the set of data items comprising a table. unsuccessful execution The attempted execution of a statement that does not result in the execution of all of the operations specified by that statement. The unsuccessful execution of a statement does not affect any data referenced by that statement, but may affect status indicators.
Glossary-16
Glossary
user-defined word A COBOL word supplied by the user to satisfy the format of a clause or statement. variable A data item whose value may be changed by the execution of the program. A variable used in a numeric expression must be a numeric or a numeric-edited elementary item. variable-length record A record associated with a file whose file description or sort-merge description entry permits records to contain a varying number of character positions. See also fixed-length record. variable-occurrence data item A table element that is repeated a variable number of times. Such an item must contain an occurs depending on clause in its data description entry, or be subordinate to such an item. Virtual Operating System (VOS) An operating system on Stratus modules. word A character string of up to 30 characters that forms a user-defined word, a system name, or a reserved word.
Glossary-17
Glossary
Glossary-18
Index
A
Abbreviating debugger requests, 4-28, C-13 Access modes, 5-2, 5-5, 5-12 indexed, 5-6 random, 5-4 sequential, 5-2 Allocation auto, 2-19, C-4 data map, C-3 of address space, 3-7, 3-13 of uninitialized data, 2-19, C-4 static, 2-19, C-4 ansi74 language option, 2-15, C-2 ansi85 language option, 2-15, C-2 Apostrophes ()', 3-9, C-8 Append I/O type, 5-12 args debugger request, 4-21, C-14 Arrays FORTRAN, 6-13 ASCII character set, 7-1 Assembly listings, C-3 Asterisk (*), 4-13 attach_port command, 5-9 Attributes, 3-10 compact, 3-10, C-9 no_compact, 3-10, C-9 no_table, 3-10, C-9 page_aligned, 3-10 table, 3-10, C-9 auto allocation, 2-19 Automatic storage, 2-19, C-4
Index-
B
BASIC data types, 6-15 passing parameters in, 6-15 subprograms, 6-15 Bind errors, 3-4 files, 3-9 maps, 3-4 statistics, 3-8
bind command, 1-4, 3-1, C-6 display form, 3-1 .bind suffix, 3-9, C-8 Binder arguments, 3-1 -control, 3-9 -map, 3-4 -search, 3-2, 3-3 -size, 3-6 -statistics, 3-8 Binder control files, 3-9, C-6, C-8 end directive, 3-10, C-8 entry directive, 3-11, C-9 modules directive, 3-9, C-9 name directive, 3-11, C-9 number_of_tasks directive, 3-12, C-9 options directive, 3-14, C-9 path names in, C-8 retain directive, 3-12, C-10 search directive, 3-12, C-10 size directive, 3-14, C-10 spacing in, 3-9, C-8, C-9 stack_size directive, 3-12, C-10 synonym directive, C-10 variable_arg_count directive, C-10 variables directive, 3-12, C-10 Binder directives end, 3-10, C-8 entry, 3-11, C-9 modules, 3-9, C-9 name, 3-11, C-9 number_of_tasks, 3-12, C-9 options, 3-14, C-9 retain, 3-12, C-10 search, 3-12, C-10 size, 3-14, C-10 stack_size, 3-12, C-10 synonym, C-10 variable_arg_count, C-10 variables, 3-12, C-10 Binder statistics, C-7 Binding, 3-1, C-6 a program, 1-4 attributes and, 3-10, C-9
Index-1
Index external static variables and, 3-12 generating a bind map, 3-4 initializing variables and, 3-13 multitasking and, 3-12 object modules, 3-2, C-9 shared variables and, 3-13 statistics, 3-8 tasking and, 3-12, 3-13 Blocks, 4-5, 4-10 break debugger request, 4-12, C-14 Break level, 4-7 Break level requests, 4-7 continue, 4-7 debug, 4-4 keep, 4-7 login, 4-7 re-enter, 4-7 stop, 4-7 Breakpoints, 4-12, C-14 Characters control, 7-3 graphic, 7-3 storage of, 7-2 -check compiler argument, 2-10, C-3 Choosing a processor, 2-18 clear debugger request, 4-17, C-14 close statement, 5-19 COBOL passing arguments, 6-5 with dope phrase, 6-8 cobol command, 1-3, 2-1, C-2 display form, 2-2, C-2 cobol debugger mode, 4-13 .cobol suffix, 1-3, C-4 Code compaction, 2-21 collate function, 7-6 Commands attach_port, 5-9 bind, 3-1 cobol, 2-1 debug, 4-3, C-12 detach_port, 5-9 format_cobol_source, C-18 in debugger, 4-28 internal, 4-28 profile, 2-13 set_tape_defaults, 5-18 tape_format, 5-17 use_abbreviations, 4-28 Common strings, 7-4 comp data, 2-18 compact module attribute, 3-10, C-9 compatible language option, 2-15, C-2 Compilation debugging and, C-13 Compilation listings, 2-3, C-2 assembly language, 2-8 cross-reference, 2-6, C-3 Compiler case sensitivity, 2-19 errors, 2-9 statistics, 2-12, C-4 Compiler arguments -check, 2-10, C-3 -cpu_profile, 2-13, C-3 -debugging_mode, C-4 -default_class, 2-19, C-4 -default_comp, 2-18, C-4 -default_sign, 2-19, C-4 -format, 2-20, C-3 -full, 2-8, C-3 -language, 2-15, B-2, C-2 -level, B-2, B-3, B-4, C-2
C
C language data types, 6-12 functions, 6-11 functions that return a value, 6-12 null pointer in, 6-13 passing parameters in, 6-11 pointers, 6-12 subroutines, 6-11 void functions, 6-11 call debugger request, 4-21, C-14 Calling procedures, 4-21 Canonical strings, 7-4 Case sensitivity, 2-19, C-3 Character set IDs, 7-7 Character sets ASCII, 7-1, 7-2 canonical strings and, 7-4 character set IDs and, 7-7 common strings and, 7-4 default, 7-5 hangul, 7-1 kanji, 7-1 katakana, 7-1 Latin alphabet No. 1, 7-1 right graphic, 7-3 ROC Chinese, 7-1 shift function and, 7-4 simplified Chinese, 7-1 supplementary, 7-1 unshift function and, 7-4 user-defined double-byte, 7-1
Index-2
Index -list, 2-2, C-2 -main, 2-21, B-3, C-4 -mapcase, 2-19, B-2, C-3 -no_optimize, 2-21 -optimize, C-3 -processor, 2-18, C-2 -production_table, 2-11, 4-3, C-3 -profile, 2-13, C-3 -segmentation, 2-21, B-2, C-4 -silent, 2-10, C-4 -statistics, 2-12, C-4 -table, 2-11, 4-3, C-3 -xref, 2-6, C-3 -xref_format, 2-6, C-3 Compiler diagnostics, 2-9 severity 1, 2-9 severity 2, 2-9 severity 3, 2-9 severity 4, 2-10 Compilers cobol, C-2 Compiling programs, 1-3 Computational types, C-4 continue break level request, 4-7 continue debugger request, 4-14, C-15 -control binder argument, 3-9 Control characters, 7-3 Control files, C-6 binder, C-8 -cpu_profile compiler argument, 2-13, C-3 Creating program modules, 1-4 Cross-reference listings, 2-6, C-3 keyCTRL keyBREAK, 4-7 keyCTRLkeyBREAK, 1-5 Current block environment, C-13 environment, 4-5, C-13 issuing internal commands in, 4-28 setting breakpoints in, 4-12 Debugger modes cobol, 4-11, 4-13, C-14 machine, 4-24, C-17 object, 4-24, C-17 Debugger request arguments expression, C-14 label, C-14 line, C-14 memory_reference, C-15 number, C-13 request_list, C-13, C-15 variable, C-14 Debugger request arguments -include, C-16 -no_include, C-16 Debugger requests, C-14 args, 4-21, C-14 break, 4-12, C-14 call, 4-21, C-14 clear, 4-17, C-14 continue, 4-14, C-15 disassemble, 4-25, C-15 display, 4-13, C-15 dump, 4-27, C-15 env, 4-10, 4-24, C-15 help, 4-6, C-15 if, C-15 if-then, 4-15 keep, C-15 list, 4-17, C-16 machine, C-17 position, 4-8, C-16 quit, 4-6, C-16 regs, 4-25, C-16 return, C-16 set, 4-14, C-16 source, 4-7, 4-23, C-16 source_path, 4-23 start, 4-9, C-16 step, 4-17 symbol, 4-13, C-17 task_status, 4-23 trace, 4-9, C-17 where, 4-11, C-17 Debugging, C-12 300-character line limit, 4-5 abbreviating requests, 4-28 arguments used for, C-13 batch mode, 4-4 blocks in, 4-10 calling a procedure, 4-21 cobol mode, 4-3, 4-11
D
Data allocation map, C-3 uninitialized allocation, 2-19, C-4 debug break level request, 4-7 debug command, 4-3, C-12 Debugger, 4-1 environment, 4-10 evaluating built-in functions in, 4-13 evaluating predefined functions in, 4-13 exiting, 4-6 invoking, 4-3 invoking from break level, 4-4 invoking on a keep module, 4-4
Index-3
Index compiling for, 4-3 current block environment, C-13 debugger request level, C-12 displaying a variablesvalue', 4-13 displaying an expressionsvalue', 4-13 examining registers, 4-25 include files, 4-8 internal commands and, C-13 interrupting, 4-7 issuing conditional requests, 4-15 keep modules, 4-4 machine mode, C-17 object mode, C-17 programs, 4-3 registers and, C-16 request lists in, 4-15 setting a variablesvalue', 4-14 setting breakpoints, 4-12 setting the current line, 4-24 shortcuts for, 4-27 source mode, C-13 stacks in, 4-9 symbol table for, 2-11, 4-3, C-3 tables, 4-13 -debugging_mode compiler argument, C-4 Default character set, 7-5 -default_class compiler argument, 2-19, C-4 -default_comp compiler argument, 2-18, C-4 -default_sign compiler argument, 2-19, C-4 Delimiters, C-8 detach_port command, 5-9 Diagnostics compiler, 2-9 severity 1, 2-9 severity 2, 2-9 severity 3, 2-9 severity 4, 2-10 Directives in a binder control file, 3-9 disassemble debugger request, 4-25, C-15 display debugger request, 4-13, C-15 Displaying a tablesvalue', 4-13 Displaying a variablesvalueinthedebugger', 4-13 Displaying an expressionsvalueinthedebugger', 4-13 dump debugger request, 4-27, C-15
E
Embedded-key index, 5-6 end binder directive, 3-10, C-8 entry binder directive, 3-11, C-9 env debugger request, 4-10, 4-24, C-15 Error checking, 2-10 for out-of-bounds table subscripts, 2-11 for out-of-range assignments, 2-10 Error code, 5-7 Error files, 2-9 Error handling, 4-7, 5-8 at end or invalid key phrase, 5-6, 5-8 on size error phrase, 5-8 Error messages, 2-9 in debugger, 4-10 run-time, 2-10, 3-7 Error messages from compiler, 2-9 out-of-bounds table subscripts, 2-10 severity levels, 2-9 .error suffix, 1-3, 2-9 Examples args debugger request, 4-21 disassemble debugger request, 4-25 displaying source code in the debugger, 4-8 dump debugger request, 4-27 getting online help in the debugger, 4-6 if-then debugger request, 4-16 regs debugger request, 4-26 step debugger request, 4-18 symbol debugger request, 4-14 tracing a stack in the debugger, 4-11 where debugger request, 4-11 Executing a program, 1-4 Expanding abbreviations in debugger requests, C-13 expression debugger request argument, C-14 Expressions, 4-13 in the debugger, 4-13 Extend mode, 5-12 extend option open statement, 5-18 External references, 3-3 External variables, C-8 messages, C-8 static, 3-13, C-10
Index-4
Index
F
File organization, 5-2, 5-13 fixed, 5-4 relative, 5-4 sequential, 5-2 stream, 5-3 File status, 5-7 Files as VOS I/O system objects, 5-1 FIPS level, C-2 Fixed file organization, 5-2 -format compiler argument, 2-20, C-3 format_cobol_source command, C-18 FORTRAN arrays, 6-13 data types, 6-14 functions, 6-14 passing parameters in, 6-13 subroutines, 6-13 -full compiler argument, 2-8, C-3 full_ansi85 language option, 2-15, C-2
Include files, 4-8 Indexed access mode, 5-6 Indexes embedded-key, 5-6 item, 5-6 separate-key, 5-6 Input I/O type, 5-12 Input mode, 5-12 input option open statement, 5-18 input-output section i-o control paragraph, 5-18 Internal commands from debugger request level, 4-28, C-13 Interrupting program execution, 1-5 i-o control paragraph input-output section, 5-18 Item index, 5-6
K
Kanji character set, 7-1 Katakana character set, 7-1 keep break level request, 4-7 keep debugger request, C-15 Keep module, 4-4, C-12, C-15 .kp suffix, 4-4, C-12, C-15
G
Generating a bind map, 3-4 Getting help in the debugger, 4-6 Getting information about binding, 3-8 about compilation statistics, 2-12 about debugging, 4-6 about program performance, 2-13 about registers, 4-25 about tasks, 4-23 Graphic characters, 7-3 Group identifiers, C-3
L
label debugger request argument, C-14 label records clause, 5-18 -language compiler argument, 2-15, C-2 Language options ansi74, 2-15, B-2, C-2 ansi85, 2-15, B-2, C-2 compatible, 2-15, B-2, C-2 full_ansi85, 2-15, B-2, C-2 Latin alphabet No. 1, 7-1 -level compiler argument, B-2, B-3, B-4, C-2 Level-1 group identifiers, C-3 Libraries default directories, C-6 object, 3-1, 3-3 searching, 3-3 linage clause, 5-20 line debugger request argument, C-14 -list compiler argument, 2-2, 2-3, C-2 list debugger request, 4-17, C-16 .list suffix, 1-3, C-5 Listings, 2-2 assembly language, 2-8, C-3 compilation, 2-2, C-2
H
Hangul character set, 7-1 help debugger request, 4-6, C-15
I
I/O ports, 5-8 system objects, 5-1 types, 5-12 append, 5-12 input, 5-12 output, 5-12 update, 5-12 I/O (i-o) mode, 5-13 if debugger request, C-15 if-then debugger request, 4-15 -include debugger request argument, C-16
Index-5
Index cross-reference, 2-6, C-3 error messages in, 2-5, 2-11 object, C-5 source, 2-2, C-5 statistics in, 2-12 locking file and record, 5-10 Locking-shift characters, 7-3 login break level request, 4-7 Lowercase characters, 2-19 Lowercase letters, C-3 -no_include debugger request argument, C-16 -no_optimize compiler argument, 2-21 no_compact module attribute, 3-10, C-9 -no_include debugger request argument, C-16 no_table module attribute, 3-10, C-9 Non-ASCII characters, 7-1 non-match function, 7-6 number debugger request argument, C-13 number_of_tasks binder directive, 3-12, C-9
M
machine debugger request, C-17 Machine mode debugging, 4-24 -main compiler argument, 2-21, B-3, C-4 -map binder argument, 3-4 -mapcase compiler argument, 2-19, B-2, C-3 Memory allocation, 3-7, 3-13 memory_reference debugger request argument, C-15 Messages as external variables, C-8 Module attributes, 3-9 compact, 3-10 no_compact, 3-10 no_table, 3-10 page_aligned, 3-10 table, 3-10 module_term name, 3-9 Modules keep, 4-4 object, 1-3 program, 1-4 source, 1-3 modules binder directive, 3-9, C-9 Multitasking, 3-12, 3-13, 4-23
O
.obj suffix, 1-3, 3-2, 3-9, C-4, C-7, C-9 Object libraries, 3-1 Object listings, C-5 Object mode debugging, 4-24 Object modules, 1-3, 3-2, C-7 open extend statement, 5-18 open input statement, 5-18 Open modes, 5-12 extend, 5-12, 5-18 I/O, 5-13 input, 5-12, 5-18 output, 5-12, 5-18 open output statement, 5-18 open statement extend option, 5-18 input option, 5-18 output option, 5-18 tape mounting, 5-18 Optimization, 2-21 constant folding, 2-21 loop, 2-21 -optimize compiler argument, C-3 options binder directive, 3-14, C-9 Out of bounds array subscripts, 2-10 Output I/O type, 5-12 Output mode, 5-12 output option open statement, 5-18
N
name binder directive, 3-11, C-9 National Language Support (NLS), 7-1 character sets canonical strings and, 7-4 common strings and, 7-4 hangul, 7-1 kanji, 7-1 katakana, 7-1 Latin alphabet No. 1, 7-1 ROC Chinese, 7-1 shift function and, 7-4 simplified Chinese, 7-1 unshift function and, 7-4 user-defined double-byte, 7-1 string, 7-2
P
page_aligned module attribute, 3-10, C-9 Parameters pass-by-reference, 4-21 pass-by-value, 4-21 Pascal data types, 6-10 functions, 6-10 passing parameters in, 6-9
Index-6
Index procedures, 6-10 value parameters, 6-9 variable parameters, 6-9 Passing arguments by content, 6-9, 6-11 by reference, 6-9, 6-11 Passing arguments in COBOL to C language routines, 6-11 Passing parameters by content, 6-4 by reference, 6-4 in BASIC, 6-15 in C, 6-11 in FORTRAN, 6-13 in Pascal, 6-9 in PL/I, 6-7 Path names, C-8, C-9 in binder control files, 3-9 in compilation listings, 2-5 in examples, 3-10 Performance information binder, 3-8 compiler, 2-12 program execution, 2-13 PL/I data storage, 6-7 data types, 6-8 extents, 6-8 functions, 6-7 passing parameters in, 6-7 programs, 6-6 star extents, 6-8 .plist suffix, 2-13 .pm suffix, 1-4 Pointer-qualified variable reference, 4-13 position debugger request, 4-8, C-16 Position phrase, 5-18 Predefined functions shift, 7-4 unshift, 7-4 Printer files, 5-20 Procedure calls from debugger, 4-21 Process size large vs. small, C-7 -processor compiler argument, 2-18, C-2 -production_table compiler argument, 2-11, 4-3, C-3 -profile compiler argument and creating .profile files, 2-13 profile command, 2-13 -profile compiler argument, C-3 .profile suffix, 2-13 Program optimization, C-3 size, 3-7 Program modules, 1-4, 6-1, C-7 allocating space for, 3-7 creating, 1-4 executing, 1-4 Programming languages BASIC, 6-15 C, 6-11 COBOL, 6-5 FORTRAN, 6-13 Pascal, 6-9 PL/I, 6-6
Q
quit debugger request, 4-6, C-16 Quitting the debugger, 4-6
R
Random access mode, 5-4 read statement end of reel, 5-19 re-enter break level request, 4-7 Registers, 4-25, 4-26 and debugging, C-16 regs debugger request, 4-25, C-16 Relative file organization, 5-2 Request lists in debugging, 4-15, C-15 request_list debugger request argument, C-13, C-15 Reserved words, C-3 Restrictions 300-character line limit, 4-5 case, 2-19 retain binder directive, 3-12, C-10 return debugger request, C-16 Right control characters, 7-3 Right graphic characters, 7-3 ROC Chinese character set, 7-1
S
s$open subroutine, 5-5, 5-13 Scope, 4-5 -search binder argument, 3-2, 3-3 search binder directive, 3-12, C-10 Search rules, 3-3, 3-9, C-6 -segmentation compiler argument, 2-21, B-2, C-4 select clause tape, 5-18 Selecting a processor, 2-18
Index-7
Index Separate-key index, 5-6 Sequential access mode, 5-2 Sequential file organization, 5-2 set debugger request, 4-14, C-16 set_tape_defaults command, 5-18 Setting breakpoints, 4-12, C-14 Shared variables, 3-13, C-8 Shift characters, 7-3 locking-shift, 7-3 single-shift, 7-3 shift function, 7-4 -silent compiler argument, 2-10, C-4 Simplified Chinese character set, 7-1 Single-shift characters, 7-3 -size binder argument, 3-6 size binder directive, 3-14, C-10 Sorted cross-reference listings, C-3 source debugger request, 4-7, 4-23, C-16 Source listings, C-5 Source mode debugging, C-13 Source modules, 1-3, 1-3, C-2 source_path debugger request, 4-23 Spaces between module attributes, 3-9, C-9 in binder control files, C-8 special-names paragraph channel n, 5-20 Stack frames, 4-5 stack_size binder directive, 3-12, C-10 Stacks, 4-5, 4-9 Star names, 4-13 start debugger request, 4-9, C-16 static allocation, 2-19 Static data, 2-19, C-4 static external variables, C-10 Statistics binder, C-7 compiler, C-4 -statistics binder argument, 3-8 -statistics compiler argument, 2-12, C-4 step debugger request, 4-17 Stepping through a program, 4-17 stop break level request, 4-7 Storage of characters, 7-2 Stream file organization, 5-2 Strings canonical, 7-4 common, 7-4 NLS, 7-2 Suffixes .bind, 3-9, C-8 .cobol, 1-3, C-4 .error, 1-3, 2-9 .kp, 4-4, C-12, C-15 .list, 1-3, C-5 .obj, 1-3, 3-2, 3-9, C-4, C-7, C-9 .plist, 2-13 .pm, 1-4 .profile, 2-13 Supplementary character sets, 7-1 character set IDs and, 7-7 mnemonic names and, 7-7 symbol debugger request, 4-13, C-17 Symbol listings, 2-3 Symbol tables, 2-11, 4-3, C-3, C-7 synonym binder directive, C-10 Syntax, C-8 delimiters, C-8
T
-table compiler argument, 4-3, C-3 table module attribute, 3-10, C-9 Tables multidimensional, 4-13 single dimensional, 4-13 Tape files, 5-17 Tape mounting open statement, 5-18 tape_format command, 5-17 task_status debugger request, 4-23 Tasking, 3-12, 3-13, 4-23, 4-24 current task environment, 4-11 debugging, 4-10 Temporary storage of variables, 6-5 trace debugger request, 4-9, C-17 Tracing a stack, 4-9
U
Uninitialized data, 2-19, C-4 Unshared variables, 3-13 unshift function, 7-4 Update I/O type, 5-12 Uppercase conversion restriction, 2-19 conversion to lowercase, 2-19 letters, C-3 use_abbreviations command, 4-28 use procedure, 5-6 User-defined double-byte character set, 7-1
V
variable debugger request argument, C-14 variable_arg_count binder directive, C-10
Index-8
Index Variables allocating address space for, 3-13 external static, 3-13 in the debugger, 4-13 initializing, 3-13 shared, 3-13 unshared, 3-13 variables binder directive, 3-12, C-10 VOS BASIC, 6-15 VOS COBOL, 6-5 VOS commands in debugger, 4-28 VOS FORTRAN, 6-13 VOS Pascal, 6-9 VOS PL/I, 6-6 vosc, 6-11
W
where debugger request, 4-11, C-17 with dope phrase, 6-8 Word delimiters, C-8 write statement end of reel, 5-19 Writing a binder control file, 3-9
X
-xref compiler argument, 2-6, C-3 -xref_format compiler argument, 2-6, C-3
Index-9

VOS COBOL User Guide

Uploaded by

Copyright:

Available Formats

VOS COBOL User Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

VOS COBOL User Guide

Uploaded by

Copyright:

Available Formats

R142-00

VOS COBOL Users Guide

Stratus Computer, Inc.

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

1990 by Stratus Computer, Inc. All rights reserved.

VOS COBOL Users Guide (R142)

VOS COBOL Users Guide (R142)

VOS COBOL Users Guide (R142)

VOS COBOL Users Guide (R142)

VOS COBOL Users Guide (R142)

VOS COBOL Users Guide (R142)

Chapter 1: Overview: Programming in VOS COBOL

VOS COBOL Users Guide (R142)

Overview: Programming in VOS COBOL

edit file_name Source Module file_name.cobol Error Listing file_name.error

Compiler Listing cobol file_name file_name.list

Compiler Errors? No Object Module file_name.obj

Binder bind file_name

Binder Errors? No Program Module file_name.pm

Figure 1-1. Program Development Process

Preparing a Source Program

Preparing a Source Program

Compiling a Source Module

VOS COBOL Users Guide (R142)

Binding Object Modules

Binding Object Modules

Executing and Interrupting a Program Module

Chapter 1: Overview: Programming in VOS COBOL

Executing and Interrupting a Program Module

VOS COBOL Users Guide (R142)

Executing and Interrupting a Program Module

Chapter 1: Overview: Programming in VOS COBOL

Chapter 2: Compiling a Source Module

VOS COBOL Users Guide (R142)

Creating a Program Listing

The cobol commands display form is as follows:

Creating a Program Listing

Table 2-1. Arguments That Create Compilation Listings Option

Chapter 2: Compiling a Source Module

Creating a Program Listing

Creating a Compilation Listing

(Continued on next page)

VOS COBOL Users Guide (R142)

Creating a Program Listing

NAME monthly_sales report_writer

(Continued on next page)

Chapter 2: Compiling a Source Module

Creating a Program Listing

ATTRIBUTES lists various attributes related to the object.

Creating a Program Listing

Creating a Cross-Reference Listing

standard. The cross-reference information is included in the Attributes area of the

Chapter 2: Compiling a Source Module

Creating a Program Listing

transaction_number_in data/numeric trans_amount_in data/alphanum . . . summary_and_cleanup paragraph-name

Figure 2-2. Cross-Reference Listing

VOS COBOL Users Guide (R142)

Creating a Program Listing

Figure 2-3. Sorted Cross-Reference Listing

Producing an Assembly Language Listing