PDP-11 COBOL User's Guide Order No. AA-17570-TC The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. Digital Equipment Corporation assumes no responsibility for the use or reliability of its software on equipment that is not supplied by Digital. Copyright@ 1974, 1976, 1977, 1978 by Digital Equipment Corporation The postage-prepaid READER'S COMMENTS form on the last page of this document requests the user's critical evaluation to assist us in preparing future documentation. The following are trademarks of Digital Equipment Corporation: DIGITAL DEC PDP DEC US UNIBUS COMPUTER LABS COMTEX DDT DEC COMM ASSIST-11 VAX DECnet DECsystem-1,0' DECtape DIBOL EDUSYSTEM FLIP CHIP FOCAL INDAC LAB-8 DECSYSTEM-2,0' RTS-8 VMS !AS MASS BUS OMNIBUS OS/8 PHA RSTS RSX TYPESET-8 TYPESET-11 TMS-11 ITPS-1,0' SB! 2.'79-15 November 1978 This document describes how to use Version 4 of the PDP-11 COBOL compiler. It is a companion guide to the PDP-11 COBOL Language Reference Manual. PDP-11 COBOL User's Guide Order No. AA-17570-TC SUPERSESSION/UPDATE INFORMATION: This document supersedes the document of the same name, Order No. AA-1757C-TC published April 1977. OPERATING SYSTEM AND VERSION: RSTS/E RSX-11 M IAS V06C V03 V02 SOFTWARE VERSION: PDP-11 COBOL V04 To order additional copies of this document, contact the Software Distribution Center, Digital Equipment Corporation, Maynard, Massachusetts 01754 digital equipment corporation · maynard, massachusetts The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. Digital Equipment Corporation assumes no responsibility for the use or reliability of its software on equipment that is not supplied by Digital. Copyright@l974, 1976, 1977, 1978 by Digital Equipment Corporation The postage-prepaid READER'S COMMENTS form on the last page of this document requests the user's critical evaluation to assist us in preparing future documentation. The following are trademarks of Digital Equipment Corporation: DIGITAL DEC PDP DECUS UNIBUS COMPUTER LABS COMTEX DDT DEC COMM ASSIST-11 VAX DECnet DECsystem-1,0' DECtape DIBOL EDUSYSTEM FLIP CHIP FOCAL INDAC LAB-8 DECSYSTEM-2,0' RTS-8 VMS IAS MASS BUS OMNIBUS OS/8 PHA RSTS RSX TYPESET-8 TYPESET-11 TMS-11 ITPS-1,0' SBI CONTENTS Page PREFACE xv ACKNOWLEDGMENTS xvii CHAPTER 1 INTRODUCTION 1-1 CHAPTER 2 USING THE PDP-11 COBOL SYSTEM 2-1 2.1 2.1.1 2.1. 2 2.2.1 2.2.2 2.2.3 2.2.4 2.2.5 2.3 2.3.1 2.3.2 2.3.3 2.3.4 2.4 2.4.1 2.4.2 2.5 2.5.l 2.5.2 2.5.3 2.6 2.6.l 2.6.2 CREATING A SOURCE FILE Choosing a Reference Format Entering a Source Program USING THE LIBRARY FACILITY (COPY) Creating a COBOL Library File The COPY Statement The COPY REPLACING Statement The Source Listing Common Errors in Using the Library Facility USING THE PDP-11 COBOL COMPILER PDP-11 COBOL Command Line Compiler Switches Error Message Summary Common PDP-11 COBOL Command Line Errors THE COBOL MERGE UTILITY Using the Merge Utility Merge Utility Error Messages TASK-BUILDING PDP-11 COBOL PROGRAMS Using ODL-File Input Using Object-File Input Program Task Size EXECUTING A COBOL TASK The RUN Command Setting Program Switches 2-1 2-1 2-2 2-2 2-3 2-3 2-5 2-8 2-8 2-9 2-10' 2-11 2-15 2-16 2-16 2-18 2-23 2-25 2-25 2-27 2-29 2-29 2-30' 2-30' CHAPTER 3 NON-NUMERIC DATA HANDLING 3-1 3.1 3.2 3.2.1 3.2.2 3.3 3.4 3.4.1 3.4.1.1 3.4.1.2 3.4.2 3.5 3.6 3.6.1 3.6.2 3.6.2.1 INTRODUCTION DATA ORGANIZATION Group Items Elementary Items SPECIAL CHARACTERS TESTING NON-NUMERIC FIELDS Relation Tests Classes of Data The Comparison Operation Class Tests DATA MOVEMENT THE MOVE STATEMENT Group Moves Elementary Moves Edited Moves 3-1 3-2 3-2 3-2 3-3 3-4 3-4 3-5 3-6 3-6 3-7 3-8 3-8 3-8 3-1~ iii CONTENTS (Continued) 3.6.2.2 3.6.3 3.6.4 3.6.5 3.6.6 3.7 3.7.1 3.7.2 3.7.3 3.7.4 3.7.5 3.7.6 3.8 3.8.1 3.8.2 3.8.2.1 3.8.3 3.8.4 3.8.5 3.8.6 3.8.7 3.8.8 3.8.9 3.9 3.9.1 3.9.2 3.9.3 3.9.3.1 3.9.3.2 3.9.3.3 3.9.4 3.9.5 3.9.5.1 3.9.5.2 3.9.5.3 3.9.5.4 3.9.6 3.9.6.1 3.9.6.2 3.9.6.3 3.9.6.4 3.986.5 3.9.7 Justified Moves Multiple Receiving Fields C:::nh<:!l"'r;n+-orl MnuoQ .., .... ..,..., ....... ~ .... I:''-'-"'&..&""'¥'- ..... Common Errors, MOVE Statement Format 2, MOVE CORRESPONDING THE STRING STATEMENT Multiple Sending Fields The POINTER Phrase The DELIMITED BY Phrase The OVERFLOW Phrase Subscripted Fields in STRING Statements Common Errors, STRING Statement THE UNSTRING STATEMENT Multiple Receiving Fields The DELIMITED BY Phrase Multiple Delimiters The COUNT Phrase The DELIMITER Phrase The POINTER Phrase The TALLYING Phrase The OVERFLOW Phrase Subscripted Fields in UNSTRING Statements Common Errors, UNSTRING Statement THE INSPECT STATEMENT The BEFORE/AFTER Phrase Implicit Redefinition The INSPECT Operation Setting the Scanner Active/Inactive Arguments Finding an Argument Match Subscripted Fields in INSPECT Statements The TALLYING Phrase The Tally Counter The Tally Argument The Tally Argument List Interference in Tally Argument Lists The REPLACING Phrase The Search Argument The Replacement Value The Replacement Argument The Replacement Argument List Interference in Replacement Argument Lists Common Errors, INSPECT Statement CHAPTER 4 4cl 4 .1.1 4 .1. 2 4 .1. 3 4 .1. 4 4.2 4.3 4.4 4.5 4.5.1 NUMERIC CHARACTER HANDLING USAGES DISPLAY COMPUTATIONAL COMPUTATIONAL-6 COMPUTATIONAL-3 DECIMAL SCALING POSITION SIGN CONVENTIONS ILLEGAL VALUES IN NUMERIC FIELDS TESTING NUMERIC FIELDS Relation Tests Page 3-1.0 3-11 3-11 3-12 3-12 3-13 3-13 3-14 3-15 3-17 3-18 3-2~ 3-21 3-21 3-23 3-27 3-28 3-29 3-3~ 3-32 3-33 3-34 3-36 3-36 3-37 3-38 3-4.0 3-41 3-41 3-42 3-43 3-43 3-44 3-44 3-45 3-47 3-51 3-51 3-52 3-52 3-53 3-54 3-55 4-1 4-1 4-1 4-1 4-3 4-5 4-6 4-6 4-8 4-8 4-8 iv C0NTENTS (Continued} 4.5.2 4.5.3 4.6 4.6.1 4.6.2 4.6.3 4.6.4 4.7 4.7.1 4.7.2 4.7.3 4.7.4 4.7.5 4.7.6 4.7.7 4.7.8 4.7.9 4.7.1.0' 4.7.11 4.8 Sign Tests Class Tests THE MOVE STATEMENT Group Moves Elementary Numeric Moves Elementary Numeric Edited Moves Common Errors, Numeric MOVE Statements THE ARITHMETIC STATEMENTS Intermediate Results The ROUNDED Phrase The SIZE ERROR Phrase The GIVING Phrase Multiple Operands in ADD and SUBTRACT Statements The ADD Statement The SUBTRACT Statement The MULTIPLY Statement The DIVIDE Statement The COMPUTE Statement Common Errors, Arithmetic Statements ARITHMETIC EXPRESSION PROCESSING CHAPTER 5 TABLE HANDLING 5.1 5.2 5.2.1 5.2.2 5.3 5.3.1 5.4 5.4.1 5.4.2 5.4.3 5.4.4 5.4.5 5.4.6 5.4.7 5.4.8 5.4.9 5.4.1.0' 5.4.11 5.4.12 5.4.13 5.4.14 INTRODUCTION DEFINING TABLES The OCCURS Phrase - Format 1 The OCCURS Phrase - Format 2 MAPPING TABLE ELEMENTS Initializing Tables SUBSCRIPTING AND INDEXING Subscripting with Literals Operations Performed by the Software Subscripting with Data-Names Operations Performed by the OTS Subscripting with Indexes Operations Performed by the OTS Relative Indexing Index Data Items The SET Statement Referencing a Variable-Length Table Element at OTS Time Referencing a Dynamic Group at OTS Time The SEARCH Verb The SEARCH Verb - Format 1 The SEARCH Verb - Format 2 CHAPTER 6 FILE HANDLING 6.1 6 .1.1 6 .1. 2 6 .1. 3 6 .1. 4 6 .1. 5 6 .1. 6 6.1.6.1 SEQUENTIAL FILE ORGANIZATION Record Size RECORD CONTAINS'Clause SAME RECORD AREA Clause Print-Controlled Records Record Blocking Buffering Buffer Size v Page 4-9 4-1.0' 4-1.0' 4-11 4-11 4-13 4-14 4-15 4-15 4-16 4-17 4-18 4-18 4-19 4-19 4-2.0' 4~21 4-21 4-21 4-22 5-1 5-1 5-1 5-2 5-2 5-3 5-7 5-9 5-1.0' 5-11 5-11 5-11 5-12 5-12 5-13 5-14 5-14 5-15 5-15 5-16 5-16 5-17 6-1 6-3 6-4 6-4 6-5 6-6 6-6 6-7 6-8 CONTENTS (Continued) 6.1.6.2 6.1.6.3 6.1.6.4 6.1. 7 6.1.7.1 6.1.7.2 6.1.7.3 6.1.7.4 6.1.7.5 6.2 6.2.1 6.2.2 6.2.3 6.2.4 6.2.5 6.2.5.1 6.2.5.2 6.2.5.3 6.2.5.4 6.2.6 6.2.6.1 6.2.6.2 6.2.6.3 6.2.6.4 6.2.6.5 6.2.6.6 6.2.6.7 6.2.6.8 6.3 6.3.1 6.3.2 6.3.3 6.3.4 6.3.5 6.3.5.1 6.3.5.2 6.3.5.3 6.3.5.4 6.3.6 6.3.6.1 6.3.6.2 6.3.6.3 6.3.6.4 6.3.6.5 6.3.6.6 6.3.6.7 6.4 6.4.l 6.4.2 6.4.3 6.5 6.5.1 6.5.2 6.5.3 6.6 6.6.1 6.6.2 I-0 Buffer Areas Buffer Space Sharing Buffer Space Among Files Sequential I/O Statements Opening Sequential Files Reading Sequential Files Rewriting Records into Sequential Files Writing Sequential Files Closing Sequential Files RELATIVE FILE ORGANIZATION Record Size RECORD CONTAINS CLAUSE SAME RECORD AREA Clause Record Blocking Buffering Buffer Size I/0 Buffer Areas Buffer Space Sharing Buffer Space Among Files Relative I/O Statements Access Modes Opening Relative Files Reading Relative Files Rewriting Records into a Relative File Writing Records in a Relative File Deleting Records from a Relative File Specifying the Next Record to be Read Closing Relative Files INDEXED FILE ORGANIZATION Record Size RECORD CONTAINS Clause SAME RECORD AREA Clause Record Blocking Buffering Buffer Size I/O Buffer Areas Buffer Space Sharing Buffer Space Among Files Indexed I/O Statements Access Mode Opening Indexed Files Reading Indexed Files Rewriting Records into an Indexed File Deleting Records from an Indexed File Specifying the Next Record to be Read Closing Indexed Files DEVICES Disk Magnetic Tape Card Reader and Line Printer FILES AND FILENAMES Using Explicit Filenames (VALUE OF ID Clause) Device Asssignment by ASSIGN Clause Files and Logical Units COMMUNICATING WITH THE PROGRAM Using the ACCEPT Statement Using the DISPLAY Statement vi Page 6-8 6-8 6-8 6-9 6-9 6-11 6-12 6-12 6-13 6-13 6-14 6-14 6-15 6-15 6-17 6-18 6-18 6-18 6-18 6-18 6-19 6-2J 6-21 6-22 6-22 6-22 6-23 6-24 6-24 6-27 6-27 6-27 6-27 6-3J 6-3$J 6-3J 6-31 6-31 6-31 6-32 6=33 6-34 6-34 6-35 6-35 6-37 6-37 6-38 6-39 6-39 6-4J 6-41 6-43 6-43 6-45 6-45 6-46 6.7 6.7.1 6.7.2 6.7.3 6.8 CHAPTER 7 7.1 7.2 7.3 7.4 7.5 ., c I· U 7.6.1 7.6.2 7.6.3 7.6.4 7.6.5 7.6.6 CHAPTER 8 CHAPTER 9 9.1 9 .1.1 9.2 9.3 9.4 CHAPTER 1,0 1,0'.l 1.0 .1.1 1,0.1.2 1,0'.2 1,0. 3 1,0'.4 CHAPTER 11 11.1 11. 2 11. 3 11. 4 11.4.1 11.4.2 11. 4. 3 CONTENTS (Continued) Page FILE COMPATIBILITY WITH OTHER PROGRAMMING LANGUAGES Writing Files for Other Programming Languages Reading Files Written in Other Programming Languages Data File Transportability PROCESSING I/O ERRORS - USE STATEMENT 6-47 6-47 6-48 6-48 6-49 GOOD PROGRAMMING PRACTICES 7-1 FORMATTING THE SOURCE PROGRAM USE OF PUNCTUATION USE OF THE ALTER STATEMENT USE OF THE PERFORM STATEMENT USE OF LEVEL-88 CONDITION NAMES USE OF QUALIFIED REFERENCES Qualified Data References Guideline 1 (Data Item Definition) Guideline 2 (Reference Format) Guideline 3 (Unique Referability) Qualified Procedure References Qualification and Compiler Performance 7-1 7-4 7-5 7-5 7-6 7-8 7-8 7-1.0 7=1.0' 7-11 7-12 7-12 REFORMAT UTILITY PROGRAM 8-1 SEGMENTATION 9-1 USING THE PDP-11 COBOL SEGMENTATION FACILITY 9-1 Programming Considerations 9-2 SEGMENTATION AND THE PDP-11 COBOL COMPILER 9-2 SEGMENTATION USING THE /OV SWITCH 9-2 USING THE CSEG:nnnn SWITCH 9-3 INTER-PROGRAM COMMUNICATIONS 1.0'-l COBOL MAIN PROGRAMS VS SUBPROGRAMS Calling a COBOL Subprogram from a COBOL Program Returning from a COBOL Subprogram UNIQUENESS OF PSECT NAMES COBOL OTS - ERROR CHECKING INCLUDING A NON-COBOL OBJECT MODULE IN A TASK 1.0-1 1.0'-2 1.0'-3 1.0'-3 1.0'-3 1.0'-4 HAND-TAILORING ODL FILES 11-1 STANDARD ODL FILE ODL FILE HEADER ODL FILE BODY COMPILER-GENERATED ODL FOR COBOL PSECTS ODL Generated for Overlays Containing Only One PSECT ODL Generated for Overlays Containing More Than One PSECT ODL Generated for All Overlayable PSECTS 11-1 11-1 11-2 11-3 11-3 11-3 11-3 vii CONTENTS (Continued) 11. 5 11. 6 1, ,1..6., .l ..1. .J. · I 11. 7 .1 11. 7. 2 MERGING STANDARD ODL FILES INCLUDING NON-COBOL PROGRAMS IN A TASK Creating a Standard COBOL ODL File REARRANGING A COMPILER-GENERATED ODL FILE Modifying the Compiler-Generated ODL File Specifying Task Builder Options CHAPTER 12 ERROR MESSAGES 12.1 12.2 12.3 12.4 COMPILER SYSTEM ERRORS DIAGNOSTIC ERROR MESSAGES RUNTIME FILE I/O ERROR PROCEDURES RUNTIME ERROR MESSAGES CHAPTER 13 COBOL INTERACTIVE DEBUGGER (CID) 13 .1 13. 2 13.3 13.3.l 13.3.2 13.4 13.4.1 13.4.2 13.4.3 13.4.4 13.4.5 13.4.6 13.4.7 13.5 13. 6 13.7 13. 8 13.9 13.9.1 13.9.2 HOW TO INCLUDE CID COMMAND MODE AND THE CID ENVIRONMENT ADDRESSING Addressing Data Addressing Procedure Division Code COMMANDS CANCEL BREAKPOINT Command DEPOSIT Command EXAMINE Command GO Command SET BREAKPOINT Command SHOW BREAKPOINTS Command XIT Command PROGRAM INITIATION USING BREAKPOINTS PROGRAM TERMINATION AND SUSPENSION CID COMMAND ERRORS EXAMPLES Sample Debugging Session Sample Program Listings CHAPTER 1 A .L ".t OPTIMIZATION 14.1 OPTIMIZING MASS STORAGE I/O 14.2 PROGRAM DEVELOPMENT 14.2.1 Overlay Structure 14.2.2 Sequentially Reading Indexed Files 14.2.3 Caching Index Roots 14.2.4 Multi-block Reading and Writing 14.3 FILE DESIGN 14.3.1 Sequential Files 14.3.2 Relative Files 14.3.3 Indexed Files 14.3.3.1 General Rules for Indexed Files 14.3.3.2 Bucket Size 14.3.3.3 Index Depth 14.3.3.4 File Activity 14.4 OPTIMIZING COMPUTATION 14.5 FILE SPECIFICATION SWITCHES Page 11-5 11-5 11-5 11-6 11-6 11-8 12-1 12-1 12-1 12-4 12-5 13-1 13-1 13-2 13-3 13-3 13-3 13-4 13-5 13-5 13-6 13-7 13-7 13-8 13-8 13-8 13-9 13-9 13-1,, 13-11 13-11 13-14 14-1 14-1 14-2 14-2 14-3 14-3 14-3 14-4 14-4 14-5 14-5 14-7 14-8 14-9 14-9 14-1.0' 14-11 viii APPENDIX A APPENDIX B APPENDIX c APPENDIX D D.l APPENDIX E E.l E .1.1 E. l. 2 E. l. 3 E. l. 4 E. l. 5 E.2 E.3 E.4 E.5 E.6 E.7 APPENDIX F F.l F .1.1 F .1. 2 F.1. 3 F .1. 4 F .1. 5 F .1. 6 F .1. 7 F.2 APPENDIX G APPENDIX H APPENDIX I APPENDIX J INDEX C-0-N'I'-B-N'I'-S ( C-e-n t i-nue-d) Page THE COBOL FORMATS A-1 LOGICAL UNIT NUMBER (LUN) ASSIGNMENT B-1 PDP-11 COBOL COMPILER IMPLEMENTATION LIMITATIONS C-1 COMPILER-GENERATED PSECTS D-1 PSECT NAMING CONVENTIONS D-1 SORTING FILES IN A COBOL PROGRAM E-1 CALL STATEMENTS REQUIRED E-1 Initializing the SORT - CALL RSORT E-1 Passing a Record to the Sort - CALL RELES E-2 Merging the Scratch Files - CALL MERGE E-2 Requestinq an Output Record - CALL RETRN E-2 Terminating the Sort - CALL ENDS E-3 SETTING UP THE KEY E-3 WORK AREA SIZE E-3 TYPICAL USAGE SEQUENCE E-3 LINKING SORT ROUTINES WITH A COBOL PROGRAM E-4 COMPARISON WITH ANS COBOL SORT VERB E-4 ERROR CODES E-5 RSTS/E TERMINAL HANDLING SERVICES F-1 GENERAL SERVICES F-1 Opening a Logical Unit for Terminal I/O F-2 Close a Terminal Logical Unit F-2 Assigning a Terminal F-2 Deassigning a Terminal F-3 Write to a Specific Terminal F-3 Read from a Specific Terminal F-4 READ Unsolicited from Any Terminal Assigned F-4 ERROR CODES DURING MULTI-TERMINAL HANDLING F-5 SOURCE PROGRAM LISTINGS G-1 DIAGNOSTIC ERROR MESSAGES H-1 RECORD MANAGEMENT SERVICES ERROR CODES I-1 OBJECT TIME SYSTEM ERROR MESSAGES J-1 Index-I ix FIGURE 1-1 2-1 2-2 2-3 3-1 3-2 3-3 3-4 3-5 3-6 3-7 3-8 3-9 3-10' 3-11 3-12 3-13 3-14 3-15 3-16 3-17 3-18 3-19 3-20' 3-21 3-22 3-23 3-24 3-25 3-26 3-27 3-28 3-29 3-31} 3-31 3-32 3-33 3-34 3-35 3-36 3-37 3-38 3-39 3-41} 3-41 3-42 3-43 3-44 FIGURES Page Building a COBOL Task Image 1-4 Merging Library Text 2-4 Merge Dialogue Using Multiple Object Modules and Default I/O Overlaying 2-22 Merge Dialogue Using One Object Module and No I/O Overlaying 2-23 Field Sizes 3-2 Redefining Special Characters 3-3 ASCII Code Chart 3-4 Relation Condition 3-4 The Meanings of Relational Operators 3-5 Class Condition, General Format 3-6 Data Movement with Editing Symbols 3-10' Data Movement with No Editing 3-11 Subscripted MOVE Statements 3-11 Sample STRING Statement 3-13 Concatenation with the STRING Statement 3-13 Literals as Sending Fields 3-14 Indexed Sending Fields 3-14 Sample POINTER Phrase 3-14 Delimiting with the Word SIZE 3-15 SPACE as a Delimiter 3-15 Repeating the DELIMITED BY Phrase 3-16 Delimiting with More Than One Space Character 3-16 The ON OVERFLOW Phrase 3-17 Various STRING Statements Illustrating the Overflow Condition 3-17 STRING Statement with Pointer 3-18 Subscripting with the Pointer 3-19 Subscripting with the Delimiter 3-19 Sample UNSTRING Statement 3-21 Multiple Receiving Fields 3-21 Delimiting with a Space Character 3-23 Delimiting with Multiple Receiving Fields 3-24 Delimiting with an Identifier 3-27 Multiple Delimiters 3-27 The COUNT Phrase 3-28 The DELIMITER Phrase 3-29 The POINTER Phrase 3-30' Examining the Next Character by Using the Pointer Data Item as a Subscript 3-31 Examining the Next Character by Placing It Into a One-Character Field 3-31 The TALLYING Phrase 3-32 The POINTER and TALLYING Phrases used Together 3-32 Subscripting the COUNT Phrase with the TALLYING Data Item 3-33 Using the OVERFLOW Phrase 3-34 Sequence of Subscript Evaluation 3-35 Erroneously Repeating the Word INTO 3-36 Sample INSPECT . · . TALLYING Statement 3-37 Sample INSPECT ·.· REPLACING Statement 3-37 Sample INSPECT ··. BEFORE Statement 3-37 Matching the Delimiter Characters to the Characters in a Field 3-38 x 3-45 3-46 3-47 3-48 3-49 3-50' 3-51 3-52 3-53 3-54 3-55 3-56 3-57 3-58 3-59 3-6.0 3-61 3-62 3-63 3-64 3-65 3-66 3-67 3-68 3-69 3-7.0 3-71 3-72 3-73 4-1 4-2 4-3 4-4 4-5 4-6 4-7 4-8 FIGURES (Continued) Page Sample INSPECT Statement Sample REPLACING Argument Sample AFTER Delimiter Phrase Where Arguments Become Active in a Field Sample Subscripted Argument Format of the Tally Argument CHARACTERS Form of the Tally Argument Results of Counting with the LEADING Condition · Argument List Adding into One Tally Counter Argument List Adding into Separate Tally Counters Argument List (with Delimiters) Adding into Separate Tally Counters Results of the Scan in Figure 3-55 Two Tallying Arguments that Do Not Interfere with Each Other Two Tallying Arguments that Do Interfere with Each Other Two Tallying Arguments that, Because of Their Positioning, Only Partially Interfere with Each Other An Attempt to Tally the Character B with Two Arguments Tallying Asterisk Groupings Placing the LEADING Condition in the Argument List Reversing the Argument List in Figure 3-62 An Argument List that Counts Words in a Statement Counting Leading Tab or Space Characters Counting the Remaining Characters with the CHARACTERS Argument Format of the Search Argument Format of the Replacement Value The Replacement Argument R~placement Argument List that is Active Over the Entire Field Replacement Argument List that "Swaps" Ones for Zeroes and Zeroes for Ones Replacement Argument List that Becomes Inactive with the Occurrence of a Space Character Argument List with Three Arguments that Become Inactive with the Occurrence of a Space Memory Storage of COMP Data Items Memory Storage of COMP-6 Data Items Memory Storage of COMP-3 Data Items Truncation Caused by Decimal Point Alignment Zero Filling Caused by Decimal Point Alignment Numeric Edi ting Rounding Truncated Decimal Point Positions Rounding Truncated Decimal Scaling Positions 3-40' 3-40' 3-41 3-42 3-43 3-44 3-44 3-45 3-45 3-46 3-46 3-46 3-47 3-47 3-47 3-48 3-48 3-49 3-49 3-49 3-50' 3-50' 3-51 3-52 3-53 3-53 3-53 3-54 3-54 4-2 4-4 4-5 4-12 4-12 4-14 4-16 4-16 xi 4-9 4-1,0 4-11 5-1 5-2 5-3 5-4 5-5 5-6 5-7 5-8 5-9 5-1,0 5-11 5-12 5-13 5-14 5-15 5-16 5-17 5-18 5-19 5-2g 6-1 6-2 6-3 6-4 6-5 6-6 7-1 7-2 7-3 7-4 9-1 9-2 10'-l 10'-2 11-1 11-2 11-3 14-1 FIGURES (Continued) Page Explicit Programmer-Defined Temporary Work Area Arithmetic Statement Intermediate Result Field Attributes Determined from Composite of Operands Arithmetic Expression Intermediate Result Field Attributes Determined by ImplementorDef ined Rules Defining a Table Mapping a Table into Memory Synchronized COMP Item in a Table Adding a Field without Altering the Table Size Adding One Byte which Adds Two Bytes to the Element Length Forcing an Odd Address by Adding a 1-Byte FILLER Item to the Head of the Table The Effect of a SYNCHRONIZED RIGHT Clause Instead of a FILLER Item as Shown in Figure 5-6 Initializing Tables Initializing Mixed usage Fields Initializing Alphanumeric Fields Literal Subscripting Subscripting a Multi-Dimensional Table Subscripting Rules for a Multi-Dimensional Table Subscripting with Data-Names Index-Name Item Subscripting with Index-Name Items Relative Indexing Index Data Item Legal Data Movement with the SET Statement Example of Using SEARCH to Search a Table Placement of End-of-File Mark Placement of the End-of-Volume Label and End-of-File Mark in a Multi-Volume File Single Key Indexed File Organization Multi-Key Indexed File Organization Assigning Logical Names to the Card Reader and Line Pr inter Assigning the Card Reader and Line Printer to Files Unqualified Data Item Reference Qualified Data Item Reference General Format of a Qualified Data Reference General Format og a Qualified Procedure Reference Segmentation Using the /OV Switch Using the /CSEG:nnnn Switch Sample LINKAGE SECTION and USING Phrase Argument Address List Merged ODL File Listing Modified ODL File Overlay Description Map Before and After Modification Three-Level Primary Key Index 4-23 4-23 4-24 5-2 5-3 5-4 5-5 5-5 5-6 5-6 5-7 5-8 5-8 5-9 5-1g 5-lg 5-11 5-12 5-12 5-14 5-14 5-15 5-19 6-3 6-4 6-25 6-26 6-39 6-4g 7-8 7-9 7-lg 7-11 9-3 9-4 lg-2 lg-6 11-7 11-8 11-9 14-6 X .;...;.. TABLE 2-1 2-2 2-3 3-1 3-2 3-3 3-4 3-5 3-6 3-7 3-8 3-9 3-1.0 3-11 3-12 4-1 4-2 6-1 6-2 6-3 6-4 6-5 6-6 6-7 6-8 6-9 6-1.0 14-1 D-1 D-2 TABLES COPY REPLACING Matches Operating System Prompts and Compiler Names Compiler Switches Legal Non-Numeric Elementary Moves Results of the Preceding Sample Statements Results of the Preceding Sample Statements Values Moved into the Receiving Fields Based on the Value in the Sending Field Handling a Sending Field that is Too Short Results of Delimiting with an Asterisk Results of Delimiting Multiple Receiving Fields Results of Delimiting with Two Asterisks Results of Delimiting with ALL Asterisks Results of Delimiting with ALL Double Asterisks Results of the Multiple Delimiters Shown in Figure 3-29 Original, Altered, and Restored Values Resulting from Implicit Redefinition The Resulting ASCII Character from a Sign and Digit Sharing the Same Byte The Sign Tests COBOL File Types I/O Statements Sequential OPEN Modes Bucket Sizes for Record Lengths Relative OPEN Modes Bucket Sizes for Record Lengths Indexed OPEN Modes Device Codes Comparison of PDP-11 Disk Devices Form Control Characters File Specification Switches $KK PSECT Name Suffixes PSECT Name Suffixes Page 2-6 2-9 2-12 3-9 3-18 3-2' 3-22 3-23 3-24 3-25 3-25 3-26 3-26 3-28 3-39 4-7 4-9 6-2 6-2 6-9 6-16 6-19 6-28 6-32 6-37 6-38 6-47 14-11 D-2 D-3 xiii PREFACE The PDP-11 COBOL User's Guide is intended primarily for reference use. It is a companion guide to the PDP-11 COBOL Language Reference Manual. Because it is not a tutorial guide for--beg1nn1ng programmers, you should have a working knowledge of the COBOL language. This guide describes the COBOL file structures: data formats; some of the features of the PDP-11 COBOL Version 4 compiler, error messages generated by the compiler and run-time systems, I/O devices available with the system, some hints on good programming practices, some techniques for debugging source programs, and a description of the PDP-11 COBOL utility programs, Merge and REFORMAT. xv ACKNOWLEDGMENTS COBOL is an industry language and is not the property of any company or group of companies, or of any organization or group of organizations. No warranty, expressed or implied, is made by any contributor or by the CODASYL COBOL Committee as to the accuracy and functioning of the programming system and language. Moreover, no responsibility is assumed by any contributor, or by the committee, in connection therewith. The authors and copyright holders of the copyrighted material used herein are: FLOW-MATIC (trademark of Sperry Rand Corporation), Programming for the UNIVAC (R) I and II, Data Automation Systems copyrighted 1958, 1959, by Sperry Rand Corporation; IBM Commercial Translator Form No. F28-8013, copyrighted 1959 by IBM; FACT, DSI 27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell. They have specifically authorized the use of this material, in whole or in part, in the COBOL specifications. Such authorization extends to the reproduction and use of COBOL specifications in programming manuals or similar publications. Procedures have been established for the maintenance of COBOL. Inquiries concerning the procedures for proposing changes should be directed to the Chairman of the CODASYL COBOL Committee, P.O. Box 124, Monroeville; Pa. 15146. xvi CHAPTER 1 INTRODUCTION The PDP-11 COBOL compiler translates ANS-74 COBOL source programs into relocatable object modules; it runs under the supervision of the following PDP-11 operating systems: e RSTS/E · RSX-llM e IAS To run a COBOL program, you follow a five-step process: · Prepare a source program · Compile a source program · Merge or prepare an overlay description file (optional) · Task-build object modules into an executable task · Execute the task The PDP-11 COBOL compiler accepts COBOL source statements from source input files. This means that you must manually enter your source statements onto an acceptable medium prior to the compilation process. Once you have decided upon an input medium and format for your source input files and have created them, you compile the source program. The PDP-11 COBOL compiler reads source statements from the source input file, translates them into object code modules consisting of program sections (PSECTs), and produces the following files: · Listing (LST) · Object (OBJ) · Overlay Description Language (ODL) The listing file (LST) contains a listing of the source statements in the order in which they were compiled, any diagnostic error messages, and any optional special format listings, e.g., cross-reference listings and data and procedure maps. You obtain special format listings by appending an appropriate switch to the COBOL command line at compile-time. 1-1 INTRODUCTION The object file (OBJ) contains a collection of program sections called PSECTs which are not executable. They must be linked into an executable task image by an operating system task called Task Builder. The ability to compile COBOL subprograms to produce linkable object files independently enables you to create modular programs. The Overlay Description Language (ODL) file contains directives that describe the overlay structure of the object module generated from the COBOL source program. ODL directives are generated into the ODL file for each overlayable object module program section. The compiler can compile only one source program or subprogram per command string execution. Therefore, a program which consists of a main program plus one or more subprograms requires multiple executions of the compiler. Each compilation generates a separate listing, ODL, and object file. The ODL files, in this instance, must be merged together into a single ODL file to be submitted as input to the Task Builder. To accomplish this, you use the Merge Utility, which performs the following functions: 1. Merges the ODL statements from one or more ODL files into a single ODL file 2. Analyzes the I/O requirements for the entire task and provides directives to include the required I/O routines 3. Inserts the missing but required ODL directives not provided by the compiler Whether you have a large segmented program, a main program plus subroutines, or a small stand-alone program, the ODL files generated by the compiler require merging or modification. Task Builder provides you with a facility for linking separately compiled object modules into an executable task image. You can, depending on your knowledge of your operating system and PDP-11 COBOL, link object modules created by another programming language into your COBOL task image. Task Builder also allows you to take full advantage of the COBOL system library to selectively link into your COBOL task only those runtime support routines actually needed to run your task. The Task Builder, using the ODL file as a guide, provides the facility to build large amounts of code into a task by careful use of code segments that overlay each other. Careful use of segmentation or calls to subprograms within your COBOL source program will allow you to compile and execute large and complex COBOL programs. If you add some functionality to an existing COBOL program and find that, after task-building, the resulting task will not fit in memory, you have an alternative other than reprogramming: you can segment the program or make subprograms out of some of the existing procedures, replac ng these procedures with CALL statements to the newly crea ed subprograms. When the source program has been compiled, the ODL f ie merged, and task-building accomplished, the task is ready to be executed. 1-2 INTRODUCTION The task is an executable form of the declarations and instructions represented in your COBOL source programs. It includes input-output routines and other subprograms that were inserted by the Task Builder as a result of your commands or the contents of the ODL file. It also includes the COBOL run-time system, which is a library of predefined routines that perform standard functions for your program, such as arithmetic and data movement. The run-time system is also referred to as the Object-Time System, or OTS. Figure 1-1 shows the process of preparing a COBOL program for execution. COBOL System Utility Programs The PDP-11 COBOL System includes two utility programs: MERGE The Merge Utility merges compiler-generated ODL files into a single ODL file. It also allows you to specify several options in it dialogue. Chapter 2 discusses Merge in detail. REFORMAT PDP-11 COBOL accepts source programs that were coded using either the ANSI ai-column card reference format or the shorter, terminal-oriented PDP-11 reference format. The REFORMAT utility program reads source programs that were coded in the PDP-11 terminal format and converts them to si-column ANSI-compatible source programs. Chapter 8 describes the use of REFORMAT. The two reference formats are discussed in the PDP-11 COBOL Language Reference Manual. 1-3 INTRODUCTION OBJECT MODULE COMPILER (CBL) ODL FILE ODL MERGE UTILITY ODL FILE TASK BUILDER (TKB) LISTING Figure 1-1 Building A COBOL Task Image 1-4 CHAPTER 2 USING THE PDP-11 COBOL SYSTEM This chapter discusses the procedures for creating, compiling and using COBOL programs. The procedure can be described as a 5-step process: 1. Creating or entering source programs. 2. Compiling the source programs to produce object files and Overlay Descriptor Language (ODL) files. 3~ Optionally merging ODL files to produce an ODL file that contains the structural specification for an executable task. 4. Task-building the object modules to produce the executable task. 5. Executing the task and setting optional program switches. 2.1 CREATING A SOURCE PROGRAM This section discusses the selection of a source reference format and the preparation of a source program file for input to the compiler. 2.1.1 Choosing ~ Reference Format The PDP-11 COBOL compiler can accept source programs in either conventional or terminal reference format (both are described in the PDP-11 COBOL Reference Manual). However, it is important to note that you cannot mix reference formats in the same source program (including text copied from a COBOL library). Terminal format was designed to be easily used by programmers at interactive terminals; therefore, the compiler accepts terminal reference format as a default (you can use a compiler switch to specify conventional format). Using terminal format can result in a significant saving of file space used to store COBOL source programs. In addition, you will find that it is usually easier to edit source programs written in terminal format, because spacing requirements are more flexible. 2-1 USING THE PDP-11 COBOL SYSTEM You may want to select the conventional reference format if your COBOL program was originally written that way for another compiler. You can convert a terminal format program to conventional format by using the REFORMAT utility, which is described in Chapter 8. Use REFORMAT to transport a terminal format program to a system that accepts only conventional format. You can also use it to match the formats of source files and COBOL library files if they are not the same. 2.1.2 Entering ~ Source Program Create a source program file from your terminal by using a text editing program that is available on your system; or use a system utility to transfer existing source files from external media. You can also use a text editor to update existing source program files. · 2.2 USING THE LIBRARY FACILITY (COPY) The PDP-11 COBOL library facility allows you to copy COBOL source language text from a library file into your COBOL program during compilation. One COPY statement can include large amounts of library source text in a program, eliminating a great deal of repetitious coding and the errors that often go along with it. The compiler treats the copied text as if it were a part of the source program; however, the copied material does not change the source program file in any way. The COBOL library facility provides two important benefits: 1. Standardization of File and Coding Conventions A data file is usually processed by more than one program. Each of those programs must describe the characteristics of the file, such as file-name, blocking factor and record descriptions. The programs are often written by one programmer, then maintained and updated by another. Because it is often difficult for a programmer to understand a program written by someone else, many organizations design and code standardized file descriptions, then keep them in COBOL libraries; programmers then COPY the file descriptions into their programs, frequently without having to understand (or even know) their details. This technique also applies to Procedure Division code that is used in many different programs. For example, a library could contain a standardized routine to convert calendar dates to Julian dates, or to format standard report headings. 2. Saving Time and Reducing Errors Defining and coding file aQd record descriptions are both time-consuming and error-prone activities. When the descriptions already exist in COBOL libraries, you can easily COPY them into a source program; you save time because you don't have to code them again, and you avoid potential errors in re-entering complex code. 2-2 USING THE PDP-11 COBOL SYSTEM Chang_in_g t:he format of a file is a_nother common time-consuming chore. When a file format changes, you usually must change and recompile all programs that use the file. If the file description is in a COBOL library, only the library must be changed: individual programs often then need only recompilation, since the library coding changes are included by the COPY. Putting commonly used Procedure Division code in libraries yields the same benefits. 2.2.1 Creating~ COBOL Library File Each line of a COBOL library file must form syntactically correct COBOL text when it is merged into the source program. It can meet this condition by being itself syntactically correct or by becoming correct when it is merged with the source program. Library text must conform to the rules for the COBOL source reference format: for example, library text that will appear in Area A of the source program must be in Area A in the library file. You can write library text using either the conventional format or terminal format: however, the library text format must be the same as the source program into which it is merged. 2.2.2 The COPY Statement COPY is a compiler-directing statement that merges a COBOL library file into a COBOL source program. The simplest form of the statement is: COPY text-name. Text-name must be either an alphanumeric literal or a file name. Remember that the COPY statement must end with a terminator period regardless of where it appears in the source program. If you specify a literal, the compiler uses its value as a file specification: therefore, you can include or omit all components of the file specification that are allowed by your operating system, such as device, UIC (or PPN), file type, and version number. The only required component is the file name itself. For example: COPY "DKl: [7,2J]ACCFIL.XYZ:3". causes the compiler to acce~s version number 3 of the file ACCFIL.XYZ in UIC [7,2J] on the device DKl:. If you use a file name in the COPY statement, the compiler uses .LIB as the default file type. For example: COPY ACCOUNT. causes the compiler to access the latest version of the file ACCOUNT.LIB on the default device and UIC. 2-3 USING THE PDP-11 COBOL SYSTEM Only four conditions require the use of the alphanumeric literal to indicate the full file specification for the copy statement: 1. When the file type is other than .LIB. 2. When the library file is not on the default device. 3. When the library file is not in the default directory. ·4. When the default directory contains more than one version of the file want a version other than 1 ;hr::iru ..I ~ . . llJ .... """ ... and ,71"'\11 .I"' .... +-I"\ rtl"\Y"'\"'C7 '-"' ...... "'.I::' .I the latest. This condition cannot occur under RSTS/E, which does not support multiple file versions. Figure 2-1 demonstrates the use of the COPY statement to include Procedure Division code. Note that the format of the library text is maintained when it is included in the source program. COBOL Source Program I I Resulting Source Program PROCEDURE DIVISION. START-PROC SECTION. BEGIN-PROC. ACCEPT TO-DATE FROM DATE. OPEN-FILES. COPY OPENF. OPEN I-0 WORK-FILE. INPUT-LOOP. READ CUST-FILE .·· Library File (OPENF.LIB) * OPEN INPUT CUST-FILE. OPEN I-0 ORDERS. GET-VERSION. DISPLAY "VERSION?". ACCEPT VER-NUM. IF VER-NUM NOT NUMERIC GO TO GET-VERSION. * PROCEDURE DIVISION. START-PROC SECTION. BEGIN-PROC. ACCEPT TO-DATE FROM DATE. OPEN-FILES. COPY OPENF. * OPEN INPUT CUST-FILE. OPEN I-0 ORDERS. GET-VERSION. DISPLAY "VERSION?". ACCEPT VER-NUM. IF VER-NUM NOT NUMERIC GO TO GET-VERSION. * OPEN I-0 WORK-FILE. INPUT- LOOP. READ CUST-FILE ... Figure 2-1 Merging Library Text 2-4 USING THE PDP-11 COBOL SYSTEM The COPY statement can appear anywhere that a COBOL word is allowed in a so-urce prog-ra-m; the-r-e-f-o-r-e, yo-u ca-n use it in rna-n-y w--ay-s -to s--e-lv-e different problems. For example, if a library file called MTG contains the single entry MORTGAGE-PAYMENT-AMOUNT, it could be copied in the Data Division: Source Statement: g3 COPY MTG. PIC 999V99. Resulting Source Statement: g3 MORTGAGE-PAYMENT-AMOUNT PIC 999V99. or in the Procedure Division: Source Statement: MULTIPLY COPY MTG. BY 12 GIVING ANNUAL-PAYMENT. Resulting Source Statement: MULTIPLY MORTGAGE-PAYMENT-AMOUNT BY 12 GIVING ANNUAL-PAYMENT. The periods following the COPY statements in these examples do not become part of the source text. If the library text requires punctuation: it must be included in the library file~ NOTE The two preceding examples are not recommended uses of the COPY statement. They are included only to illustrate the mechanics of the COBOL library facility. 2.2.3 The COPY REPLACING Statement It is sometimes necessary to tailor library file text for use in a particular program. For example, if a record description in a library file has level-numbers incremented by 1 (gl, g2, g3, ... ) and you want them to be incremented by four (gl, gs, ~9, .·· ),you can change the level-numbers as the library text is merged into the source program. During the copying process, the COPY statement can replace all occurrences of a literal or word with an alternate literal or word. For example: COPY ACCTREC REPLACING ~2 BY gs, ~3 BY gg, g4 BY 13. This sample statement causes the compiler to scan the file ACCTREC searching for the character-string ~2. Wherever it finds a g2, the compiler substitutes gs. A match occurs only if the compiler finds a ~2; no match occurs for a g or a 2 alone. The compiler follows the same procedure for occurrences of g3 and g4. The REPLACING character-string can be a literal or a word; it must compare equally, character for character, with the entire character-string in the library text. Table 2-1 illustrates the results of some character-string comparisons. 2-S USING THE PDP-11 COBOL SYSTEM Table 2-1 COPY REPLACING Matches REPLACING Literal or word Library Text Match? "ABC" HRLY-RATE 1 II 2" II 15" ".0'12" 0'12 SUBTRACT ".0'12" ACCT "ABCD" No HRLY-RATE Yes 1 Yes 2 No "15" No "12" No 12 No SUBTRACT Yes II .0'12 II Yes ACCTl No The following examples COPY the library file named NEWSBOY, which contains this text: ,0'1 A. ,0'2 B PIC 99. ,0'2 C PIC 99 VALUE 2. ,0'2 D PIC X(5) VALUE "ABCDE" · .0'2 EPIC 99V99 VALUE 3.75. ,0'2 F PIC 99 VALUE ,0'2. Example .!. Statement: COPY NEWSBOY REPLACING B BY X. Result: .0'1 A · .0'2 x PIC 99. .0'2 c PIC 99 VALUE 2. .0'2 D PIC x (5) VALUE "ABCDE". j2 E PIC 99V99 VALUE 3.75. .0'2 F PIC 99 VALUE .0'2. 2-6 USING THE PDP-11 COBOL SYSTEM Statement: COPY NEWSBOY REPLACING 2 BY 6. Result: .0'1 A· .0'2 B PIC 99 · .0'2 C PIC 99 VALUE 6 . .0'2 D PIC X(5) VALUE "ABCDE" . .0'2 EPIC 99V99 VALUE 3.75 · .0'2 F PIC 99 VALUE .0'2. Example l Statement: COPY NEWSBOY REPLACING .0'2 BY 63. Result: _01 A. 63 B PIC 99. 63 c PIC 99 VALUE 2. 63 D PIC x (5) VALUE "ABCDE". 63 E PIC 99V99 VALUE 3.75. 63 F PIC 99 VALUE 63. Example ! Statement: COPY NEWSBOY REPLACING B BY X, "ABCDE" BY "HIJ", 3.75 BY 4.234. Result: .0'1 A · .0'2 x PIC 99. .0'2 c PIC 99 VALUE 2. .0'2 D PIC x (5) VALUE "HIJ". .0'2 E PIC 99V99 VALUE 4.234. .0'2 F PIC 99 VALUE .0'2. In the third example, level-number .0'2 was changed to level-number 63, which is not legal under COBOL rules; therefore, although both the COPY statement and the library text are syntactically correct, the merged text is incorrect and would generate syntax errors. 2-7 USING THE PDP-11 COBOL SYSTEM 2.2.4 The Source Listing The compiler displays copied library text on the source listing; however, you can suppress this display by using the /NL compiler switch. Depending on how you write the COPY statement, library text can appear either before or after the COPY statement. The compiler normally prints a line of source text when it scans to the end of the line; however, when the compiler recognizes a completed COPY statement before the end of the line, it locates the library file, then: 1. Prints the library text. 2. Scans the rest of the source program line. 3. Prints the entire source line. Thus, if the source line contains a COPY statement followed by other text (including spaces), the compiler prints the library text before the source line containing the COPY statement; this results in a somewhat confusing listing. You can cause the compiler to produce a more readable listing by making sure that you write each COPY statement as the last entry on a source program line. 2.2.5 Common Errors in Using the Library Facility Some of the more common errors to avoid when using the library facility are: · Failing to follow the rules for the COBOL reference format when creating the library file. · Merging a library file in one format (conventional or terminal) with a source program written in the other. · Forgetting to end the COPY statement with a terminator period. · Inadvertently defining data-names in the source program when they are also defined in the library file, thus causing duplicate names. · Writing library file text that becomes syntactically incorrect when it is merged with the source program. · Merging the wrong library file, either because multiple versions exist, or because of misspellings. · Writing source text following the COPY statement on the same line, thus causing confusion in the source program listing. · Forgetting that numeric literals (such as J2, 77, .·· ) used in the REPLACING option replace level-numbers, picture descriptions, and paragraph or section names, when they find matches in the library file. e Forgetting that a period must appear in the library file if it is to appear in the source program; the terminator period that ends the COPY statement is replaced by library text. 2-8 USING THE PDP-11 COBOL SYSTEM The PDP-11 COBOL compiler translates the COBOL text in a source program file into an object module that contains relocatable code, and an Overlay Descriptor Language (ODL) file that contains a structural description of the program. The compiler also produces an optional listing that contains the source statements and other information that you can request by using compiler switches. This section describes the procedure for compiling your source program; it discusses the COBOL command line, compiler switches and the error message summary. Finally, the section lists some common errors to avoid in entering compiler command lines. Appendix G discusses the components of the source program listing. System prompts, COBOL compiler names, and command line formats differ for the three supported operating systems. Table 2-2 shows the system prompt and compiler name for each operating system. Table 2-2 Operating System Prompts and Compiler Names I Operating System System Prompt Compiler Name RSX-llM > CBL IAS RSTS/E PDS> J READY COBOL I COBOL Examples in this section are for the RSTS/E operating system. RSX-llM COBOL command lines are the same except for the compiler name. The IAS COBOL compiler command line format is described in the IAS User's Guide. The compiler switches described in this section can be used on each system. Depending on whether you want to compile a single source program or more than one, you invoke the compiler in one of two ways: 1. To compile a single program, call for the compiler and supply its command line on a single line, followed by a carriage return; when the compilation is finished, the operating system prompt appears. For example: READY COBOL <command line> READY 2-9 USING THE PDP-11 COBOL SYSTEM 2. To compile more than one program during a single execution of the compiler, call the compiler on one line (followed by a carriage return), then enter command lines in response to compiler prompts. When a compilation is finished, the compiler prompts you for the next command line. Enter a CTRL-Z (AZ} when the last program has been compiled: READY COBOL CBL> <command line> CBL> <command line> CBL> <command line> CBL> <command line> CBL> "'z READY 2.3.1 PDP-11 COBOL Command Line The PDP-11 COBOL command line has the following format: <object-file>,<listing-file>=<source-file></switch> ·.. </switch> where: <object-file> is the file specification for the file that is to contain the object module generated by the compiler. <listing-file> is the file specification for the file that is to contain the source program listing. <source-file> is the file specification for the file that contains the COBOL source program to be compiled. </switch> is a compiler switch option, written as a slash (/) followed by one or more ASCII characters. (The next section discusses compiler switches.) You can write each file specification with or without the file type (or extension). If you omit the file type, the compiler assumes the following as defaults: <object-file> OBJ <listing-file> LST <source-file> CBL 2-10 USING THE PDP-11 COBOL SYSTEM You can omit either or hath 0-f the -CO-mp-il.e-r 's out-p.u-t f il-e--s -b--y 0-mitting: the corresponding file specifications from the command line. Consider the following examples: CBL> OBJECT,LIST=SOURCE produces OBJECT.OBJ and LIST.LST and uses SOURCE.CBL. The three files are assumed to be in the default directory on the default device. CBL> OBJECT=[7,2l]SOURCE.CBS produces no listing-file. It uses the source-file SOURCE.CBS in directory [7,21] and produces OBJECT.OBJ in the default directory on the default device. CBL> ,LIST.LSX=SOURCE produces a listing-file (LIST.LSX) on the default device; however, no object-file is produced. The source-file is SOURCE.CBL. CBL> =SOURCE produces no output files at all. The source-file is SOURCE.CBL in the default directory on the default device. The only output of this compilation is the error message summary; however, it will appear only if the compiler detects errors. NOTE The compiler generates an ODL file only if it produces an object file. The ODL file name, device, and PPN (UIC) are the same as those of the object file. 2.3.2 Compiler Switches PDP-11 COBOL provides a series of compile-time switches that you can use to select or suppress compiler options. Table 2-3 summarizes the compiler switches, which are then described in detail. 2-11 USING THE PDP-11 COBOL SYSTEM /ACC:n /-BOU /CM6 /CREF /CSEG:nnnn /CVF' /ERR:n /HELP /KER:kk /MAP /NL /OBJ /-ODL /OV /PFM:nn /-PLT /RO /SYM:n Table 2-3 Compiler Switches Acceptable diagnostics to produce object file Suppress bounds checking COMPUTATIONAL-6 interpretation Cross-reference listing Specify maximum procedural PSECT size Conventional format Diagnostic print suppression Display compiler command line information Specify PSECT kernel name Produce map on listing Suppress listing of library text Print object code locations on listing Suppress ODL file generation Overlay all procedural PSECTS Specify maximum PERFORM nesting Suppress literal pooling Generate read-only PSECTS Add symbol table space /ACC:n /-BOU Causes the compiler to produce an object file only if the source program generates diagnostics with severity numbers equal to or less than n. Acceptable values for n are ~, 1, and 2: ~ Informational diagnostics 1 Warning diagnostics 2 = Fatal diagnostics The default is /ACC:l. Suppresses the generation of code to check that subscripts and indexes are in their legal ranges when they are used. If this switch is not specified, a program's use of an out-of-range subscript or index results in its termination by the OTS. Suppression of bounds checking can increase execution speed for a program that executes a large number of subscripted or indexed data references. The default is /BOU. NOTE If /-BOU is specified and a program uses out-of-range subscripts or indexes, the results are unpredictable. 2-12 USING THE PDP-11 COBOL SYSTEM I /C.M6 causes t-he c·crmptler to interpret COMPUTATIONAL usage as it did in releases prior to Version 4.~. The effect is the same as changing all COMPUTATIONAL references to COMPUTATIONAL-6. NOTE Since COMPUTATIONAL-6 is a temporary data format, intended only for program conversion from PDP-11 COBOL releases prior to Version 4.~, its use for conversion purposes should also be considered temporary. /CREF Produces a cross-reference listing as part of the listing file. Data-names and procedure-names are listed in ascending order with the source program line numbers on which they appear. On the listing, the symbol # indicates the source line on which the name is defined. NOTE The /CREF switch significantly increases the compilation time for large source programs. /CSEG:nnnn Specifies the maximum size for procedural PSECTs to be generated by the compiler; nnnn is a decimal number greater than ii? that specifies the maximum PSECT size in bytes. /CVF Specifies that the source program is in conventional format; the compiler then expects si-character images with optional sequence numbers in character positions 1-6, indicators in position 7, Area A beginning in position 8, Area B beginning in position 12, and the identification area in positions 73-8~. /ERR:n Suppresses the printing of compiler diagnostic messages with severity numbers less than n. Acceptable values for n are ~' 1, and 2: i = Informational diagnostics 1 = Warning diagnostics 2 = Fatal diagnostics You cannot suppress fatal diagnostics. The default is /ERR:~. /HELP Displays information about the compiler command line (including switches) on the default output device. 2-13 USING THE PDP-11 COBOL SYSTEM /KER:kk Specifies a two-character kernel for PSECT names in this compilation. Use this switch when two more object files will be merged into a single task. The Task Builder requires all PSECT names to be unique; specifying different kernels for each object file in the task overrides the compiler's default names and ensures uniqueness. The kernel (kk) is a two-character string that can contain any combination of the letters A-Z and the numbers j-9. /MAP /NL /OBJ Causes the compiler to produce the following maps in the listing file: · Data Division · Procedure Map · External Subprograms Referenced · Data and Control PSECTs · OTS Routines Referenced · Segmentation Map Appendix G contains a description and example of each l map. J ! Suppresses the listing of text copied from library 1 l files; only the COPY statement itself appears in the listing file. T I J I Causes the compiler to list the object location for each verb in the Procedure Division. The location appears on the line before the source line in which the verb is used. /PFM:nn /-PLT Specifies the maximum number of nested PERFORM statements in the program being compiled. The default is lj. Using this switch to specify the exact number of nested PERFORMS causes the compiler to reserve no more memory than necessary for the PERFORM stack. Causes the compiler to suppress literal pooling. As a default (/PLT), the compiler pools literals to minimize the space required to contain them. Depending on PSECT size, literal pooling can also avoid the generation of additional PSECTS that would otherwise result from reaching maximum PSECT size. However, literal pooling increases compile time; you can therefore speed up compilations by using the /-PLT switch. 2-14 USING THE PDP-11 COBOL SYSTEM /RO Ca-us-es the cumpiler to g-enera-te read-nnly ps-E-C-Ts for Procedure Division object modules. The default PSECT access code attribute is read/write. The access code attribute of a PSECT affects its memory allocation by the Task Builder. If your system supports hardware memory protection, specifying read-only PSECTs can help avoid unintentional damage to Procedure Division code, especially if you compile your program with the /-BOU switch. You will find more information about this attribute in your system's Task Builder Reference Manual. NOTE Do not use the /RO switch if you intend to include the COBOL Interactive Debugger (CID) in the task; CID breakpoints require read/write PSECTs. /SYM:n Causes the compiler to reserve more symbol table space for the compilation. The acceptable values for n, which represents the space required for the maximum number of data-names and procedure-names, are 1, 2, 3, and 4: Maximum Maximum n Data-Names Procedure-Names 1 761 2 1.0'21 3 1531 4 2.0'39 761 1,0'21 1531 2,0'39 The default is /SYM:l. 2.3.3 Error Message Summary If the compiler detects any errors during a compilation, it displays an error message summary on the system output device. The error message summary has the following format: CBL -- nnnnn ERROR(S), nnnnn FATAL NOTE If any fatal errors occur, the compiler does not generate an object file unless you use the /ACC:2 switch in the command line. 2-15 USING THE PDP-11 COBOL SYSTEM 2.3.4 Common PDP-11 COBOL Command Line Errors Some of the more common errors to avoid when command lines are: · Omitting the /CVF switch for ~ource conventional format. entering programs PDP-11 COBOL that are in · Including switches that contradict file specifications in the command line, such as using the /MAP switch when no listing-file is specified. · Omitting version numbers from file specifications, causing the compiler to use an unintended version of a file (on IAS and RSX-llM systems) · · Forgetting to use a file type in the file specification when you intend to use or create a file with other than the default file type. · Forgetting to enter a comma when you want only a listing file. For example, CBL> ,A=A produces only a listing file, while CBL> A=A produceS-an object file and an ODL file, but no listing. 2.4 THE COBOL MERGE UTILITY ~- -~~ ~~- The PDP-11 COBOL compiler produces an object file and an Overlay Descriptor Language (ODL) file for each source file. The ODL file contains directives that describe the structure of the associated object modules; it must be supplied to the Task Builder to produce an executable task image that contains overlayable segments. Even when you do not require overlaying, you may want to supply ODL files to the Task Builder to combine several object modules. However, the Task Builder cann9t directly use the compiler-generated ODL files because: 1. The compiler-generated ODL file is not complete; it requires additional ODL directives to include the required I/O routines. 2. The compiler generates an ODL file for each program (and subprogram); thus, multiple ODL files are required when the task consists of a main program that calls one or more subprograms. On the other hand, the Task Builder can accept only a single ODL file; therefore, multiple ODL files must first be merged. The Task Builder can operate on object modules directly only if you do not require overlaying and if only a few object modules combine to produce the executable task. Section 2.5.2 describes this use of the Task Builder. 2-16 USING THE PDP-11 COBOL SYSTEM Assuming that your task is complex or does require overlaying, you must s_uppLy .an DDL fi1-e ta the Ta.sk Builde-r,. In tha-t ca-ser r-eg.a-r-d-l-e-SS of the attributes of your program (and its subprograms), the compiler-generated ODL file{s} require merging or modification before the Task Builder can use them. You can merge or modify these files yourself if you have an in-depth knowledge of: 1) your operating system, 2) ODL file concepts, 3) PDP-11 COBOL segmentation and interprogram communications, and 4) the Task Builder. Chapter 11 (Hand-Tailoring ODL Files) describes the techniques for modifying ODL files yourself. However, the COBOL Merge Utility performs these functions for you quickly and easily in a standardized, systematic way. The Merge Utility has several options that allow you to select features and tailor the resulting ODL file to fit particular needs. For example: 1. You can select either a "merged" or an "abbreviated" output ODL file. The merged ODL file is a concatenation of all the input ODL files (that is, it contains the contents of each file, one directly after the other) followed by Merge-supplied ODL statements: PROGl.ODL statement PROGl.ODL statement PROG2.0DL statement PROG2.0DL statement PROG3.0DL statement PROG3 .ODL statement PROGn.ODL statement PROGn.ODL statement ODL statements supplied by the Merge Utility 2-17 USING THE PDP-11 COBOL SYSTEM The abbreviated ODL file contains indirect command file specifications (one for each input ODL file) followed by Merge-supplied ODL statements: @PROGl.ODL @PROG2.0DL @PROG3.0DL @PROGn.ODL ODL statements supplied by the Merge Utility The merged ODL file takes more file space than the abbreviated ODL file; however, it is a complete ODL file, and the compiler-generated partial ODL files need not be available to the Task Builder. The abbreviated ODL takes less space because it contains indiiect command file specifications; however, because the specifications are essentially pointers to other files, the compiler-generated files must also be available when you use the Task Builder. 2. You can include the COBOL Interactive Debugger (CID) in the executable task. Chapter 13 describes CID and discusses its use. 3. You can overlay I/O routines to reduce the size of the executable task; overlaying may be necessary in some cases to prevent address space overflow. However, if you can avoid overlaying I/O routines, program execution speed will be greater· 4. If you elect to overlay I/O routines, the Merge Utility allows yo~ to tailor I/O for the executable task. Your responses in the Merge dialogue specify options that balance execution speed against memory space. 2.4.1 Using the Merge Utility Invoke the Merge Utility by typing MRG, RUN $MRG, or RUN CBLMRG (depending on your system) in response to a system prompt. Merge guides you through the specification process by asking a series of questions. The dialogue sequence is affected by your answers; therefore, the order can vary from one use of Merge to another. Figures 2-2 and 2-3 show two sample Merge dialogues. For the purposes of this discussion, the dialogue steps are numbered. However, the numbers do not appear in an actual Merge dialogue. 2-18 USING THE PDP-11 COBOL SYSTEM PLEASE ENTER FILE SPECIFICATION FOR OUTPUT FILE ~~- -~- -~ ~~ Respond with a complete or partial file specification for the ODL file that you will supply to the Task Builder. If you enter a partial specification, Merge will assume the default system device and directory, and the file type ODL. For example, if you enter PROGA, the output ODL file will be PROGA.ODL. The specification for this file should not duplicate the name of an input ODL file. Merge opens the output file immediately; using the name of an ODL file that you intend for input will cause that file to be lost (in the case of RSTS/E) or will cause an error later in the session. DO YOU WANT AN ABBREVIATED OR MERGED ODL FILE? PLEASE ANSWE~A(BBREVIATED)~,M(ERGED)' OR--a(ELP) If your response is "A" or "M", Merge generates the output ODL file in one of the formats described earlier. If you enter "H", Merge displays a short description of each type of file. Otherwise, Merge asks for a valid response and waits for more input. DO YOU WANT TO INCLUDE THE COBOL DEBUGGER lf""TT"'I\ ") \'-.L.LJJ· PLEASE ANSWERY (ES) OR N (0) - - If you enter "Y", Merge generates a directive in the ODL file that causes the Task Builder to. include the CID module in your executable task. If you entei an invalid response, Merge prompts you for a correction and waits for more input. Do not include CID if any of the object modules were compiled with the /RO compiler switch; CID breakpoints require read/write procedural PSECTs. CID adds approximately liii (decimal) words to your program's memory address space requirement. If the increase exceeds the program's size limit, you can overlay I/O routines through the Merge dialogue or recompile the program (for debugging purposes only) with the /OV switch. DO YOU WANT TO OVERLAY I/O SUPPORT ROUTINES? PLEASE ANSWERY(ES)' N(O) OR H(ELP) Entering "N" will cause a library of I/O routines (RMSLIB) to be included in your task image. Execution will be faster than if you overlay I/O; however, the included routines could cause your program's maximum size to be exceeded. If you enter "N", Merge continues the dialogue at Step 7. Entering "Y" causes Merge to ask more questions about I/O routine overlaying, allowing you to choose from standard Record Management Services (RMS) ODL files, or to specify your own. As before, an invalid response causes Merge to request a correction. 2-19 USING THE PDP-11 COBOL SYSTEM DO YOU WANT TO USE A DEC-SUPPLIED I/0 OVERLAY STRUCTURE? PLEASE ANSWERY(ES)-; N(O) OR H(ELP)? If you answer "Y", Merge continues the dialogue at Step 7 and includes one of the standard RMS ODL files: Functions All except INDEXED All All Operating System RSX-llM and IAS RSTS/E RMSllS .ODL RMSllX.ODL RMS12X.ODL I I RMSRTS.ODL RMSRTX.ODL RMS12R.ODL Entering "N" allows you to specify your own ODL file to include I/O routines in the next step of the dialogue. If you enter "H", Merge advises you to answer "Y". Unless you have an ODL file to include I/O routines, and it has been tested and verified, you are advised to use one of the default files supplied with your system. © PLEASE ENTER YOUR ODL FILE SPECIFICATION. ~~- -~- -~ ~~ Enter a file specification that includes both file name and file type. If either the file name or file type is missing or invalid, Merge asks you to re-enter the entire file specification. PLEASE ENTER FILE SPECIFICATION FOR INPUT ODL FILE ~~- -~- -~ ~~- -~ ~~ As in Step 1, you can enter a partial or complete file specification. Merge uses the same defaults as before for a partial file specification. After validating the file specification, Merge processes the input ODL file. OBJECT PROGRAM REFERENCED IN ODL FILE IS: (object-file> ~ ~- -~- -~ PLEASE ENTER OBJECT FILE DEVICE AND PPN IN THE FORMAT: DEV: [PR6JECT,PROGRAMMERJ ~ If you enter only a carriage return, the device and PPN (or UIC) for the input object file are the same as the system defaults. However, Merge gives you the option of overriding the defaults by entering other specifications. 2-20 USING THE PDP-11 COBOL SYSTEM ANY MORE ODL FILES? ~AS"EANSWi-R Y (-ES} GR -N-W-) Entering "Y" causes Merge to return to Step 7 to request the name of the next input ODL file. If you enter "N", indicating that all ODL files have been processed, the dialogue continues with: Step l~ if Merge has detected use of indexed file organization, and you specified the default I/O overlay option in Step 5 Step 11 if indexed I/O is not indicated in any of the input ODL files, or if you used a non-default ODL file for overlays DO YOU WANT THE SMALLER OR THE LARGER I/0 ROUTINES? PLEASE ANSWER S(MALLER) ,L(ARGER), OR H(ELP) If you answer "S", Merge includes RMSllX.ODL (for RSX-llM and IAS systems) or RMSRTX.ODL (for RSTS/E systems). The I/O routines take about 9KB of user address space. Entering "L" causes Merge to include one of the larger ODL files: RMS12X.ODL (for RSX-llM and IAS systems) or RMS12R.ODL (for RSTS/E) · These I/O routines take about 12KB of user address space. If you select this option and an "address overflow" condition is detected during task-building, merge the ODL files again and enter "S" to try reducing the size of the task. If you are not sure which set of routines ~o specify, enter "L"; selecting the larger I/O overlay may increase your program's execution speed. @ ODL FILE MERGE COMPLETE MERGEi)QDL FILE IS: <output-ODL-file> Merge tells you the name of the ODL file it created, which is the name that you entered in Step 1. If you entered a file specification without a file type, the actual file specification includes the default file type, ODL. After displaying this message, Merge terminates. You are then ready to use the Task Builder to create an executable task image. 2-21 USING THE PDP-11 COBOL SYSTEM Figure 2-2 Merge Dialogue Using Multiple Object Modules and Default I/O Overlaying MRG PLEASE ENTER FILE SPECIFICATION FOR OUTPUT FILE PAYROL DO YOU WANT AN ABBREVIATED OR MERGED ODL FILE? PLEASE ANSWERA(BBREVIATED)-,-M(ERGED)' OR~P) A DO YOU WANT TO INCLUDE THE COBOL DEBUGGER (CID)? PNLOEASE ANSWER-Y(E-S)-O-R - N- (O)-- DO YOU WANT TO OVERLAY I/0 SUPPORT ROUTINES? PyLEASE ANSWER- Y(E- S) - OR-N(- O) DO YOU WANT TO USE A DEC-SUPPLIED I/O OVERLAY STRUCTURE? PLEASE ANSWE~Y(ES)~ N(O)' OR H(EL~ YES -- - PLEASE ENTER FILE SPECIFICATION FOR INPUT ODL FILE PAYRLl.ODL - - -- -- -- --- OBJECT FILE REFERENCED IN ODL FILE IS: PAY"RLI:OBJ - - -- -- PLEASE ENTER OBJECT FILE DEVICE AND PPN IN THE FORMAT: DEV: [PR0JECT,PROGRAMMER] - <CR> ANY MORE ODL FILES? PLEASEJ\NSWER Y(ES) OR N(O) y ----- PLEASE ENTER FILE SPECIFICATION FOR INPUT ODL FILE PAYRL2 - - - - -- - - -- --- OBJECT FILE REFERENCED IN ODL FILE IS: PAY'RE2:0BJ - -- -- -- I 1 PLEASE THE ENTER FORMAT: OBJECT DEV: FILE DEVICE AND PPN [PROJECT, PROGRAMMER] IN <CR> ANY MORE ODL FILES? PNLOEASEJ\NSWER - Y(E- S) -OR-N(- O) DO YOU WANT THE SMALLER OR THE LARGER I/0 ROUTINES? PLEASE ANSWER S(MALLER),~(ARGER), OR Ff1ELP) L ODL FILE MERGE COMPLETE MERGEDC5DL FILE IS: PAYROL 2-22 USING THE PDP-11 COBOL SYSTEM Figure 2-3 M-erg-e Dialog-ue U-Sing One Object M..-0-d-ule and No I/O Overlaying MRG PLEASE ENTER FILE SPECIFICATION FOR OUTPUT FILE PRSNEL.ODL - - DO YOU WANT AN ABBREVIATED OR MERGED ODL FILE? PLEASE ANSWERA(BBREVIATED)-,M(ERGED) I OR~P) A DO YOU WANT TO INCLUDE THE COBOL DEBUGGER (CID)? PLEASE ANSWERY (ES) OR N ( 0 ) - - NO DO YOU WANT TO OVERLAY I/0 SUPPORT ROUTINES? PLEASE ANSWERY(ES) OR N(O) N ----- PLEASE ENTER FILE SPECIFICATION FOR INPUT ODL FILE PERSNL.ODL - - -- - - -- --- OBJECT FILE REFERENCED IN ODL FILE IS: PER~OBJ - -- --- -- PLEASE -ENTER OBJECT FILE DEVICE AND PPN IN <CRTH>E FORMAT: DEV: [PR6JECT-,P-R- O-G-R-AMMER] - ANY MORE ODL FILES? PLEASE ANSWER Y(ES) OR N(O) N ODL FILE MERGE COMPLETE MERGE5C5DL FILE IS: PRSNEL.ODL 2.4.2 Merge Utility Error Messages When the Merge Utility detects an error, it displays an error message, then waits for another entry from you if it can recover from the error. The error messages are self-explanatory in most cases; this section lists Merge error messages that require further explanation. THIS ODL FILE CONTAINS A ;COBMAIN LINE A ;COBMAIN LINE HAS ALREADY OCCURRED THIS ODL FILE IS IGNORED A ;COBMAIN line in an ODL file identifies the object program as a main program. A task image can contain only one main program; therefore, Merge ignores the ODL file. If you specified the incorrect ODL file, continue the dialogue by entering the correct file specification. It is possible that the PROCEDURE DIVISION USING phrase was omitted from the subprogram that is referenced in the ODL file; in that case, change the program, recompile it, and use the Merge Utility again. Of course, this condition could also exist in an ODL file that was incorrectly modified. 2-23 USING THE PDP-11 COBOL SYSTEM MULTIPLE ;COBKER HEADER LINE DETECTED THIS ODL FILE IS IGNORED The ;COBKER line in an ODL file specifies the two-character kernel that particularizes PSECT names in the referenced object file. Only one ;COBKER line is allowed; therefore, Merge ignores the ODL file. The most likely cause for this condition is incorrect modification of the ODL file. MULTIPLE ;COBOBJ HEADER LINE DETECTED THIS ODL FILE IS IGNORED The ;COBOBJ line identifies the object file for which the ODL file is produced. Merge assumes that the ODL file is incorrect because a compiler-generated ODL file contains only one ;COBOBJ header line. NOT STANDARD COBOL ODL FILE FILE IS IGNORED The ODL file contains nonstandard ODL lines. The file was probably modified incorrectly. OPEN UNSUCCESSFUL The Merge Utility could not open a file for one of the following reasons: 1. The device is not on line. 2. The device is not mounted. 3. A hardware failure occurred. 4. The file does not exist on the device. 5. Access to the file is not allowed. Determine and correct the condition; then, invoke the Merge Utility again. 2-24 USING THE PDP-11 COBOL SYSTEM READ ERROR -- MUST ABORT The Merge Utility encountered an unrecoverable error while attempting to read the input ODL file. Merge terminates after closing the input and output ODL files. The error occurred for one of the following reasons: 1. The device is not on line. 2. The device is not mounted. 3. A hardware failure occurred. 4. The volume is full. Determine and correct the condition; execute the Merge Utility again. then, 2.5 TASK-BUILDING PDP-11 COBOL PROGRAMS Compiler-generated object modules contain relocatable code; they must be linked by the Task Builder (TKB) to create executable task images. The Task Builder's input can be either: a) a single ODL file, or b) one or more object files and one or more library files. On RSTS/E and RSX-llM systems, invoke the Task Builder by entering TKB. The Task Builder displays the prompt, TKB> and waits for you to enter a TKB command line. The next two sections discuss two forms of the TKB command line, each of which corresponds to one of the input file options just mentioned. Section 2.5.3 summarizes the factors that determine program task size. On IAS systems, enter the command line as described in the next two sections. 2.5.1 Using ODL-File Input You must supply an ODL file to TKB if you want overlaying in the task image. However, you can use TKB with an ODL file regardless of overlay requirements. The ODL file, which the Merge Utility created or which the compiler generated and you modified, contains directives to TKB; the directives cause TKB to include component object modules and library modules and to create an executable image with a specified overlay structure. 2-25 USING THE PDP-11 COBOL SYSTEM RSTS/E and RSX-llM Users: When the TKB prompt appears, enter the command line in the following format: <task-file>,<map-file>=<ODL-file>/MP where: <task-file> is the file specification for the task image file to be generated. If you do not specify a file type, TKB uses the default extension, TSK. <map-file> is the file specification for the file to contain the optional map listing. If you omit the file type, TKB uses the default extension, MAP.- If you do not want a map file, do not enter either the comma or the file specification. <ODL-f ile> is the file specification for the input ODL file. If you do not specify a file type, TKB assumes the default extension, ODL. /MP is the required switch that identifies the preceding file specification as an ODL file. The Task Builder validates the contents of the command line. If it detects no errors, TKB displays the following message and prompt: ENTER OPTIONS: TKB> NOTE The Task Builder may display the TKB> prompt after you enter the command line. You can continue with the dialogue by entering a slash (/), or you can end the dialogue by entering two slashes (//) if you do not want to specify any TKB options. The RSTS/E user enters HISEG=RMSll, which causes TKB to associate the task image with the RSTS/E RMSll run-time system. TKB then again displays its prompt: TKB>. At this point, enter // to end the dialogue; or enter other options followed by // when you have entered all options and a new prompt appears. 2-26 USING THE PDP-11 COBOL SYSTEM NQTE The most likely options you will use are UNITS and ASG. Your system's Task Builder Reference Manual describes all TKB options. Consider the following example of running TKB on a RSTS/E system: READY TKB TKB> PAYROL,PAYPRG=PAYROL/MP ENTER OPTIONS: TKB> HISEG=RMSll TKB> UNITS=9 TKB> ASG=SY:7,9,MT1:8 TKB> II READY This dialogue causes TKB to use the ODL file, PAYROL.ODL, to produce a task image, PAYROL.TSK, and a map in file PAYPRG.MAP. The UNITS option specifies that the task image requires three additional logical units (LUNs); six is the default. The ASG option assigns LUNs 7 and 9 to the system disk and LUN 8 to magtape 1. IAS Users: On IAS systems, enter the LINK command: LINK/OVERLAY:<ODL-file>/MAP:<map-file>/TASK:<task-file> If you do not include the /TASK qualifier, the Task Builder generates a task file with the same name as the ODL file and the default extension, TSK. If you omit the /MAP qualifier, the Task Builder produces no map file. Use the /OPTIONS qualifier to enter Task Builder options. The IAS Task Builder Reference Manual describes all qualifiers and options. 2.5.2 Using Object-File Input The Task Builder can use object files and library files directly (without an ODL file) if you do not need segment overlaying in the task image. Therefore, you can sometimes bypass the Merge Utility process by using the Task Builder as described in this section. 2-27 USING THE PDP-11 COBOL SYSTEM RSTS/E and RSX-llM Users: Enter the TKB command line in the following format: <task-file>,<map-file>=<object>,<object>, ··· ,LB:CID,LB:COBLIB/LB,LB:RMSLIB/LB where: <task-file> is the file specification for the task image file to be generated. If you do not specify a file type, TKB uses the default extension, TSK. <map-file> is the file specification for the file to contain the optional map listing. If you omit the file type, TKB uses the default extension, MAP. If you do not want a map f·ile, do not enter the comma or the file specification. <object> is a file specification for the files containing the object modules to be linked. You can enter one or more object file specifications. If you omit the file type, TKB assumes the default object file extension, OBJ. LB:CID is the file specification for the optional COBOL Interactive Debugger (CID) · It must appear before the COBLIB specification if you wish to include CID. LB:COBLIB is the file specification for the COBOL library file, which contains the COBOL object-time system (OTS). LB :RMSLIB is the file specification for the RMS-11 library file, which contains the RMS I/O routines. /LB is the Task Builder switch that identifies the preceding file as a library file. After you enter the command line, the dialogue continues as described in Section 2.5.1. NOTE For RSX-llM use~s, the format of the command line is the same, except that "LB:" is replaced by "[1,1]". 2-28 USING THE PDP-11 COBOL SYSTEM IAS Users: Enter the Task Builder command line in the following format: LINK <object>,<object>, .·· ,LB: [l,l]CID,LB:[l,l]COBLIB/LIBRARY,RMSLIB/LIBRARY You can enter the /MAP and /OPTIONS qualifiers as described in Section 2.5.1. The IAS Task Builder Reference Manual describes all qualifiers and options. 2.5.3 Program Task Size The size of a COBOL object module generated from a COBOL source file depends on the memory requirements for the following components: 1. Data items in the Working-Storage Section. 2. Number of files in the File Section. 3. Amount of code generated for the Procedure Division. 4. Number and length of all unique numeric and non-numeric literals used in the Procedure Division. 5. Total size of all run-time modules needed for the program. These include arithmetic support, I/0 support, and segmentation support. 6. Stack space needed to support the executable code. 7. Directories for all referenced data items and literals. If your COBOL program exceeds the memory storage size limit, the Task Builder displays a diagnostic message and does not produce an executable task. You can reduce the memory requirement by: 1. Overlaying sections of the program by using the COBOL segmentation facility (See Chapter 9, Segmentation). 2. Overlaying I/O routines (or choosing the smaller I/O routine option) in the Merge Utility dialogue, as described earlier in this chapter. 3. Using the Merge Utility if you have not done so. Program size is sometimes reduced because of the techniques that Merge uses to include run-time routines. 2.6 EXECUTING A COBOL TASK When the object modules have been linked (task-built) to create an executable task image, you can use the RUN command to execute the task. If you specified SWITCH ON or OFF in the SPECIAL-NAMES paragraph of any COBOL sour~e program in the run unit, the OTS prompts you to set the switches as soon as execution begins. 2-29 USING THE PDP-11 COBOL SYSTEM 2.6.1 The RUN Command ~- -~ Enter the RUN command in response to a system prompt: READY RUN <task-file> where <task-file> is the file specification for the task image. 2.6.2 Setting Program Switches PDP-11 COBOL programs can test the ON/OFF status of up to 16 switches to determine logic paths. The switches are specified in the SPECIAL-NAMES paragraph in the Environment Division. When the task begins execution, the OTS displays the following message: SPECIFY "ON" SWITCHES You can enter a list of switch numbers (separated by commas, spaces, or tab characters) or an asterisk (*). Enter a list of switch numbers to set specific switches; enter an asterisk (*) to set all switches. For example: 2,7,16 sets switches 2, 7, and 16 * sets all switches (1-16) 2-30 CHAPTER 3 NON-NUMERIC CHARACTER HANDLING 3.1 INTRODUCTION COBOL programs hold their data in fields whose sizes are described in their source programs. These fields are thus "fixed" during compilation to remain the same size throughout the lifespan of the resulting object program. The data descriptions of the fields in a COBOL program describe them as belonging to any of three data classes -- alphanumeric, alphabetic, or numeric class. Numeric class data items contain only numeric values, alphabetic class only A-Z and space, but alphanumeric class data items may contain values that are all alphabetic, all numeric, or a mixture of alphabetic bytes, numeric bytes, or, in fact, any character from the ASCII character set. Further, these three classes are subdivided into five categories: alphabetic, numeric, numeric edited, alphanumeric edited, and alphanumeric. Every elementary item except for an index data item belongs to one of the classes and further to one of the categories. The class of a group item is treated at object time as alphanumeric regardless of the classes of subordinate elementary items. For alphabetic and numeric (data items) class and category are synonymous. An alphabetic field is a field declared to contain only alphabetic (A-Z and space) characters. An alphanumeric class field that is declared to contain any ASCII character is called an alphanumeric category field. If the data description of an alphanumeric class field specifies that certain editing operations will be performed on any value that is moved into it, that field is called an alphanumeric or numeric edited category field. When reading the following sections of this chapter, this distinction between the class or category of a data item and the actual value that the item contains should always be kept in mind. Sometimes the text refers to alphabetic, alphanumeric, and alphanumeric edited data items as non-numeric data items. This is to distinguish them from items that are specifically described as numeric items. Regardless of the class of an item, it is usually possible to store a valu~ in the item, at object time, that is "illegal". Thus, non-numeric ASCII characters can be placed into a field described as numeric class, and an alphabetic class field may be loaded with non-alphabetic characters. 3-1 NON-NUMERIC CHARACTER HANDLING To increase readability, the following sections occasionally omit the word "class" when describing an item; however, the reader should regard the descriptive word, numeric, alphabetic, or alphanumeric, as referring to the class of an item unless it applies specifically to the value in the item. This chapter discusses non-numeric class data and the non-arithmetic, non-input-output operations that manipulate this typ~ of data. 3.2 DATA ORGANIZATION Usually, the data areas in a COBOL program are organized into group items with subordinate elementary items. A group item is a data item that is followed by one or more dat~ items (elementary items) with higher valued level numbers. An elementary item has no higher valued subordinate level number. All of the data areas used by COBOL programs (except for certain registers and switches) must be described in the Data Division of the source program. The compiler allocates memory space for these fields and fixes them in size at compilation time. The following sub-sections (3.2.1 and 3.2.2) discuss, on a general level, how the compiler handles group and elementary data items. 3.2.1 Group Items The size of a group item is the total size of the data area occupied by its subordinate elementary items. The compiler considers group items to be alphanumeric DISPLAY items. Thus, the software manipulates group items as if they had been described as PIC X() items, and ignores the structure of the data contained within them. 3.2.2 Elementary Items The size of an elementary item is determined by the number of allowable symbols it contains that represent character positions. For example, consider the following fields: 01 TRANREC. 03 FIELD-1 PIC X(7). 03 FIELD-2 PIC S9(5)V99. Figure 3-1 Field Sizes Both fields consume seven bytes of memory; however, FIELD-1 contains seven alphanumeric bytes while FIELD-2 contains decimal digits and an operational sign. Although certain verbs handle these two classes of data differently, the data, in either case, occupies seven bytes of PDP-11 memory. COBOL operations on such fields are independent of the mapping of the field into PDP-11 memory words (16-bit words that hold two 8-bit bytes). Thus, a field may begin in the left or right-hand byte of a word with no effect on the function of any operations that may refer to that field. 3-2 NON-NUMERIC CHARACTER HANDLING In effect, the compiler sees memory as a continuous array of bytes, not words. This becomes particularly important when declaring a table with the OCCURS clause (see Chapter 5, Table Handling}. Records (a 01 level entry and all of its subordinate entries} and data items that have a level number of 77 and all literal values given in the Procedure Division automatically begin on even byte addresses. I/O verbs require that records be aligned on word boundaries because the PDP-11 COBOL file system reads and writes integral numbers of words. Non-input-output verbs do not require alignment of the data. However, when two fields are aligned identically, the processing verb can sometimes increase its efficiency by processing them a word at a time rather that a byte at a time. In all cases, automatic word alignment of literals, records, and/or 77 items increase the opportunity for more efficient processing. 3.3 SPECIAL CHARACTERS COBOL allows the user to manipulate any of the 128 characters of the ASCII character set as alphanumeric data even though many of the characters are control characters, which usually control input/output devices. Generally, alphanumeric data manipulations are performed in a manner that attaches no "meaning" to an 8-bit byte. Thus, the user can move and compare these control characters in the same manner as alphabetic and numeric characters. Although the object program can manipulate all ASCII characters, certain control characters cannot appear in non-numeric literals since the compiler uses them to delimit the source text. Further, the keyboards of the console and keypunch devices have no convenient input key for many of the special characters, thus making it difficult to place them into non-numeric literals. Special characters may be placed into data fields of the object program by placing the binary value of the special character into a numeric COMP field and redefining that field as alphanumeric DISPLAY. Consider the following example of redefinition. (Keep in mind that the even byte of a word corresponds to the low-order bits of a binary word.) 01 LF-COMP PIC 999 COMP VALUE 10. 01 LF REDEFINES LF-COMP PIC X. 01 HT-COMP PIC 999 COMP VALUE 9. 01 TAB REDEFINES HT-COMP PIC X. 01 CR-COMP PIC 999 COMP VALUE 13. 01 CR REDEFINES CR-COMP PIC X. Figure 3-2 Redefining Special Characters The sample coding in Figure 3-2 introduces each character as a 1-word COMP item with a decimal value, then redefines it as a single byte. (The second byte of the redefinition need not be described at the 01 level, since redefinition at this level does not require identically sized fields.) 3-3 NON-NUMERIC CHARACTER HANDLING The following ASCII code chart may be used to determine the decimal value for any ASCII character. To use the chart, find the desired character; then add its row and column values together to determine the decimal integer to be supplied as a VALUE for the computational i tern. ~ e 000 w e 008 016 024 032 040 048 056 064 0 NUL BS OLE CAN space ( 0 8 @ 1 2 SOH STX HT DC1 EM LF DC2 SUB .!. ) * 1 9 2 : A B 3 ETX VT DC3 ESC # + 3 ; c 4 EOT FF DC4 FS $ 4 < D 5 ENO CR NAK GS % 5 = E 6 ACK so SYN RS & 6 > F 7 BEL SI ETB us apos I 7 ? G 072 080 088 096 104 112 120 H p x grave h p x I a y a i q y J R z b j r z K s [ c k s I L T \ d I t I M u 1 e m u I N v (t) f n v (E~) 0 w (!:) g 0 w DEL Figure 3-3 ASCII Code Chart 3.4 TESTING NON-NUMERIC FIELDS 3.4.1 Relation Tests An IF statement that contains a relation condition (greater-than, less-than, equal-to, etc.} can compare the value in a non-numeric data item with another value and use the result to alter the flow of control in the program. An IF statement with a relation condition compares two operands, either of which may be an identifier or a literal, except that both cannot be literals. If the relation exists between the two operands, the relation condition has a truth value of true. Figure 3-4 illustrates the general format of a relation condition. (The relational characters ">!" "<t" and "=," although required, are not underlined to avoid confusion with other symbols such as greater-than-or-equal-to.} l (IS [NOT] GREATER THAN f({IS '~~~n~~~i~r-1 Ji~ [NOT] [NOT] LESS THAN EQUAL TO ).Lii:.era.L-.L 'arithrnetic-expression-1' IS [NOT] fNOTl -> < f~. ~:~==.~=.~r- 2 t ()..1....1..1..C:..LQ...L-"' ( {arithrnetic-expression-2J IS (NOTJ J Figure 3-4 Relation Condition 3-4 NON-NUMERIC CHARACTER HANDLING When coding a relational operator, leave a space before and after each reserved word. When the reserved word NOT is present, the software considers it and the next key word or relational character to be one relational operator that defines the comparison. Figure 3-5 shows the meanings of the relational operators. OPERATOR MEANING IS [NOT] GREATER THAN IS [NOT] > The first operand is greater than (or not greater than) the second operand. IS [NOT] LESS THAN IS [NOT] < The first operand is less than (or not less than} the second operand. IS [NOT] EQUAL TO IS [NOT] = The first operand is equal to (or not equal to) the second operand. Figure 3-5 The Meanings of the Relational Operators 3.4.1.1 Classes of Data - COBOL allows comparison of both numeric ciass operands and non-numeric ciass operands; however, it handles each class of data slightly differently. For example, it allows a comparison of two numeric operands regardless of the formats specified in their respective USAGE clauses, but requires that all other comparisons (including comparisons of any group items) be between operands with the same usage. It compares numeric class operands with respect to their algebraic values and non-numeric (or a numeric and a non-numeric) class operands with respect to a specified collating sequence. If only one of the operands is numeric, it must be an integer data item or an integer literal and it must be DISPLAY usage; further, the manner in which the software handles numeric operands depends on the non-numeric operand. Consider the following two types of non-numeric operands: 1. If the non-numeric operand is an elementary item or a literal, the software treats the numeric operand as if it had been moved into an alphanumeric data item (which is the same size as the numeric operand) and then compared. This causes any operational sign, whether carried as a separate character or as an overpunch, to be stripped from the numeric item; thus, it appears to be an unsigned quantity. In addition, if the picture-string of the numeric item contains trailing P characters indicating that there are assumed integer positions that are not actually present, these are filled with zero digits during the operation of stripping any sign that is present. Thus, an item with a picture-string of S9999PPP is moved to a temporary location where it is described with a picture-string of 9999999. If its value is 432J (-4321}, the value in the temporary location will be 4321000. The numeric digits, stored as ASCII bytes, take part in the comparison. 2. If the non-numeric operand is a ~roup item, the software treats the numeric operand as 1f 1t had been moved into a group item (which is the same size as the numeric operand) and then compared. This is equivalent to a "group move". The software ignores the description of the numeric field (except for length} and, therefore, includes any operational sign, whether carried as a separate character or as an 3-5 NON-NUMERIC CHARACTER HANDLING overpunch, in its length. (Overpunched char acter s are never ASCII numeric digits, but characters in the range of from A through R, {, or }.) Thus, the sign and the digits, stored as ASCII bytes, take part in the comparison, and zeroes are not supplied for P characters in the picture-string. The compiler will not accept a comparison between a non-integer numeric operand and a non-numeric operand, and any attempt to compare these two items will cause a diagnostic message at compile time. 3.4.1.2 The Comparison Operation - If the two operands are acceptable, the software compares them byte for byte starting at their left-hand end. It proceeds from left to right, comparing the characters in corresponding character positions until it either encounters a pair of unequal characters or reaches the right-hand end of the longer operand. If the software encounters a pair of unequal characters, it considers their relative position in the collating sequence. The operand with the character that is positioned higher in the collating sequence is the greater operand. If the operands have different lengths, the comparison proceeds as though the shorter operand were extended on the right by sufficient ASCII spaces (040) to make them both the same length. If all of the pairs of characters compare equally, the operands are equal. 3.4.2 Class Tests An IF statement that contains a class condition (NUMERIC or ALPHABETIC) can test the value in a non-numeric data item (USAGE DISPLAY only) to determine if it contains numeric or alphabetic data and use the result to alter the flow of control in the program. Figure 3-6 illustrates the general format of a class condition. If the data item consists entirely of the ASCII characters 0123456789 with or without the operational sign, the class condition would determine that it is NUMERIC. If the item consists entirely of the ASCII characters A through z and space, the class condition would determine that it is ALPHABETIC. identifier IS [NOT] ~NUMERIC } (ALPHABETIC o.;n.,vo. "l_t:: v .L .L.'j\..l.L. ti;; ..J Class Condition, General Format 3-6 NON-NUMERIC CHARACTER HANDLING When the reserved word, NOT, is present, the software considers it and the next key word as one class condition that defines the class test to be executed; for example, NOT NUMERIC is a truth test for determining if an operand contains at least one non-numeric byte. If the item being tested was described as a numeric data item, it may only be tested as NUMERIC or NOT NUMERIC. (For further information on using class conditions with numeric items, see Chapter 4.) The NUMERIC test cannot examine an item that was described either as alphabetic or as a group item containing elementary items whose data descriptions indicate the presence of operational signs. 3.5 DATA MOVEMENT COBOL provides three statements (MOVE, STRING, and UNSTRING) that perform most of the data movement operations required by business-oriented programs. The MOVE statement simply moves data from one field to another. The STRING statement concatenates a series of sending fields into a single receiving field. The UNSTRING statement disperses a single sending field into multiple receiving fields. Each has its uses and its limitations. This section discusses data movement situations which take advantage of the versatility of these statements. The MOVE statement handles the majority of data movement operations on character strings. However, the MOVE statement has limitations in its ability to handle multiple fields; for example, it cannot, by itself, concatenate a series of sending fields into a single receiving field or disperse a single sending field into several receiving fields. Two MOVE statements will 1 however, bring the contents of two fields together into a third (receiving) field if the receiving field has been "subdivided" with subordinate elementary items that match the two sending fields in size. If other fields are to be concatenated into the third field and they differ in size from the first two fields, then the receiving field will require additional subdivisions (through redefinition). Another method of concatenation with the MOVE statement is to subdivide the receiving field into single character fields, creating a "table" of a single character field that occurs as many times as there are characters in the receiving field, and execute a data movement loop which moves each sending field, a character at a time, using a subscript that moves continuously across the receiving field. Two MOVE statements can also be used to disperse the contents of one sending field to several receiving fields. The first MOVE statement can move the left-most end of the sending field to a receiving field; then the second MOVE statement can move the right-most end of the sending field to another receiving field. (The second receiving field must first be described with the JUSTIFIED clause.} Characters from the middle of the sending field cannot easily be moved to any rece1v1ng field without extensive redefinitions-of the sending field or a character-by-character movement loop {as with concatenation). The concatenation and dispersion limitations of the MOVE statement are handled quite easily by the STRING and UNSTRING statements. The following sections (3.6, 3.7, and 3.8) discuss these three statements in detail. 3-7 NON-NUMERIC CHARACTER HANDLING 3.6 THE MOVE STATEMENT The MOVE statement moves the contents of one field into another. The following illustration shows the two formats of the MOVE statement. Format 1 MOVE FIELDl TO FIELD2 Format 2 MOVE CORRESPONDING FIELDl TO FIELD2 NOTE Format 2 is discussed in Section 3.6.6. FIELDl is the name of the sending field and FIELD2 is the name of the rece1v1ng field. The statement causes the software to move the contents of FIELDl into FIELD2. The two fields need not be the same size, class, or usage; and they may be either group or elementary items. If the two fields are not the same length, the software will align them on one end or the other and will truncate or pad (with spaces) the other end. The movement of group items and non-numeric elementary items is discussed below. A point to remember when using the MOVE statement is that it will alter the contents of every character position in the receiving field. 3.6.1 Group Moves If either the sending or rece1v1ng field is a group item, the software considers the move to be a group move. It treats both the sending and receiving fields in a group move as if they were alphanumeric class fields. If the sending field is a group item and the receiving field is an elementary item, the software ignores the receiving field description (except for the size description, in bytes, and any JUSTIFIED clause); therefore, the software conducts no conversion or editing on the receiving field. 3.6.2 Elementary Moves If both fields of a MOVE statement are elementary items, their data description clauses control their data movement. (If the receiving field was described as numeric or numeric edited, the rules for numeric moves -- see Chapter 4, Numeric Character Handling -- control the data movement.) The following table shows ithe legal (and illegal) non-numeric elementary moves. 3-8 NON-NUMERIC CHARACTER HANDLING Table 3-1 L-eg-al Ne-a-Nu-me-r ic El-eme--ntary M-0-v-e-s SENDING FIELD CATEGORY RECEIVING FIELD CATEGORY ALPHABETIC ALPHANUMERIC ALPHANUMERIC EDITED ALPHABETIC Legal Legal ALPHANUMERIC Legal Legal ALPHANUMERIC EDITED Legal Legal NUMERIC INTEGER (DISPLAY ONLY) Illegal Legal NUMERIC EDITED Illegal Legal In all of the legal moves shown above, the software treats the sending field as thouqh it had been described as PIC X(). If the sending field description contains a JUSTIFIED clause, the clause will have no effect on the move. If tne sending field picture-string contains editing characters, the software uses them only to determine the field's size. Numeric class data must be in DISPLAY (byte) format and must be an integer. If the description of the numeric data item indicates the presence of an operational sign (either as a character or an overpunch} or if there are P characters in the picture-string of the numeric data item, the software first moves the item to a temporary location. During this move, it removes the sign and fills out any P character positions with zero digits. It then uses the temporary value (which may be shorter than the original if a separate sign were removed, or longer if P character positions were filled in with zeroes) as the sending field as if it had been described as PIC X(), that is, as if its category were alphanumeric. If the sending item is an unsigned numeric class field with no P characters in its picture-string, the software does not move the item to a temporary location. A numeric integer data item sending justification of the receiving field. shorter than the receiving field, the field with spaces. field has no effect on the If the numeric sending field is software fills the receiving In legal, non-numeric elementary moves, the rece1v1ng field actually controls the movement of data. All of the following items, in the receiving field, affect the move: (1) the size, (2) the presence of editing characters in its description, and (3) the presence of the JUSTIFIED RIGHT clause in its description. The JUSTIFIED clause and editing characters are mutually exclusive; therefore, the two classes are discussed separately below. When a field that contains no editing characters or JUSTIFIED clause in its description is used as the receiving field of a non-numeric elementary MOVE statement, the statement moves the characters by starting at the left-hand end of the fields and scanning across, character-by-character to the right. If the sending item is shorter 3-9 NON-NUMERIC CHARACTER HANDLING than the receiving item, the software fills the remaining character positions with spaces. 3.6.2.1 Edited Moves - Alphabetic or alphanumeric fields may contain editing characters. Consider the following insertion editing characters. Alphabetic fields will accept only the B character; however, alphanumeric fields will accept all three characters. B blank insertion position 0 zero insertion position I slash insertion position. When a field that contains an insertion editing character in its picture-string is used as the receiving field of a non-numeric elementary MOVE statement, each receiving character position that corresponds to an editing character receives the insertion byte value. Figure 3-7 illustrates the use of such symbols with the statement, MOVE FIELD! TO FIELD2. (Assume that FIELD! was described as PIC X(7).) FIELD2 FIELD! PICTURE-STRING CONTENTS AFTER MOVE 070476 XX/99/XX 07/04/76 04JUL76 99BAAAB99 04 JUL 76 2351212 XXXBXXXX/XX/ 235 1212/ I 123456 OXBOXBOXBOX 01 02 03 04 Figure 3-7 Data Movement with Editing Symbols Data movement always begins at the left end of the sending field, and moves only to the byte positions described as A, 9, or X in the receiving field picture-string. When the sending field is exhausted, the software supplies space characters to fill any remaining character positions (not insertion positions) in the receiving field. If the receiving field becomes exhausted before the last character is moved from the sending field, the software ignores the remaining sending field characters. 3.6.2.2 Justified Moves - A JUSTIFIED RIGHT clause in the data description of the receiving field causes the software to reverse its usual data movement conventions. (It starts with the right-hand characters of both fields and proceeds from right to left.) If the sending field is shorter than the receiving field, the software fills the remaining left-hand character positions with spaces. Figure 3-8 illustrates various data description situations for the statement, MOVE FIELD! TO FIELD2, with no editing. 3-10 NON-NUMERIC CHARACTER HANDLING FIELDl FIELD2 PICTURE-STRING CORT-EN-TS xxx ABC l?:tCTORB-STRtNG {AND JUST CLAUSE) xx xxxxx xx JUST xxxxx JUST Figure 3-8 Data Movement with No Editing CONTENTS AFTER MOVE AB ABC BC ABC 3.6.3 Multiple Receiving Fields If a MOVE statement is written with more than one rece1v1ng field, it moves the same sending field value to each of the receiving fields. It has essentially the same effect as a series of separate MOVE statements that all have the same sending field. (For information on subscripted fields, see section 3.6.4.) The receiving fields need have no relationship to each other. The software checks the legality of each one independently, and performs an independent move operation on each one. Multiple receiving fields on MOVE statements provide a convenient way to set many fields equal to the same value, such as during initialization code at the beginning of a section of processing. For example: MOVE SPACES TO LIST-LINE, EXCEPTION-LINE, NAME-FLD. MOVE ZEROES TO EOL-FLAG, EXCEPT-FLAG, NAME-FLAG. MOVE 1 TO COUNT-1, CHAR-PTR, CURSOR. 3.6.4 Subscripted Moves Any field of a MOVE statement may be subscripted and the referenced field may also be used to subscript another name in the same statement. When more than one receiving field is named in the same MOVE statement, the order in which the software evaluates the subscripts affects the results of the move. Consider the following two situations: Situation 1 MOVE FIELDl{FIELD2) TO FIELD2 FIELD3. Situation 2 MOVE FIELDl TO FIELD2 FIELD3{FIELD2). Figure 3-9 Subscripted MOVE Statements 3-11 NON-NUMERIC CHARACTER HANDLING In situation 1, the software evaluates FIELDl{FIELD2) only once, before it moves any data to the receiving fields. In effect it is as if the statement were replaced with the following statements: MOVE FIELDl{FIELD2) TO TEMP. MOVE TEMP TO FIELD2. MOVE TEMP TO FIELD3. In situation 2, the software evaluates FIELD3{FIELD2) immediately before moving the data into it (but aLL~L moving the data from FIELDl to FIELD2). Thus, it uses the newly stored value of FIELD2 as the subscript value. In effect, it is as if the statement were replaced with the following statements: MOVE FIELDl TO FIELD2. MOVE FIELDl TO FIELD3{FIELD2). 3.6.5 Common Errors, MOVE Statement A most important thing to remember when writing MOVE statements is that the compiler considers any MOVE statement that contains a group item to be a group move. It is easy to forget this fact when moving a group item to an elementary item, and the elementary item contains editing characters, or a numeric integer. These attributes of the receiving field {which would determine the action of an elementary move) have no effect on the action of a group move. 3.6.6 Format 2 - MOVE CORRESPONDING Format 2 of the MOVE statement allows the programmer to move multiple elementary items from one group item to another, by using a single MOVE statement. When the corresponding phrase is used, selected elementary items in the sending field are moved to those elementary items in the receiving field whose data-names are identical. For example: 01 A-GROUP 01 B-GROUP 02 FIELDl 02 VTVTn~ ~i~uv~ 03 A PIC x 03 A PIC x 03 B PIC 9 03 c PIC xx 03 c PIC xx 03 E PIC xxx 03 D PIC 99 03 E PIC xxx MOVE CORRESPONDING A-GROUP TO B-GROUP OR MOVE CORRESPONDING FIELDl TO FIELD2 NON-NUMERIC CHARACTER HANDLING The above examples are equivalent to the following series of MOVE statements: MOVE A OF FIELDl TO A OF FIELD2 MOVE C OF FIELDl TO C OF FIELD 2 MOVE E OF FIELDl TO E OF FIELD2 3.7 THE STRING STATEMENT The STRING statement concatenates the contents of two or more sending fields into a single field. The statement has many forms; the simplest is equivalent, in function, to a non-numeric MOVE statement. Consider the following illustration; if the two fields are the same size, or if the sending field (FIELDl) is larger, the statement is equivalent to the statement, MOVE FIELDl TO FIELD2. STRINGl FIELDl DELIMITED BY SIZE INTO FIELD2. Figure 3-10 Sample STRING Statement If the sending field is shorter than the receiving field, an important difference between the STRING and MOVE statements emerges: the software does not fill the receiving field with spaces. Thus, the STRING statement may leave some portion of the receiving field unchanged. Additionally, the receiving field must be an elementary alphanumeric field with no JUSTIFIED clause or editing characters in its description. Thus, the data movement of the STRING statement always fills the receiving field from left-to-right with no editing insertions. 3.7.1 Multiple Sending Fields An important characteristic of the STRING statement is its ability to concatenate a series of sending fields into one receiving field. Consider the following example of the STRING statement: STRING FIELDlA FIELDlB FIELDlC DELIMITED BY SIZE INTO FIELD2. Figure 3-11 Concatenation with the STRING Statement In this sample STRING statement, FIELDlA, FIELDlB, and FIELDlC are all sending fields. The software moves them to the receiving field (FIELD2) in the order in which they appear in the statement, from left to right, resulting in the concatenation of their values. 3-13 NON-NUMERIC CHARACTER HANDLING If FIELD2 is not large enough to hold all three items, the operation stops when it is full. If this occurs while moving one of the sending fields, the software ignores the remaining characters of that field and any other sending fields not yet processed. For example, if FIELD2 became full while receiving FIELDlB, the software would ignore the rest of FIELDlB and all of FIELDlC. If the sending fields do not fill the receiving field, the operation stops with the movement of the last character of the .last sending item (FIELDlC in Figure 3-11). The software does not alter the contents ~or space-fill the remaining character positions of the receiving field. The sending fields may be non-numeric literals and figurative constants (except for ALL literal). For example, the following statement sets up an address label with the literal period and space between the STATE and ZIP fields: STRING CITY SPACE STATE ". " ZIP DELIMITED BY SIZE INTO ADDRESS-LINE. Figure 3-12 Literals as Sending Fields Sending fields may also be subscripted. For statement uses subscripts to concatenate (A-TABLE) into a single field {A-FOUR). {I, subscript or an index-name.) example, the following the elements of a table of course, must be a STRING A-TABLE{!) A-TABLE(I+l) A-TABLE(I+2) A-TABLE(I+3) DELIMITED BY SIZE INTO A-FOUR. Figure 3-13 Indexed Sending Fields 3.7.2 The POINTER Phrase Although the STRING statement normally starts at the left-hand end of the receiving field, with the POINT?R phrase it is possible to start it scanning at another point within the field. (The scanning, however, remains left-to-right.) MOVE 5 TO P. STRING FIELDlA FIELDlB DELIMITED BY SIZE INTO FIELD2 WITH POINTER P. Figure 3-14 Sample POINTER Phrase When the POINTER phrase is used, the value of P determines the starting character position in the receiving field. In Figure 3-14, the 5 in P causes the software to move the first character of FIELDlA into character position 5 of FIELD2 (the left-most character position of the receiving field is character position 1) and leave positions l through 4 unchanged. 3-14 NON-NUMERIC CHARACTER HANDLING When the STRING operation is complete, the software leaves P pointing to one character position beyond the last character replaced in the receiving field. If FIELD1A and -PTELD1B in Figure 3-14 are both four characters long, P will contain a value of 13 (5+4+4} when the operation is complete (assuming that FIELD2 is at least 12 characters long} . 3.7.3 The DELIMITED BY Phrase Although the sending fields of the STRING statement are fixed in size at compile time, they frequently contain variable-length items that are padded with spaces. For example, a 20-character city field may contain only the word MAYNARD and 13 spaces. A valuable feature of the STRING statement is that it may be used to move only the useful data from the left-hand end of the sending field. The DELIMITED BY phrase, written with a data-name or literal, instead of the word SIZE, performs this operation. (The delimiter may be a literal, a data item, a figurative constant, or the word SIZE. It may not be ALL literal since ALL literal has an indefinite length. When the phrase contains the word SIZE, the software moves each sending field, in total, until it either exhausts the sending field, or fills the receiving field.) Consider the following example: STRING CITY SPACE STATE ". " ZIP DELIMITED BY SIZE INTO ADDRESS-LINE. Figure 3-15 Delimiting with the word SIZE If CITY is a 20-character field, the result of the STRING operation shown in Figure 3-15 might look like the following: "~~~-16 AYER~~-,,-~~~~MA. 01432 spaces A far more attractive printout can be produced by having the STRING operation produce the following: AYER, MA. 01432 To accomplish this, use the figurative constant SPACE as a delimiter on the sending field; thus, MOVE 1 TO P. STRING CITY DELIMITED BY SPACE INTO ADDRESS-LINE WITH POINTER P. STRING ", " STATE ". " ZIP DELIMITED BY SIZE INTO ADDRESS-LINE WITH POINTER P. Figure 3-16 SPACE as a Delimiter 3-15 NON-NUMERIC CHARACTER HANDLING This sample coding uses the pointer's characteristic of pointing to one character position beyond the last character replaced in the receiving field to enable the second STRING statement to begin at a position one character past where the first STRING statement stopped. (The first STRING statement moves data characters until it encounters a space character a match of the delimiter SPACE. The second STRING statement adds the literal, the 2-character STATE field, another literal, and the 5-character ZIP field.) The delimiter can be varied for each field within a single STRING statement by repeating the DELIMITED BY phrase after the sending field names to which it applies. Thus, the following shorter statement has the same effect as the preceding example. (Placing the operands on separate source lines, as shown in this example, has no effect on the operation of the statement, but improves program readability and simplifies debugging.) STRING CITY DELIMITED BY SPACE ", " STATE ". " ZIP DELIMITED BY SIZE INTO ADDRESS-LINE. Figure 3-17 Repeating the DELIMITED BY Phrase The sample STRING statement in Figure 3-17 cannot handle 2-word city names, such as New York, since the software would consider the space between the two words as a match for the delimiter SPACE. A longer delimiter, such as two or three spaces (non-numeric literal), can solve this problem. Only when a sequence of characters matches the delimiter will the movement stop for that data item. With a 2-byte delimiter, the same statement can be rewritten in a simpler form: STRING CITY ", " STATE ". " ZIP DELIMITED BY " " INTO ADDRESS-LINE. Figure 3-18 Delimiting with More Than One Space Character Since only the CITY field may contain two consecutive spaces (the entire STATE field is only two bytes long), the delimiter's search of the other fields will always be unsuccessful and the effect is the same as moving the full field (delimiting by SIZE). Data movement under control of a data-name or literal is generally slower in execution speed than movement delimited by SIZE. The example in Figure 3-18 illustrates a frequent source of error in the use of STRING statements to concatenate fieldso The remainder of the receiving field is not space-filled as with a MOVE statement. If ADDRESS-LINE is to be printed on a mailing label, for example, the STRING statement should be preceded by the statement, MOVE SPACES TO ADDRESS-LINE. This guarantees a space fill to the right of the concatenated result. Alternatively, the last field concatenated by the STRING statement can be a field previously set to SPACES. (This sending field must be moved under control of a delimiter other than SPACE, of course.) NON-NUMERIC CHARACTER HANDLING 3.7.4 The OVERFLOW Phrase When the SIZE option of the DELIMITED BY phrase controls the STRING operation and the pointer value is either known or the POINTER phrase is not used, the programmer can tell, by simple addition, if the receiving field is large enough to hold the sending fields. However, if the DELIMITED BY phrase contains a literal or an identifier, or if the pointer value is not predictable, it may be difficult to tell whether the size of the receiving field is adequate, and an overflow may occur. Overflow occurs when the receiving field is full and the software is either about to move a character from a sending field or is considering a new sending field. Overflow may also occur if, during the initialization of the statement, the pointer contains a value that is either less than 1 or greater than the length of the receiving field. In this case, the software moves no data to the receiving field and terminates the operation immediately. The ON OVERFLOW phrase at the end of the STRING statement tests for an overflow condition: STRING FIELDlA INTO FIELD2 WITH POINTER PNTR ON OVERFLOW GO TO PN57. Figure 3-19 The ON OVERFLOW Phrase The ON OVERFLOW phrase cannot distinguish the overflow caused by a bad initial value in pointer PNTR from the overflow caused by a receiving field that is too short. Only a separate test, preceding the STRING statement, can distinguish between the two. The following examples illustrate the overflow condition: DATA DIVISION. 01 FIELDlA PIC XXX VALUE "ABC". 01 FIELD2 PIC XXXX. PROCEDURE DIVISION. 1. STRING FIELDlA QUOTE DELIMITED BY SIZE INTO FIELD2. 2. STRING FIELDlA FIELDlA DELIMITED BY SIZE INTO FIELD2. 3. STRING FIELDlA FIELDlA DELIMITED BY "C" INTO FIELD2. 4. STRING FIELDlA FIELDlA FIELDlA FIELDlA DELIMITED BY "B" INTO FIELD2. 5. STRING FIELDlA FIELDlA "C" DELIMITED BY "C" INTO FIELD2. 6. MOVE 2 TO P. STRING FIELDlA "AC" DELIMITED BY "C" INTO FIELD2 WITH POINTER P. Figure 3-20 Various STRING Statements Illustrating the Overflow Condition 3-17 NON-NUMERIC CHARACTER HANDLING The results of executing the numbered statements follow: Table 3-2 Results of the Preceding Sample Statements Value of FIELD2 after the STRING operation Overflow? 1. ABC" NO 2. ABCA YES 3. ABAB NO 4. AAAA NO 5. ABAB YES 6. AABA NO 3.7.5 Subscripted Fields in STRING Statements All data-names used in the STRING statement may be s~bscripted, and the pointer value may be used as a subscript. Since the pointer value might be used as a subscript on one or more of the fields in the statement, it is important to understand the order in which the software evaluates the subscripts and exactly when it updates the pointer. (The use of the pointer as a subscript is not specified by ANS-74 COBOL. Before using it, read the note at the end of this subsection.) The software updates the pointer after it moves the last character out of each sending field. Consider the following sample coding: MOVE 1 TO P. STRING "ABC" SPACE "DEF" DELIMITED BY SIZE INTO R WITH POINTER P. Figure 3-21 STRING Statement with Pointer During the movement of "ABC" into the receiving field (R), the pointer value remains at 1. After the move, the software increases the pointer value by 3 (the size of the sending field literal "ABC") and it takes on the value 4. The software then moves the figurative constant SPACE and increases the pointer value by 1 and it takes on the value 5. "DEF" is then moved and, on completion of the move, the software increases the pointer to its final value for this operation, 8. 3-18 NON-NUMERIC CHARACTER HANDLING Now, consider the updating characteristics of the pointer when applied to subscripting: MOVE 1 TO P. STRING CHAR(P) CHAR(P) CHAR(P) CHAR(P) DELIMITED BY SIZE INTO R WITH POINTER P. Figure 3-22 Subscripting with the Pointer If CHAR is a !-character field in a table, the pointer increases by one after each field has been moved and the software will move them into R as if they had been subsctjpted as CHAR(!), CHAR(2), CHAR(3), and CHAR(4). If CHAR is a 2-character field, the pointer increases by two after each field has been moved and the fields will move into R as if they had been subscripted as CHAR(!), CHAR(3), CHAR(S), and CHAR (7) · Thus, the software evaiuates the subscript of a sending item once, immediately before it considers the item as a sending item. The software evaluates the subscript of a receiving item only once, at the start of the STRING operation. Therefore, if the pointer is used as a subscript on the receiving field, changes occurring to the pointer during the execution of the STRING statement will not alter the choice of which receiving string is altered. Even the delimiter field can be subscripted, and it too can be subscripted with the pointer. The software re-evaluates the delimiter subscript once for each sending field, immediately before it compares the delimiter to the field. Thus, by subscripting it with the pointer value, the delimiter can be changed for each sending field. This has the peculiar effect of choosing the next sending field's delimiter based on the position, in the receiving field, into which its first character will fall. For example, consider the following sample coding: 01 DTABLE. 03 D PIC X OCCURS 7 TIMES. ~Vll ~ 1 TO P. STRING "ABC" "ABC" "ABC" DELIMITED BY D(P) INTO R WITH POINTER P. Figure 3-23 Subscripting the Delimiter 3-19 NON-NUMERIC CHARACTER HANDLING The following table shows the value that will arrive in the receiving field (R) from the three "ABC" literals if DTABLE contains the values shown in the left-hand column: Table 3-3 Results of the Preceding Sample Statements DTABLE Value R Value ABCD EFG BCDEFGH CD EFG HI cccccccc (Unchanged) AA BA BC ABABCABC ABABAB NOTE The rules in this section, concerning subscripts in the STRING statement, are rules that are not specified by 1974 American National Standard COBOL. Dependence on these rules, particularly those involving the use of the pointer field as a subscript, may produce programs that will not perform the same way on other COBOL compilers. If the pointer field is not used as a subscript on any of the fields in the statement, the point at which the software evaluates the subscripts is immaterial to the execution of the statement. Thus, by avoiding the use of the pointer as a subscript, uniform results can be expected from all COBOL compilers that adhere to 1974 ANS COBOL. 3.7.6 Common Errors, STRING Statement The most common errors made when writing STRING statements are: · using the word "TO" instead of "INTO" e forgetting to write "DELIMITED BY SIZE"; · forgetting to initialize the pointer; · initializing the pointer to 0 instead of l; · forgetting to provide for space fill of the receiving field when it is desirable. 3-20 NON-NUMERIC CHARACTER HANDLING 3.8 THE UNSTRING STATEMENT The UNSTRING statement disperses the contents of a single sending field into multiple receiving fields. The statement has many forms; the simplest is equivalent in function to a non-numeric MOVE statement. Consider the following illustration; the sample statement is equivalent to MOVE FIELDl TO FIELD2, regardless of the relative sizes of the two fields. UNSTRING FIELDl INTO FIELD2. Figure 3-24 Sample UNSTRING Statement The sending field (FIELDl) may be either a group item or an alphanumeric, or alphanumeric edited elementary item. The receiving field (FIELD2) may be alphabetic, alphanumeric, or numeric, but it cannot specify any type of editing. If the receiving field is numeric, it must be DISPLAY usage. The picture-string of a numeric receiving field may contain any of the legal numeric description characters except for P and, of course, the editing characters. The UNSTRING statement moves the sending field to numeric receiving fields as if the sending field had been described as an unsigned integer; further, it automatically truncates or zero fills as required. If the receiving field is not numeric, the software follows the rules for elementary non-numeric MOVE statements. It left-justifies the data in the receiving field, truncating or space-filling as required. (If the data-description of the receiving field contains a JUSTIFIED clause, the software right-justifies the data, truncating or space-filling to the left as required.) 3.8.1 Multiple Receiving Fields An important characteristic of the UNSTRING statement is its ability to disperse one sending field into several receiving fields. Consider the following example of the UNSTRING statement written with multiple receiving fields: UNSTRING FIELDl INTO FIELD2A FIELD2B FIELD2C. Figure 3-25 Multiple Receiving Fields In this sample statement, FIELDl is the sending field. The software performs the UNSTRING operation by scanning across FIELDl from left to right. When the number of characters scanned is equal to the number of characters in the receiving field, the software moves the scanned characters into the receiving field and begins scanning the next group of characters for the next receiving field. 3-21 NON-NUMERIC CHARACTER HANDLING Assume that each of the receiving fields in the preceding illustration (FIELD2A, FIELD2B, and FIELD2C) is five characters long, and that FIELDl is 15 characters long. The size of FIELD2A determines the number of characters for the first move. The software scans across FIELDl until the number of characters scanned equals the size of FIELD2A (5). It then moves those first five characters to FIELD2A, and sets the scanner to the next (sixth) character position in FIELDl. The size of FIELD2B determines the size of the next move. The software begins this move by scanning across FIELDl from character position six, until the number of scanned characters equals the size of FIELD2B (5). It then moves the sixth through the tenth characters to FIELD2B, and sets the scanner to the next (eleventh) character position in FIELDl. FIELD2C determines the size of the last move (for this example) and causes characters 11 through 15 of FIELDl to be moved into FIELD2C, thus terminating this UNSTRING operation. Each data movem~nt acts as an individual MOVE statement, the sending field of which is an alphanumeric field equal in size to the receiving field. If the receiving field is numeric, the move operation will convert the data to the numeric form. For example, consider what would happen if the fields under discussion had the data descriptions and were manipulating the values shown in the following table: Table 3-4 Values Moved Into the Receiving Fields Based on the Value in the Sending Field FIELDl PIC X(15). VALUE IS: FIELD2A PIC X(5) FIELD2B PIC S9(5) LEADING SEPARATE FIELD2C PIC S999V99 ABCDE1234512345 XXXXX0000100123 ABCDE xxxxx +12345 +00001 3450 1230 FIELD2A is an alphanumeric field and, therefore, the software simply conducts an elementary non-numeric move with the first five characters. FIELD2B, however, has a leading separate sign that is not included in its size. Thus. the software moves onlv five numeric characters and generates a positive sign in the separate-sign position. FIELD2C has an implied decimal point with two character positions to the right of it, plus an overpunched sign on the low-order digit. The sending field should supply five numeric digits; but, since the sending field is alphanumeric, the software treats it as an unsigned integer; it truncates the two high-order digits and supplies two zero digits for the decimal positions. Further, it supplies a positive overpunch sign, making the low-order digit a +O (or the ASCII character, { ) . (There is no simple way to have UNSTRING recognize a sign character or a decimal point in the sending field.) If the sending field is shorter than the sum of the sizes of the receiving fields, the software ignores the remaining receiving fields. If it reaches the end of the sending field before it reaches the end of one of the receiving fields, the software moves th~ scanned characters into that receiving field. It left-justifies and fills the rema1n1ng character positions with spaces for alphanumeric data, or decimal point aligns and zero fills the remaining character positions 3-22 NON-NUMERIC CHARACTER HANDLING for numeric data. Consider the following examples of a sending field that is to_o sh-0-rt. (The st-ateme-n-t is UNSTRING FIE-LD-l INT-0 FIELD-2A FIELD2B. FIELD2A is a 3-character alphanumeric field, and receives the first three characters of FIELDl (ABC) in every operation. FIELD2B, however, runs out of characters every time before filling. Since FIELD2A always contains the characters ABC, it is not shown.) Table 3-5 Handling a Sending Field that is Too Short FIELDl PIC X(6) VALUE IS: FIELD2B PICTURE IS: FIELD2B Value after UNSTRING Operation ABC DEF ABC246 xxxxx S99999 S9V999 S9999 LEADING SEPARATE DEF 0024F 600 +0246 3.8.2 The DELIMITED BY Phrase The size of the data to be moved can be controlled by a delimiter, rather than by the size of the receiving field. The DELIMITED BY phrase supplies the delimiter characters. UNSTRING delimiters are quite flexible; they can be literals, figurative constants t1nc~ua1ng ALL literal), or identifiers (identifiers may even be subscripted data-names). This sub-section discusses the use of these three types of delimiters. Subsequent sections cover multiple delimiters, the COUNT phrase, and the DELIMITER phrase. Subscripting delimiters is discussed at the end of this section under Subscripted Fields in UNSTRING Statements. Consider the following sample UNSTRING statement; figurative constant, SPACE, as a delimiter: it uses the UNSTRING FIELDl DELIMITED BY SPACE INTO FIELD2. Figure 3-26 Delimiting with a Space Character In this example, the software scans the sending field (FIELDl), searching for a space character. If it encounters a space, it moves all of the scanned (non-space) characters that precede that space to the receiving field (FIELD2). If it finds no space character, it moves the entire sending field. When it has determined the size of the sending field, the software moves the contents of that field following the rules for the MOVE Statement, truncating or zero filling as required. The following table shows the results of an UNSTRING operation that delimits with a literal asterisk (UNSTRING FIELDl DELIMITED BY "*" INTO FIELD2) . 3-23 NON-NUMERIC CHARACTER HANDLING Table 3-6 Results of Delimiting with an Asterisk FIELDl FIELD2 FIELD2 l I PIC X(6) PICTURE IS: VALUE AFTER VALUE IS: UNSTRING I xxx ABC 1 I ABC DEF ****** *ABCDE A***** y (7\ '~ \ ' I xxx JUSTIFIED xxx xxx xxx JUSTIFIED ABC DEF DEF M/J. /J.M MA 246*** S9999 024F 12345* S9999 SEPARATE TRAILING 2345+ 2468** S999V9 SEPARATE LEADING +4680 *246** 9999 0000 If the delimiter matches the first character in the sending field, the software considers the size of the sending field to be zero. The movement operation still takes place, however, and fills the receiving field with spaces or zeroes depending on its class. A delimiter may' also be applied to an UNSTRING statement that has multiple receiving fields: UNSTRING FIELDl DELIMITED BY SPACE INTO FIELD2A FIELD2B. Figure 3-27 Delimiting with Multiple Receiving Fields The sample instruction in Figure 3-27 causes the software to scan FIELDl searching for a character that matches the delimiter. If it finds a match, it moves the scanned characters to FIELD2A and sets the scanner to the next character position to the right of the character that matched. It then resumes scanning FIELDl for a character that matches the delimiter. If it finds a match, it moves all of the characters that lie between the character that first matched the delimiter and the character that matched on the second scan, and sets the scanner to the next character position to the right of the character that matched. (Tqe DELIMITED BY phrase could handle additional receiving fields in the same manner as it handled FIELD2B.) The following table shows the results of an UNSTRING operation that applies a delimiter to multiple receiving fields (UNSTRING FIELDl DELIMITED BY "*" INTO FIELD2A FIELD2B). 3-24 NON-NUMERIC CHARACTER HANDLING Table 3-7 Re-SU-lts O-f D-e-limi ti-Rg Multiple Receiving Fields FIELD! PIC X{8) VALUE IS: FIELD2A PIC X(3) VALUES AFTER UNSTRING OPERATION FIELD2B PIC X(3) ABC*DEF* ABC ABCDE*FG ABC A*B***** AM *AB*CD** M~ **ABCDEF llM A*BCDEFG AA ABC**DEF ABC A******B AM DEF FG~ I l BM 1 AB!i I l Mll I BCD The last two examples illustrate the limitations of a single character delimiter. Accordingly, the delimiter may be longer than one character and it may be preceded by the word ALL. The following table shows the results of an UNSTRING operation that uses a 2-character delimiter {UNSTRING FIELD! DELIMITED BY "**" INTO FIELD2A FIELD2B) : Table 3-8 Results of Delimiting with Two Asterisks FIELD! PIC X{8) VALUE IS: VALUES AFTER UNSTRING OPERATION FIELD2A FIELD2B PIC XXX PIC XXX JUSTIFIED ABC**DEF ABC DEF A*B*C*D* A*B Mll I AB***C*D AB**C*D* . AB~ C*D ABll *D* 1 j l ! AB**CD** I AB!i I 1 AB***CD* ABll I liCD CD* AB*****CD 11 AB~ Mll 3-25 NON-NUMERIC CHARACTER HANDLING Unlike the STRING statement, the UNSTRING statement accepts the ALL literal as a delimiter. When the word ALL precedes the delimiter, the action of the UNSTRING statement remains essentially the same as with one delimiter until the scanning operation finds a match. At this point, the software scans farther, looking for additional consecutive strings of characters that also match the delimiter item. It considers the "ALL delimiter" to be one, two, three, or more adjacent repetitions of the delimiter item. The following table illustrates the results of an UNSTRING operation that uses an ALL delimiter (UNSTRING FIELDl DELIMITED BY ALL "*" INTO FIELD2A FIELD2B). Table 3-9 Results of Delimiting with ALL Asterisks FIELD! PIC X(8) VALUE IS: VALUES AFTER UNSTRING OPERATION FIELD2A FIELD2B PIC XXX PIC XXX JUSTIFIED ABC*DEF* i ABC DEF ABC**DEF ABC DEF A******F AM MF A*F***** AM MF A*CDEFG AM EFG The next table illustrates the results of an UNSTRING operation that combines ALL with a 2-character delimiter (UNSTRING FIELD! DELIMITED BY ALL "**" INTO FIELD2A FIELD2B). Table 3-10 Results of Delimiting with ALL Double Asterisks FIELD! VALUES AFTER UNSTRING OPERATION PIC X(8) PIC XXX PIC XXX VALUE IS: JUSTIFIED J I ABC**DEF I ABC I DEF I ··- -- -A-Bt. ~DE I A***D*** AM fl *D ! J A******* AM flfl * J 3-26 NON-NUMERIC CHARACTER HANDLING In addition to unchangeable delimiters, such as literals and figurative constants, delimiters may be designated by identifiers. Identifiers (~hich may even be subscripted data-names) permit variable delimiting. Consider the following sample statement: UNSTRING FIELD! DELIMITED BY DEL! INTO FIELD2A FIELD2B. Figure 3-28 Delimiting with an Identifier The data-name, DE~l, must be alphanumeric. It may be a group or elementary item, and it may be edited. (Since the delimiter is not a receiving field, any editing characters will not effect its use, other than contributing to the size of the item.) If the delimiter contains a subscript, the subscript may be varied as a side effect of the UNSTRING operation. The evaluation of subscripts is discussed later in this section. 3.8.2.1 Multiple Delimiters - The UNSTRING statement has the ability to scan a sending field, searching for a match from a list of delimiters. This list may contain ALL delimiters and delimiters of various sizes. The only requirement of the list is that delimiters must be connected by the word OR. The following sample statement separates a sending field into three receiving fields. The sending field consists of three strings separated by the following: (1) any number of spaces, or (2) a comma followed by a single space, or (3) a single comma, or (4) a tab character, or (5) a carriage return character. (The " " must precede the "," in the list if it is ever to be recognized.) UNSTRING FIELD! DELIMITED BY ALL SPACE OR ", " OR "," OR TAB OR CR INTO FIELD2A FIELD2B FIELD2C. Figure 3-29 Multiple Delimiters The following table illustrates the potential of this statement. The tab (represented by the letter t) and carriage return (represented by the letter r) characters represent single character fields containing the ASCII horizontal tab and carriage return characters. 3-27 NON-NUMERIC CHARACTER HANDLING Table 3-11 Results of the Multiple Delimiters Shown in Figure 3-29 FIELD! PIC X(l2) A,0,Cr At456,~E AM~ 3~M9 AttBr A,,C ABCD,~4321,Z FIELD2A PIC XXX AM AM AM AM AM ABC FIELD2B PIC 9999 FIELD2C PIC XXX 0000 CM 0456 EM I I 0003 9M 0000 BM 0000 CM 4321 ZM t--tab character, r--carriage return character 3.8.3 The COUNT Phrase The COUNT phrase keeps track of the size of the sending string and stores the length in a user-supplied data area. The length of a delimited sending field may vary widely (from zero to the full length of the field) and some programs may require knowledge of this length. For example, if it exceeds the size of the receiving field (which is fixed in size) some data may be truncated and the program's logic may require this information. To use the phrase, simply follow the receiving field name with the words COUNT IN and an identifier. Consider the following sample statement: UNSTRING FIELDl DELIMITED BY ALL "*" INTO FIELD2A COUNT IN COUNT2A FIELD2B COUNT IN COUNT2B FIELD2C. Figure 3-30 The COUNT Phrase In this sample statement, the software will count the number of characters between the left-hand end of FIELD! and the first asterisk in FIELD! and place that value into COUNT2A; thus, COUNT2A contains the size of the first sending string. The software does not include the delimiter in the count (as it is not a part of the string). The software then counts the .number of characters in the second sending field and places that value into COUNT2B. The phrase should be used only where needed; in this example the length of the string moved to FIELD2C is not needed, so no COUNT phrase follows it. 3-28 NON-NUMERIC CHARACTER HANDLING If the rece1v1ng field is shorter than the value placed in the count field, the software truncates the sending string. (If the number of inte-ger positions in a numeric field is smaller than the value placed into the count field, high-order numeric digits have been lost.) If the software finds a delimiter match on the first character it examines, it places a zero in the count field. The count field must be described as a numeric integer, either COMP or DISPLAY usage, with no editing symbols nor the character P in its picture-string. The software moves the count value into the count field according to the rules for an elementary numeric MOVE statement The COUNT phrase may be used only in conjunction with the DELIMITED BY phrase. 3.8.4 The DELIMITER Phrase The DELIMITER phrase causes the actual character or characters that delimited the sending field to be stored in a user-supplied data area. This phrase is most useful when: (1) the statement contains a delimiter list, (2) any one of the items in the list might have delimited the field, and (3) program logic flow depends on which one found a match. In fact, the DELIMITER and COUNT phrases could be used together and program logic flow could depend on both the size of the sending string and the delimiter character that terminated it. To use the DELIMITER phrase, simply follow the rece1v1ng field name with the words DELIMITER IN and an identifier. (The software places the delimiter character in the area named by the identifier.) Consider the following sample UNSTRING statement: UNSTRING FIELDl DELIMITED BY "," OR TAB OR ALL SPACE OR CR INTO FIELD2A DELIMITER IN DELIMA FIELD2B DELIMITER IN DELIMB FIELD2C. Figure 3-31 The DELIMITER Phrase After moving the first sending string to FIELD2A, the software takes the character (or characters) that delimited that string and places it in DELIMA. DELIMA, then, contains a comma, or a tab, or a carriage return, or any number of spaces. Since the delimiter string is moved under- the rules of the elementary non-numeric MOVE statement, the software truncates or space fills with left or right justification (depending on its data description). The software then moves the second sending string to FIELD2B and places its delimiting character into DELIMB. When a sending string is delimited by the end of the sending field (rather than a match on a delimiter) the delimiter string is of zero length. This causes the DELIMITER item to be space filled. The phrase should be used only where needed; in this example, the character that delimits the last sending string is not needed, so no DELIMITER phrase follows FIELD2C. 3-29 NON-NUMERIC CHARACTER HANDLING The data item named in the DELIMITER phrase must be described as an alphanumeric item. It may contain editing characters and it may even be a group item. When the DELIMITER and COUNT phrases are used together, they must appear in the correct order (DELIMITER phrase preceding the COUNT phrase). Both of the data items named in these phrases may be subscripted or indexed. If they are subscripted, the subscript may be varied as a side effect of the UNSTRING operation. (The evaluation of subscripts is discussed in section 3.8.8.) 3.8.5 The POINTER Phrase Although the UNSTRING statement normally starts at the left-hand end of the sending field, the POINTER phrase permits the user to select a character position in the sending field for the software to begin scanning. (The scanning, however, remains left-to-right.) When a sending field is to be dispersed into multiple receiving fields, it often happens that the choice of delimiters, the size of subsequent receiving fields, etc. depend on the value in the first sending string or the character that delimited that string. Thus, the program may need to move the first field, hold its place in the sending field, and examine the results of the operation to determine how to handle the sending items that follow. This is done by using an UNSTRING statement with a POINTER phrase that fills only the first receiving field. When the first string has been moved to a receiving item, the software updates the pointer data item with a new position (one character beyond the delimiter that caused the interruption) to begin the next scanning operation. The program may then examine the new position, the receiving field, the delimiter value, the sending string size, and resume the scanning operation by executing another UNSTRING statement with the same sending field and pointer data item. Thus, the UNSTRING statement can move one sending string at a time, with the form of each move being dependent on the context of the preceding string of data. The POINTER phrase must follow the last receiving item in the statement. Consider the following two UNSTRING statements with their accompanying POINTER phrases and tests: MOVE 1 TO P. UNSTRING FIELDl DELIMITED BY tt:tt OR TAB OR CR OR ALL SPACE INTO FIELD2A DELIMITER IN DELIMA COUNT IN LSIZEA WITH POINTER PNTR. IF LSIZEA = 0 GO TO NO-LABEL-PROCESS. IF DELIMA= ":" IF PNTR > 8 GO TO BIG=LABEL=PROCESS ELSE GO TO LABEL-PROCESS. IF DELIMA = TAB GO TO BAD-LABEL PROCESS. UNSTRING FIELDl DELIMITED BY ... WITH POINTER PNTR. Figure 3-32 The POINTER Phrase 3-30 NON-NUMERIC CHARACTER HANDLING PNTR contains the current position of the scanner in the sending field.. Th-e second UNSTRING state-ment uses PNTR to begir:i scanning the additional sending strings in FIELDl. Since the software considers the left-most character to be character position one, the value returned by PNTR may be used to examine the next character. To do this, simply use PNTR as a subscript on the sending field (providing that the sending field is also described as a table of characters). For example, consider the following sample coding: 01 FIELDl. 02 FIELDl-CHAR OCCURS 40 TIMES. UNSTRING FIELDl WITH POINTER PNTR. IF FIELDl-CHAR(PNTR) = "X" Figure 3-33 Examining the Next Character By Using the Pointer Data Item as a Subscript Another way to examine the next character of the sending field is to use the UNSTRING statement to move it to a 1-character receiving field. Consider the following sample coding: UNSTRING FIELDl WITH POINTER PNTR. UNSTRING FIELDl INTO CHARl WITH POINTER PNTR. SUBTRACT 1 FROM PNTR. IF CHARl = "X" ... Figure 3-34 Examining the Next Character By Placing It Into a 1-Character Field The program must decrement PNTR in order for this case to work - like the one illustrated in Figure 3-33, since the second UN STRING statement will increment the pointer value by 1. The program must initialize the POINTER phrase data item before the UNSTRING statement uses it. The software will terminate the UNSTRING operation if the initial value of the pointer is less than one or greater than the length of the sending field. (A pointer value that is less than one or greater than the length of the sending field causes an overflow condition. Overflow conditions are discussed in section 3.8.7.) The POINTER and TALLYING phrases may be used together in the same UNSTRING statement; but, when both are used, the POINTER phrase must precede the TALLYING phrase. 3-31 NON-NUMERIC CHARACTER HANDLING 3.8.6 The TALLYING Phrase The TALLYING phrase counts the number of receiving fields that received data from the sending field. When an UNSTRING statement contains several receiving fields, the possibility exists that there may not always be as many sending strings as there are receiving fields. The TALLYING phrase provides a convenient method for keeping a count of how many fields were acted upon. MOVE 0 TO RCOUNT. UNSTRING FIELDl DELIMITED BY "," OR ALL SPACE INTO FIELD2A FIELD2B FIELD2C FIELD2D FIELD2E TALLYING IN RCOUNT. Figure 3-35 The TALLYING Phrase If the software has moved only three sending strings when it reaches the end of FIELDl, it adds 3 to RCOUNT. The first three fields (FIELD2A, FIELD2B, and FIELD2C} contain data from the operation, and the last two (FIELD2D and FIELD2E) do not. The TALLYING data item always contains the sum of its initial contents plus the number of sending strings acted upon by the UNSTRING command just executed. Thus, the programmer may want to initialize the tally count before each use. When used in the same statement with a POINTER phrase, the TALLYING phrase must follow the POINTER phrase and both phrases must follow all of the field names, the DELIMITER and COUNT phrases. The data items for both phrases must contain numeric integers, that is, be without editing characters or the letter P in their picture-strings; both data items may be either COMP or DISPLAY usage. They may be signed or unsigned and, if they are DISPLAY usage, they may contain any desired sign option. The data items for both phrases may be subscripted or indexed, or they may be used as subscripts on other fields in the statement. (The evaluation of subscripts is discussed in section 3.8.8.) A convenient use of the TALLYING phrase data item is as a subscript of a receiving field. Consider the following sample coding, which causes program control to execute the UNSTRING statement repeatedly until it exhausts the sending field. MOVE 1 TO PNTR, TLY. PARl. UNSTRING FIELDl DELIMITED BY " " OR CR INTO FIELD2(TLY) DELIMITER IN DEL2 WITH POINTER PNTR TALLYING IN TLY. IF DEL2 "," GO TO PARl. Figure 3-36 The POINTER and TALLYING Phrases Used Together 3-32 NON-NUMERIC CHARACTER HANDLING This sample coding causes program control to loop through the UNSTRING stateme_nt, using th_e pointer, PNTR1 to scan acro-s--s -FIE-LDl with successive executions. Each comma isolates a sending string until control reaches either a carriage return character or the end of FIELD!. If it reaches the end of the field without encountering a carriage return character, the software places a space into the delimiter field, DEL2, and control falls through the IF statement and out of the loop. Since the TALLYING data item, TLY, is increased by 1 after each data movement, it serves as a subscript on the receiving field. In effect this causes the software to unpack the value in FIELD! into an array of fixed-size fields. Further, an array of COUNT data items can be supplied and loaded by the UNSTRING/TALLYING statement by adding the following phrase to the coding in Figure 3-36: COUNT IN C (TLY} Figure 3-37 Subscripting the COUNT Phrase With the TALLYING Data Item The TALLYING data item, in the above example, is one greater than the number of receiving fields acted upon by the UNSTRING operation. This is because the data item must be initialized to a value of one in order to be used as a subscript for the first receiving item. 3.8.7 The OVERFLOW Phrase The OVERFLOW phrase detects the overr~ow condition and provides an imperative statement to be executed when it detects the condition. An overflow condition exists when either of the following two situations occurs: 1. The UNSTRING statement is about to be executed and its pointer data item contains a value of less than one or greater than the size of the sending field. When it detects this situation, the software executes the OVERFLOW phrase before it moves any data. Thus, the values of all of the receiving fields remain unchanged. 2. The UNSTRING statement has filled all of the rece1v1ng fields and data still remains in the sending field that has not been matched as a delimiter or included in a sending string. When it detects this situation, the software executes the OVERFLOW phrase after it has executed the UNSTRING statement. Thus, the values of all of the receiving fields are updated, but some data has not been moved. If the UNSTRING operation causes the scanner to move off the end of the sending field (thus exhausting it), the software will not execute the OVERFLOW phrase. Consider the following set of instructions, which cause program control to execute the UNSTRING statement repeatedly until it exhausts the sending field. The TALLYING data item is a subscript indexing the receiving field. (Compare this loop with the one in Figure 3-36, which accomplishes the same thing.} 3-33 NON-NUMERIC CHARACTER HANDLING PARl. MOVE 1 TO TLY PNTR. UNSTRING FIELDl DELIMITED INTO FIELD2(TLY) BY " ' " OR CR WITH POINTER PNTR TALLYING IN TLY ON OVERFLOW GO TO PARl. Figure 3-38 Using the OVERFLOW Phrase NOTE The overflow condition also occurs if the value of a pointer data item lies outside the sending field at the start of execution of the UNSTRING statement. {The pointer value must not be less than 1, nor greater than the length of the sending field.) This type of overflow is not distinguishable from the overflow condition described at the start of this section, except that this condition causes the UNSTRING statement to terminate before any data movement takes place. Then, the values of all receiving fields remain unchanged. 3.8.8 Subscripted Fields in UNSTRING Statements Since the flexibility of the UNSTRING statement is enhanced by subscripting and indexing and particularly by subscripting with other fields within the statement (such as subscripting the receiving field with the TALLYING data item as discussed above), it is important to understand how often and exactly when the software evaluates these subscripts and indexes. This sub-section discusses the frequency and times of subscript evaluation. The software evaluates subscripts and indexes on the following items only once, at the initiation of the UNSTRING statement; thus, any change in subscript values during the execution of the statement has no effect on these fields: 1. Sending field, 2. POINTER data item, 3. TALLYING data item. The software evaluates subscripts and indexes on the following items immediately before it moves data into the item. It moves the data to these items in the order in which they are listed in the statement (which is the same order as below): 1. Receiving field, 2. DELIMITER data item, 3. COUNT data item. 3-34 NON-NUMERIC CHARACTER HANDLING The software evaluates any subscripts and indexes on the data-names in the DELIMITED BY phrase (delimiters) imm.ediately before it sc.ans each sending string looking for a delimiter match. Thus, it re-evaluates these data-names once for each receiving field in the statement. If any of the following items are used as subscripts on any receiving fields, the programmer must be aware of the point at which these items are updated: · POINTER data-item, · TALLYING data-item, e COUNT data-item, · Another receiving field. Figure 3-39 illustrates, with a flow chart, the sequence of evaluation operations: ± EVALUATE ALL DELIMITER SUBSCRIPTS SCAN SENDING FIELD FOR DELIMITER ,,,--....... l CONTINUE SCANNING FOR REPETITIVE MATCHES B UPDATE SCANNER EVALUATE RECEIVING FIELD SUBSCRIPT MOVE SENDING STRING TO RECEIVING FIELD y,,,--....... Iz - LU (/) Uc::J: c.. UJ (/) c~::: c:i.:.: c::: UJ I- ~ I l:i UJ 0 ~ EVALUATE DELIMITER RECEIVING FIELD SUBSCRIPT STORE DELIMITER I STRING IN RECEIVING FIELD IF POINTER PHRASE PRESENT ~ STORE SCANNER IN POINTER DATA ITEM IF TALLY1NG PHRASE PRESENT ADD 1 TO TALLYING DATA ITEM Iz - UJ EVALUATE COUNT (/) UJ FIELD c::: c.. SUBSCRIPT UJ (/) ~ c::: :ci:..: zI- STORE COUNT ::::i VALUE IN u 0 COUNT FIELD ~ Figure 3-39 Sequence of Subscript Evaluation 3-35 NON-NUMERIC CHARACTER HANDLING NOTE The rules in this section concerning the exact point at which the software evaluates the identifiers in the DELIMITED BY phrase and the point at which it updates the POINTER and TALLYING data items, are rules that are specified by 1974 American National Standard COBOL, as opposed to the STRING statement where these are not so specified. 3.8.9 Common Errors, UNSTRING Statement The most common errors made when writing UNSTRING statements are: · Leaving the OR connector out of a delimiter list; · Misspelling or interchanging the words, DELIMITED and DELIMITER; · Writing the DELIMITER and COUNT phrases in the wrong order when both are present (DELIMITER must precede COUNT) ; · Leaving out the word INTO or writing it as TO; · Repeating the word INTO where it is not needed; thus: UNSTRING FIELD! DELIMITED BY SPACE OR TAB INTO FIELD2A DELIMITER IN DELIMA INTO FIELD2B DELIMITER IN DELIMB INTO FIELD2C DELIMITER IN DELIMC. Figure 3-40 Erroneously Repeating the Word INTO · Writing the POINTER and TALLYING phrases in the wrong order (POINTER must precede TALLYING) . 3.9 THE INSPECT STATEMENT The INSPECT statement examines the character positions in a field and counts or replaces certain characters (or groups of characters) in that field. Like the STRING and UNSTRING operations, INSPECT operations scan across the field from left to right; further, like those two statementsi the INSPECT statement features a phrase which allows it to begin or terminate the scanning operation with a delimiter match. {Thus, the operation can begin within the field instead of at the left-hand end, or it may begin at the left-hand end and terminate within the field.) The TALLYING operation {which counts certain characters in the field) and the REPLACING operation (which replaces certain characters in the field) are quite versatile and may be applied to all of the characters in the delimited area of the field being inspected, or they may be applied only to those characters that match a given character string 3-36 NON-NUMERIC CHARACTER HANDLING under stated conditions. Consider the following sample statements, which both caus.e a sc.an of the complete field: INSPECT FIELDl TALLYING TLY FOR ALL "B". Figure 3-41 Sample INSPECT ... TALLYING Statement This statement scans FIELDl looking for the character B. Each time it finds a B, it increments TLY by 1. INSPECT FIELDl REPLACING ALL SPACE BY ZERO. Figure 3-42 Sample INSPECT ... REPLACING Statement This statement scans FIELDl looking for space characters. Wherever it finds a space character, it replaces it with zero. One INSPECT statement can contain both a TALLYING phrase and a REPLACING phrase. However, when used together, the TALLYING phrase must precede the REPLACING phrase. An INSPECT statement with both phrases is equivalent to two separate INSPECT statements and, in fact, the software compiles such a statement into two distinct INSPECT statements. (To simplify debugging, therefore, it is best to initially write the two phrases in separate INSPECT statements.) 3.9.1 The BEFORE/AFTER Phrase The BEFORE/AFTER phrase acts as a delimiter and (possibly) restricts the area of the field being inspected. The following sample statement would count only the zeroes that precede the percent sign (%) in FIELDl. INSPECT FIELDl TALLYING TLY FOR ALL ZEROES BEFORE "%". Figure 3-43 Sample INSPECT .·. BEFORE Statement The delimiter (the percent sign in the preceding sample statement) can be a single character, a string of characters, or any figurative constant. Further, it can be either an identifier or a literal. · If the delimiter is an identifier, it must be an elementary data item of DISPLAY usage. It may be alphabetic, alphanumeric, or numeric, and, it may contain editing characters. The compiler always treats the item as if it had been described as an alphanumeric string. (It does this by implicit redefinition of the item, as described in Section 3.9.2.) · If the delimiter is a literal, it must be non-numeric. 3-37 NON-NGMERIC CHARACTER HANDLING The software repeatedly compares the delimiter characters against an equal number of characters in the field being inspected. If none of the characters matches the delimiter, or if insufficient characters remain in the field for a full comparison (at the right-hand end), the software considers the comparison to be unequal. The examples of the INSPECT statement in Figure 3-44, illustrate the way the delimiter character finds a match in the field being inspected. (The portion of the field the statement ignores as a result of the BEFORE/AFTER phrase delimiters is crossed out with a slash, and the portion it inspects is underlined.) INSTRUCTION FIELDl VALUE INSPECT FIELDl ..· BEFORE "E II. INSPECT FIELDl ... AFTER "E". ABCDtti9ft iJt~l1tFGHI INSPECT FIELDl ..· BEFORE "K". INSPECT FIELDl ·.. AFTER "K". ABCDEFGHI it(twtti9ft INSPECT FIELDl ... BEFORE "AB". INSPECT FIELDl . . . AFTER "AB". INSPECT FIELDl ... BEFORE "HI II. INSPECT FIELDl ... AFTER "HI". I INSPECT FIELDl ... BEFORE "I I:!. II. INSPECT FIELDl . . . AFTER III I:!. II · ilt(tl1tti~t itCDEFGHI ABCDEFG~t iit(twtr~~, ABCDEFGHI ¥Jt~l1Jl11~~1 The ellipsis represents the position of the TALLYING or REPLACING phrase. Figure 3-44 Matching the Delimiter Characters to the Characters in a Field The software scans the field for a delimiter match before it scans for the inspection operation (TALLYING or REPLACING), thus establishing the limits of the operation before beginning the actual inspection. The importance of the separate scan is discussed further in Section 3.9.3. 3.9.2 Implicit Redefinition The software requires that certain fields referred to by the INSPECT statement be alphanumeric fields. If one of these fields was described as another data class, the compiler redefines that field so the INSPECT statement can handle it as a simple alphanumeric string. This implicit redefinition is conducted as follows: · If the field was described as alphabetic, alphanumeric edited, or unsigned numeric, the compiler simply redefines it as alphanumeric. This is a compile-time operation; no data movement occurs at object-time. · If the field was described as signed numeric, the compiler first removes the sign and then redefines the field as alphanumeric. If the sign is a separate character, the compiler ignores that character, essentially shortening the 3-38 NON-NUMERIC CHARACTER HANDLING field, and that character does not participate in the implicit redefiniti_o_n.. If the sign is an "_overpunch" o_n the leading or trailing digit, the compiler actually removes the sign value and leaves the character with only the numeric value that was stored in it. The compiler alters the digit position containing the sign before beginning the INSPECT operation and restores it to its former value after the operation. If the sign's digit position does not contain a valid ASCII signed numeric digit, the action of the redefinition causes the value to change. Table 3-12 shows these original, altered, and restored values. The compiler never moves an implicitly redefined item from its storage position. All redefinition occurs in place. The position of an implied decimal point on numeric quantities does not affect implicit redefinition. Table 3-12 Original, Altered, and Restored Values Resulting from Implicit Redefinition ORIGINAL VALUE ALTERED VALUE RESTORED VALUE } (173) A (101) B (102) c (10 3) D (104) 0 (60) 1 (61) 2 (62) 3 (63) 4 (64) } (17 3) A (101) B (102) c (10 3) D (104) E (105) F (106) G (107) H (llO) I (lll) 5 (65) I 6 (66) I 7 (67) 8 (70) I 9 (71) E (105) F (106) G (107) H (llO) I (111) { (17 5) J (ll2) K (ll3) L (114) M (ll5) 0 (60) 1 (61) 2 (62) 3 (63) 4 (64) { (17 5) J (112) K (ll3) L (114) M (115) N (ll6) 0 (ll 7) p (120) Q (121) R (122) 5 (65) 6 (66) 7 (67) 8 (70) 9 ( 71) N (116) 0 (117) p (120) Q (121) R (122) 0 (60) 0 (60) } (173) I 1 (61) 1 (61) A (101) 2 (62) 2 (62) B (10 2) 3 (63) 3 (63) c (103) 4 (64) 4 (64) D (104) 5 (65) 6 (66) 7 (67) 8 (70) 9 (71) 5 (65) 6 (66) 7 (67) 8 (70) 9 ( 71) E (105) F (106) G (107) H (110) I (lll) All other values 0 (60) } (17 3) 3-39 NON-NUMERIC CHARACTER HANDLING 3.9.3 The INSPECT Operation Regardless of the type of inspection (TALLYING or REPLACING), the INSPECT statement has only one method for inspecting the characters in the field. This section describes this method. However, before discussing how the inspection operation is conducted, let's analyze the INSPECT statement itself: INSPECT FIELDl _T_A_L_L_Y_I_N-'-G_T_L_Y POR iLL B II II BEFORE 117\ II n · The field being__/ inspected ~ The argument I The operation phrase The delimiter phrase Figure 3-45 Sample INSPECT Statement The format of the INSPECT statement requires that a field be named which is to be inspected (FIELDl above); the field name must be followed by an operation phrase (TALLYING TLY above); and, that phrase must be followed by one or more identifiers or literals ("B" above). These identifiers or literals comprise the "arguments" (items to be compared to the field being inspected} . More than one argument makes up the "argument list". e TALLYING Arguments Each argument in an argument list can have other fields associated with it. Thus, each argument that is used in a TALLYING operation must have a tally counter (TLY above) associated with it. The software increments the tally counter each time it matches the argument with a character or group of characters in the field being inspected. e REPLACING Arguments INSPECT FIELDl REPLACING ALL "O" BY "$". 7 replacing argument Figure 3-46 Sample REPLACING Argument Each argument in an argument list that is used in a REPLACING operation must have a replacement item ($ above) associated with it. The software uses the replacement item to replace each string of characters in the field that matches the argument. Each argument in an argument list (that is used with either a TALLYING or REPLACING operation} may have a delimiter field (BEFORE/AFTER phrase) associated with it. If the delimiter field is not present, the software applies the argument to the entire field. If the delimiter field is present, the software applies the argument only to that portion of the field specified by the BEFORE/AFTER phrase. 3-40 NON-NUMERIC CHARACTER HANDLING 3.9.3.1 Setting the Scanner - The INSPECT operation begins by setting the scanner to the leftmost character position of the field b-ein-g inspected. It remains on this character until an argument has been matched with a character (or characters) or until all arguments have failed to find a match at that position. 3.9.3.2 Active/Inactive Arguments - When an argument has a BEFORE/AFTER phrase associated with it, that argument has a delimiter and may not be eligible to participate in a comparison at every position of the scanner. Thus, each argument in the argument list has an active/inactive status at any given setting of the scanner. For example, an argument that has an AFTER phrase associated with it starts the INSPECT operation in an inactive state. The delimiter of the AFTER phrase must find a match before the argument can participate in the comparison. When the delimiter finds a match, the software retains the character position beyond the matched character string; then, when the scanner reaches or passes this position, the argument becomes active. INSPECT FIELDl TALLYING TLY FOR ALL ~a~ AFTER ~x~. Figure 3-47 Sample AFTER Delimiter Phrase If FIELDl in Figure 3-47 has a value of "ABABXZBA", the argument B remains inactive until the scanner finds a match for the delimiter X. Thus, argument B remains inactive while the software scans character positions 1 through 5. At character position 5, the delimiter X finds a match, and since the character position beyond the matched delimiter character is the point at which the argument becomes active, argument B is compared for the first time at character position 6. It finds a successful match at character position 7 and this causes TLY to be incremented by 1. The examples in Figure 3-48 illustrate other situations where the arguments and/or the delimiters are longer than one character. (Consider the sample statement to be an INSPECT ... TALLYING statement that is scanning FIELDl, tallying in TLY, and looking for the arguments and delimiters in the left-hand column. Assume that TLY is initialized to 0.) 3-41 NON-NUMERIC CHARACTER HANDLING ARGUMENT AND DELIMITER FIELD! VALUE ARGUMENT ACTIVE AT POSITION CONTENTS OF TLY AFTER SCAN BXBXXXXBB 6 2 "B" AFTER "XX" xxxxxxxx 3 0 BXBXBBBBXX never 0 BXBXXBXXB 6 2 "X" AFTER "XX" xxxxxxxx I BBBBBBXX 3 never 6 0 BXYBXBXX 7 0 "B" AFTER "XB" XBXBXBXB 3 3 BBBBBBXB never 0 XXXXBXXXX 6 0 "BX" AFTER "XB" XXXXBBXXX 6 1 XXBXXXXBX 4 1 Figure 3-48 Where Arguments Become Active in a Field When an argument has an associated BEFORE delimiter, the inactive/active states reverse roles: the argument is in an active state when the scanning begins, and becomes inactive at the character position that matches the delimiter. Additionally, regardless of the presence of the BEFORE delimiter, an argument becomes inactive when the scanner approaches the right-hand end of the field and the remaining characters are fewer in number than the characters in the argument. (In such a case, the argument cannot possibly find a match in the field so it becomes inactive.) Since the BEFORE/AFTER delimiters are found on a separate scan of the field, the software recognizes and sets up the delimiter boundaries before it scans for an argument match; therefore, the same characters can be used as arguments and delimiters in the same phrase. 3.9.3.3 Finding an Argument Match - The software selects arguments from the argument list in the order in which they appear in the list. If the first one it selects is an active argument and the conditions stated in the INSPECT statement allow a comparison; the software compares it to the character at the position of the scanner. If the active argument does not find a match, the software takes the next active argument from the list and compares that to the same character. If none of the active arguments finds a match, the scanner moves one position to the right and begins the inspection operation again with the first active argument in the list. The inspection operation terminates at the right-hand end of the field. When an active argument does find a match, the software ignores any remaining arguments in the list and conducts the TALLYING or REPLACING operation on the character. The scanner moves to a new position and the next inspection operation begins with the first argument in the list. (The INSPECT statement may contain additional conditions, which are described later in this section; this discussion, however, assumes that the argument match is allowed to take place and that inspection is allowed to continue following the match.) 3-42 NON-NUMERIC CHARACTER HANDLING The software updates the scanner by adding the size of the matching argument to it. This moves the scanner to the next character beyond the string of characters that matched the argument. Thus, once an active argument matches a string of characters, the statement does not inspect those character positions again unless program control executes the entire statement again. 3.9.4 Subscripted Fields in INSPECT Statements Any identifier named in an INSPECT statement may be subscripted or indexed. The software evaluates all subscripts in an INSPECT statement once, before the inspection begins; therefore, if the action of the INSPECT statement alters one of the subscripts, the new subscript value has no effect on the selection of operands during that inspection operation. For example, consider the following illustration: MOVE 1 TO TLY. INSPECT FIELDl TALLYING TLY FOR ALL X(TLY). Figure 3-49 Sample Subscripted Argument In this sample statement, the software evaluates the address of X(TLY) only once, before it begins inspecting the field; hence, it will evaluate X(TLY) as X(l). The alteration of TLY by the action of inspecting and tallying has no effect on the choice of the X operand. (X(l) will be used throughout the operation.) NOTE When subscripting an INSPECT statement that contains both a TALLYING and a REPLACING phrase, keep in mind that the statement will be compiled into two separate INSPECT statements. Therefore, any field that is altered by the action of the INSPECT ... TALLYING statement will be in its altered state if used as a subscript by the INSPECT ... REPLACING statement. 3.9.5 The TALLYING Phrase An INSPECT statement that contains a TALLYING phrase counts the occurrence of various character strings under certain stated conditions. It keeps the count in a user-design~ted field called, here, a tally counter. 3-43 NON-NUMERIC CHARACTER HANDLING 3.9.5.l The Tally Counter - The identifier that follows the word TALLYING designates the tally counter. The identifier may be subscripted or indexed. The data item must be a numeric integer with no editing or P characters; it may be COMP or DISPLAY usage, and it may be signed (separate or overpunched). Each time the tally argument matches the delimited string being inspected, the software adds 1 to the tally counter. The programmer can initialize the tally counter to any numeric value. (The INSPECT statement does not initialize it.) 3.9.5.2 The Tally Argument - The tally argument specifies a character-string and a condition under which that string should be compared to the delimited string being inspected. The following figure shows the format of the tally argument: { { ALL LEADING } CHARACTERS { i~entifier}} literal Figure 3-SO Format of the Tally Argument The CHARACTERS form of the tally argument specifies that every character in the delimited string being inspected should be considered to match an imaginary character that serves as the tally argument. This increments the tally counter by a value that equals the size of the delimited string. For example, the statement in the following illustration causes TLY to be incremented by the number of characters that precede the first comma, regardless of what those characters might be. INSPECT FIELDl TALLYING TLY FOR CHARACTERS BEFORE ",". Figure 3-51 CHARACTERS Form of the Tally Argument The ALL and LEADING forms of the tally argument specify a particular character string, which may be represented by either a literal or an identifier. The tally argument character string may be any length; however, each character of the argument must match a character in the delimited string before the software considers the argument matched. · A literal character string must be either non-numeric or a figurative constant (other than ALL literal). A figurative constant: such as SPACE, ZERO, etc., represents a single character and can be written as" ", or "O", etc., with the same effect. · An identifier must be·an elementary item of DISPLAY usage. It may be any data class. However, if it is other than alphanumeric, the software performs an implicit redefinition of the item. (This redefinition is identical to the BEFORE/AFTER delimiter redefinition discussed earlier in Section 3.9.1.) 3-44 NON-NUMERIC CHARACTER HANDLING The words ALL and LEADING supply conditions that further delimit the inspection operation. · The word ALL specifies that every match that the search argument finds in the delimited character string be counted in the tally counter. When a literal follows the word ALL, it does not have the same meaning as the figurative constant, ALL literal. (The ALL literal meaning of ALL "," is a string of consecutive commas, as many as the context of the statement requires.) ALL "," used as a tally argument means, "count each comma without regard to adjacent characters." · The word LEADING specifies that only adjacent matches of the TALLY argument at the left-hand end of the delimited character string be counted. At the first failure to match the tally argument, the software terminates counting and causes the argument to become inactive. Consider the examples in Figure 3-52. (The sample statement is an INSPECT . . . TALLYING statement, scanning FIELDl, tallying in TLY, and looking for the arguments and delimiters in the left-hand column. Assume that the program initializes TLY to 0. ) ARGUMENT AND DELIMITER FIELDl VALUE AFTER SCAN F***O**F 2 F**OF** 0 LEADING 11*11 AFTER 0 II II 0 F**F**O 0 I O***F** 3 LEADING 11**11 AFTER 0 II II 0 F**O**F*** F**FO***FF** F**FO****F** F**F**O* 1 1 j 2 0 Figure 3-52 Results of Counting with the LEADING Condition 3.9.5.3 The Tally Argument List - One INSPECT ... TALLYING statement can contain more than one tally argument, and each argument can have a separate BEFORE/AFTER phrase and tally counter associated with it. These tally arguments with their associated tally counters and BEFORE/AFTER phrases form an argument list. The manner in which this list is processed affects the action of any given tally argument. The following sample statements show INSPECT statements with argument lists. The text following each one tells how that list will be processed. INSPECT FIELDl TALLYING T FOR ALL II' II ALL II II ALL ";". Figure 3-53 Argument List Adding Into One Tally Counter 3-45 NON-NUMERIC CHARACTER HANDLING These three tally arguments have the same tally counter, T, and are active over the entire field being inspected. Thus, this statement adds the total number of commas, periods, and semicolons in FIELDl to the initial value of T. INSPECT FIELDl TALLYING Tl FOR ALL "," T2 FOR ALL " " T3 FOR ALL ";". Figure 3-54 Argument List Adding Into Separate Tally Counters Each tally argument in this statement has its own tally counter, and is active over the entire field being inspected. Thus, the action of this statement is to add the total number of commas in FIELDl to the initial value of Tl, the total number of periods to the initial value of T2, and the number of semicolons to T3. INSPECT FIELDl TALLYING Tl FOR ALL "," AFTER "A" T2 FOR ALL "." BEFORE "B" T3 FOR ALL ";". Figure 3-55 Argument List (with Delimiters) Adding into Separate Tally Counters Each tally argument in this statement has its own tally counter; the first two arguments have delimiter phrases, and the last one is active over the entire field being inspected. Thus, the first argument is initially inactive and becomes active only after the scanner encounters an A; the second argument begins the scan in the active state but becomes inactive after a B has been encountered; and the third argument is active during the entire scan of FIELDl. Figure 3-56 shows various values of FIELDl and the contents of the three tally counters after the scan. Assume that the counters are initialized to 0 before the INSPECT statement. FIELDl VALUE CONTENTS OF TALLY COUNTERS AFTER SCAN Tl T2 T3 A.C;D.E,F A.B.C.D A,B,C,D A;B;C;D *,B 6 C,D 1 2 1 0 1 0 3 0 0 0 0 3 0 0 0 Figure 3-56 Results of the Scan in Figure 3-55 The BEFORE/AFTER phrase applies only to the argument that precedes it, and delimits the field for that argument only. Each BEFORE/AFTER phrase causes a separate scan of the field to determine the limits of the field for its corresponding argument. 3-46 NON-NUMERIC CHARACTER HANDLING 3.9.5.4 Interference in Tally Argument Lists - When several tally arguments contain one or more identical characters that are active at the same time, they ~ay interfere with each other (i.e., when one of the arguments finds a match, the scanner is stepped past the matching character(s) which prevents those character(s) from being considered for any other match) . The example in Figure 3-57 illustrates two identical tally arguments that do not interfere with each other since they are not active at the same time. (The first A in FIELD! causes the first argument to become inactive and the second argument to become active.) MOVE 0 TO Tl T2. INSPECT FIELDl TALLYING Tl FOR ALL "," BEFORE "A" T2 FOR ALL "," AFTER "A". Figure 3-57 Two Tallying Arguments that Do Not Interfere with Each Other The two identical tally arguments in Figure 3-58 will interfere with each other since both are active at the same time. (For any given position of the scanner, the arguments are applied to FIELDl in the order in which they appear in the statement. When one of them finds a match, the scanner moves to the next position and ignores the remaining arguments in the argument list.) Each comma in FIELD! causes Tl to be incremented by 1 and the second argument to be ignored. Thus, Tl will always contain an accurate count of all of the commas in FIELDl, and T2 will always be unchanged. INSPECT FIELDl TALLYING Tl FOR ALL "," T2 FOR ALL "," AFTER "A". Figure 3-58 Two Tallying Arguments that Do Interfere with Each Other The following statement achieves the same results as the statement in Figure 3-57. The first argument does not become active until the scanner encounters an A. The second argument tallies all commas that precede the A. After the A, the first argument counts all commas and causes the second argument to be ignored. Thus, Tl contains the number of commas that precede the first A and T2 contains the number of commas that follow the first A. This statement works well as written, but could be more confusing to debug than the one in Figure 3-57. INSPECT FIELDl TALLYING T2 FOR ALL "," AFTER "A" Tl FOR ALL ",". Figure 3-59 Two Tallying Arguments that, Because of their Positioning, Only Partially Interfere with Each Other 3-47 NON-NUMERIC CHARACTER HANDLING The preceding three examples show that one INSPECT statement cannot count any character more than once. Thus, when using the same character in more than one argument of an argument list, consider the nature of the interference and choose the order of the arguments very carefully. The solution to the problem may require two or more INSPECT statements. Consider the following problem: INSPECT FIELDl TALLYING Tl FOR ALL "AB" T2 FOR ALL "BC". Figure 3-60 An Attempt to Tally the Character B with Two Arguments If FIELDl contains "ABCABC", after the scan Tl will be incremented by a 2 and T2 will be unaltered. The successful matching of the argument includes each B in the field. Each match resets the scanner to the character position to the right of the B, and causes the second argument to never be successfully matched. Reversing the order of the arguments has no effect, the results remain the same. Only separate INSPECT statements can develop the desired counts. Sometimes the programmer can use the interference characteristics of the INSPECT statement to good advantage. Consider the following sample argument list: MOVE 0 TO T4 T3 T2 Tl. INSPECT FIELDl TALLYING T4 FOR ALL "****" T3 FOR ALL "***" T2 FOR ALL "**" Tl FOR ALL "*" Figure 3-61 Tallying Asterisk Groupings The argument list in Figure 3-61 counts all of the asterisks in FIELD! but in four different tally counters. T4 counts the number of times that four asterisks occur together; T3 counts the number of times three asterisks appear together; T2 counts double asterisks; and Tl counts singles. If FIELD! contains a string of more than four consecutive asterisks, the argument list breaks the string into groups of four, and counts them in T4. It then counts the less-than-four remainder in T3, T2, or Tl. Reversing the order of the arguments in this list causes Tl to count all of the asterisks and T2, T3, and T4 to remain When the LEADING condition is used with an argument in the ar~ument list, that argument becomes inactive as soon as it fails to be matched in the field being inspected. ,Therefore, when two arguments in an argument list contain one or more identical characters and one of the arguments has a LEADING condition, the argument with the LEADING condition should appear first. Consider the following sample statement: 3-48 NON-NUMERIC CHARACTER HANDLING MOVE 0 TO Tl T2. INSPECT FIELDl TALLYING * Tl FOR LEA-DING 11 11 T2 FOR ALL *11 11 Figure 3-62 Placing the LEADING Condition in the Argument List The placement of the LEADING condition in this sample statement causes Tl to count only leading asterisks in FIELDl; the occurrence of any other character stops this counting and causes the first tally argument to become inactive. T2 keeps a count of any remaining asterisks in FIELDl. Reversing the order of the arguments in this statement results in an argument list that can never increment Tl. INSPECT FIELDl TALLYING T2 FOR ALL "*" Tl FOR LEADING "*". I J Figure 3-63 Reversing the Argument List in Figure 3-62 If the first character in FIELDl is not an asterisk, neither argument can match it and the second argument becomes inactive. If the first character in FIELDl is an asterisk, the first argument matches and causes the second argument to be ignored. The first non-asterisk character in FIELDl will fail to match the first argument and the second argument will become inactive. (The second argument becomes inactive because it has not found a match in all of the preceding characters.} An argument with both a LEADING condition and a BEFORE phrase can sometimes sucessfully "delimit" the field being inspected: MOVE 0 TO Tl T2. INSPECT FIELDl TALLYING Tl FOR LEADING SPACES T2 FOR ALL II II BEFORE II II T2 FOR ALL II II BEFORE 11 11 · T2 FOR ALL II II BEFORE II II IF T2 > 0 ADD 1 TO T2. Figure 3-64 An Argument List that Counts Words in a Statement The statements in Figure 3-64 count the number of "words" in the English statement in FIELDI. (This assumes that no more than three spaces separate the words in the sentence and that the sentence ends with a period.) When FIELDl has been scanned, T2 contains the number of gaps between the words. Since a count of the gaps renders a number that is one less than the number of words, the conditional statement adds one to the count. 3-49 NON-NUMERIC CHARACTER HANDLING The first argument removes any leading spaces, counting them in a different tally counter. This shortens FIELD! by preventing the application of the second through the fourth arguments until the scanner finds a non-space character. The BEFORE phrase on each of the other arguments causes them to become inactive when the scanner reaches the period at the end of the sentence. Thus, the BEFORE phrases "shorten" FIELD! by making the second through the fourth arguments inactive before the scanner reaches the right-hand end of FIELD!. If the sentence in FIELD! is indented with tab characters instead of spaces, a second LEADING argument can count the tab characters. The following sample statement illustrates this technique: INSPECT FIELD! TALLYING Tl FOR LEADING SPACES Tl FOR LEADING TAB T2 FOR ALL " " etc. Figure 3-6S Counting Leading Tab or Space Characters When an argument list contains a CHARACTERS argument, it should be the last argument in the list. Since the CHARACTERS argument always matches the field, it prevents the application of any of the following arguments in the list. However, as the last argument in an argument list, it can count the remaining characters in the field being inspected. Consider the following illustration. MOVE 0 TO Tl T2 T3 T4 TS. INSPECT FIELD! TALLYING Tl FOR LEADING SPACES T2 FOR ALL " " BEFORE "," T3 FOR ALL "+" BEFORE "," T4 FOR ALL "-" BEFORE "," TS FOR CHARACTERS BEFORE ",". Figure 3-66 Counting the Remaining Characters With the CHARACTERS Argument a If F!ELDl is known to contain a number in the form frequently used to input data, it may contain a plus or minus sign, and decimal point; further, the number may possibly be preceded by spaces and terminated by a comma. If this statement were compiled and executed, it would deliver the following results: Tl would contain the number of leading spaces, T2 would contain the number of periods, T3 would contain the number of plus signs, T4 would contain the number of minus signs, TS would contain the number of remaining characters (assumed to be numeric), and the sum of Tl through TS (plus 1) gives the character position occupied by the terminating comma. 3-50 NON-NUMERIC CHARACTER HANDLING 3.9.6 The REPLACING Phrase When an INSPECT statement contains a REPLACING phrase, that statement selectively replaces characters or groups of characters in the designated field. The REPLACING phrase names a search argument consisting of a character string of one or more characters and a condition under which the string may be applied to the field being inspected. Associated with the search argument is the replacement value, which must be the same length as the search argument. Each time the search argument finds a match in the field being inspected, under the condition stated, the replacement value replaces the matched characters. A BEFORE/AFTER phrase may be used to delimit the area of the field being inspected. A search argument applies only to the delimited area of the field. 3.9.6.1 The Search Argument - The search argument of the REPLACING phrase names a character string and a condition under which the character string should be compared to the delimited string being inspected. Figure 3-67 shows the format of the search argument: I ALL ILEADING ( FIRST } identifier} { literal ' CHARACTERS I Figure 3-67 Format of the Search Argument The CHARACTERS form of the search argument specifies that every character in the delimited string being inspected should be considered to match an imaginary character that serves as the search argument. Thus, the replacement value replaces each character in the delimited string. (The replacement value, in this case, must be one character long.) The ALL, LEADING, and FIRST forms of the search argument specify a particular character string, which may be represented by a literal or an identifier. The seaLch argument character string may be any length. However, each character of the argument must match a character in the delimited string before the software considers the argument matched. · A literal character string must be either non-numeric or a figurative constant (other than ALL literal). A figurative constant, such as SPACE, ZERO, etc., represents a single character and can be written as " ", "O", etc. with the same effect. Since a figurative constant represents a single character, the replacement value must be one character long. · An identifier must represent an elementary item of DISPLAY usage. It may be any class. However, if it is other than alphabetic, the software performs an implicit redefinition of the item. (This redefinition is identical to the BEFORE/AFTER delimiter redefinition discussed in Section 3.9.1.) 3-51 NON-NUMERIC CHARACTER HANDLING The words ALL, LEADING, and FIRST supply conditions which further delimit the inspection operation: · The word ALL specifies that each match that the search argument finds in the delimited string is to be replaced by the replacement value. When a literal follows the word ALL, it does not have the same meaning as the figurative constant, ALL literal. (The figurative constant meaning of ALL "," is a string of consecutive commas, as many as the context of the statement requires.) ALL "," as a search argument of the REPLACING phrase means, "replace each comma without regard to adjacent characters." · The word LEADING specifies that only adjacent matches of the search argument at the left-hand end of the delimited character string be replaced. At the first failure to match the search argument, the software terminates the replacement operation and causes the argument to become inactive. · The word FIRST specifies that only the leftmost character string that matches the search argument is to be replaced. After the replacement operation, the search argument contafning this condition becomes inactive. 3.9.6.2 The Replacement Value - Whenever the search argument finds a match in the field being inspected, the matched characters are replaced by the replacement value. The word BY followed by an identifier or literal specifies the replacement value. identifier} BY { literal Figure 3-68 Format of the Replacement Value The replacement value must always be the same size as its associated search argument. If the replacement value is a literal character string, it must be eitner a non-numeric literal or a figurative constant (other than ALL literal). A figurative constant represents as many characters as the length that the search argument requires. If the replacement value is an identifier, it must be an elementary item of DISPLAY usage. It may be any class. However, if it is other than alphanumeric, the software conducts an implicit redefinition of the item. (This redefinition is the same as the BEFORE/AFTER redefinition discussed in Section 3.9.1.) 3.9.6.3 The Replacement Argument - The replacement argument consists of the search argument (with its condition and character string), the replacement value, and an optional BEFORE/AFTER phrase. 3-52 NON-NUMERIC CHARACTER HANDLING ALL ";" BY SPACE BEFORE "." search/ argument / ~ BEFORE/AFTER phrase (optional) replacement value Figure 3-69 The Replacement Argument 3.9.6.4 The Replacement Argument List - One INSPECT ... REPLACING statement can contain more than one replacement argument. Several replacement arguments form an argument list, and the manner in which the list is processed affects the action of any given replacement argument. The following examples show INSPECT statements with replacement argument lists. The text following each one tells how that list will be processed. I INSPECT . I . L _ FIELDl REPLACING ALL ALL II " ' " " BY BY SPACE SPACE ALL " ' " BY SPACE. Figure 3-70 Replacement Argument List that is Active Over the Entire Field These three replacement arguments all have the same replacement value, SPACE, and are active over the entire field being inspected. Thus, this statement replaces all commas, periods, and semicolons with space characters; and leaves all other characters unchanged. INSPECT FIELDl REPLACING ALL "O" BY "l" ALL "l" BY "O" Figure 3-71 Replacement Argument List that "Swaps" Ones for Zeroes and Zeroes for Ones Each of these two replacement arguments has its own replacement value, and is active over the entire field being inspected. This statement exchanges zeros for ones and ones for zeroes, and leaves all other characters unchanged. NOTE When a search argument finds a match in the field being inspected, the software replaces that character string and scans to the next position beyond the replaced characters. It ignores the remaining arguments and applies the first argument in the list to the character string in 3-53 NON-NUMERIC CHARACTER HANDLING the new position. Thus, it never inspects the new value that was supplied by the replacement operation. Because of this, the search arguments may have the same values as the replacement arguments with no chance of interference. ~PECT FIELDl REPLACING ALL "O" BY "l" BEFORE SPACE I ALL "l" BY "O" BEFORE SPACE. Figure 3-72 Replacement Argument List that Becomes Inactive with the Occurrence of a Space Character This sample statement is identical to the statement in Figure 3-71, except that, here, the first occurrence of a space character in FIELDl causes both arguments to become inactive. INSPECT FIELDl REPLACING ALL "O" BY "l" BEFORE SPACE ALL "l" BY "O" BEFORE SPACE CHARACTERS BY "*" BEFORE SPACE. Figure 3-73 Argument List with Three Arguments That Become Inactive with the Occurrence of a Space Just as in the argument list in Figure 3-72, the first space character causes all of these replacement arguments to become inactive. This argument list exchanges zeroes for ones, ones for zeroes, and asterisks for all other characters that are in the delimited area. If the BEFORE phrase is removed from the third argument, that argument will remain active across all of FIELDl. Within the area delimited by the first space character, the third argument replaces all characters except ones and zeroes with asterisks. Beyond this area, it replaces all characters (including the space that delimited FIELDl for the first two arguments and any zeroes and ones) with asterisks. 3.9.6.5 Interference in Replacement Argument Lists - When several search arguments that are active at the same time contain one or more identical characters, they may interfere with each other, and consequently have an effect on the replacement operation. This interference of one search argument with the matching of other search arguments is similar to the interference that occurs between tally arguments. The action of a search argument is never affected by the BEFORE/AFTER delimiters of other arguments, since the software scans for delimiter matches before it scans for replacement operations. The action of a search argument is never affected by the characters of any replacement value, since the scanner does not inspect the replaced characters again during execution of the INSPECT statement. 3-54 NON-NUMERIC CHARACTER HANDLING Interference between search arguments, therefore, depends on the order of the arguments, the values of the arguments, and the active-inactive status of the arguments. (The discussion in Section 3.9.5.4 Interference in Tally Argument Lists, applies, generally, to replacement arguments as well.) The following rules will help minimize interference in replacement argument lists: 1. Place search arguments with LEADING or FIRST conditions at the start of the list; 2. Place several arguments with the CHARACTERS condition at the end of the list; 3. Consider, very carefully, the order of appearance of any search arguments that contain one or more identical characters. 3.9.7 Common Errors, INSPECT Statement The most common errors made when writing INSPECT statements are: e Leaving the FOR out of an INSPECT . . . TALLYING statement. · Using the word "WITH" instead of "BY" in the REPLACING phrase. · Failing to initialize the tally counter. -.. Omitting the word n 7\ TT n rl.J..J.U c,.... . ,.. '::;:j · · · INSPECT FIELDl TALLYING TLY FOR SPACES. 3-55 CHAPTER 4 NUMERIC CHARACTER HANDLING This chapter discusses numeric class data and the COBOL operations that can be performed on numeric data items. It is assumed that you have read Chapter 3, and that you understand the concept of COBOL data classes. 4.1 USAGES The USAGE of a numeric class item specifies the form in which the data is stored in memory. PDP-11 COBOL has four formats for numeric data storage: DISPLAY (which is equivalent to DISPLAY-6 and DISPLAY-7), COMPUTATIONAL (abbreviated COMP) I COMPUTATIONAL-6 (abbreviated COMP-6) , and COMPUTATIONAL-3 (abbreviated COMP-3) · 4 .1.1 DISPLAY Items with DISPLAY usage are stored as strings of characters (bytes) in decimal radix with an assumed decimal point and optional sign. 4.1.2 COMPUTATIONAL COMPUTATIONAL usage is the standard PDP-11 binary format. A COMP item is stored as a binary value with an assumed decimal scaling position; it is automatically SYNCHRONIZED on a word boundary and stored in memory (in one, two, or four words) as follows: PICTURE RANGE S(9) to S9(4) S9(5) to S9(9) S9(11J) to S9(18) STORAGE 1 word (2 bytes) 2 words (4 bytes) 4 words (8 bytes) Figure 4-1 indicates the significance of each byte in a COMP data item by the number in parentheses. For example, "(l)" indicates that the byte contains the lowest-valued bits. Observe that the computer address (the first-referenced byte) of each COBOL data item corresponds to the low byte of the least significant word. 4-1 NUMERIC CHARACTER HANDLING The number in parentheses also indicates the order of characters if the data item is redefined as an alphanumeric item. Consider an example of a two-word COMP item: i1 COMP-ITEM PIC 9(9) USAGE IS COMP. i1 GROUP-ITEM REDEFINES COMP-ITEM. i3 CHARACTER-ITEM PIC X OCCURS 4 TIMES. The subscripts of CHARACTER-ITEM correspond to the numbers in parentheses in Figure 4-1. NOTE The internal formats of one-word COMP and COMP-6 data items are identical. addressed word high byte ( 2) low byte (1) one-word COMP data item I addressed word next word high byte (2) low byte (1) high byte (4) low byte ( 3} two-word COMP data item addressed word high byte ( 2) low byte (1) next word next word high byte (4) low byte (3) high byte (6) low byte (5) four-word COMP data item next word high byte (8) low byte (7) Figure 4-1 Memory Storage of COMP Data Items 4-2 NUMERIC CHARACTER HANDLING 4.1.3 COMPUTATIONAL-6 NOTE COMP-6 is temporarily defined for compatibility with the COMP data type in PDP-11 COBOL releases prior to Version 4.ii. Its use is not recommended except for converting data files containing data items defined as COMP in earlier releases of PDP-11 COBOL. COMP-6 is not compatible with the standard binary data types. A COMP-6 item is stored as a binary value with an assumed decimal scaling position; it is automatically SYNCHRONIZED on a word boundary and stored in memory (in one, two, three, or four words) as follows: PICTURE RANGE s (9) to S9(4) 89 (5) to 89(9) 89 (li) to S9(14) S·9 (15) to S9(18) STORAGE 1 word (2 bytes) 2 words (4 bytes) 3 words (6 bytes) 4 words (8 bytes) Figure 4-2 indicates the significance of each byte in a COMP-6 data item by the number in parentheses. For example, "(l)" indicates that the byte contains the lowest-valued bits. Note that the computer address (the first-referenced byte) of each COBOL data item corresponds to the low byte of the most significant word. The number in parentheses does not indicate the order of characters if the data item is redefined -a5 an alphanumeric item. Consider an example of a four-word COMP-6 item: i1 COMP-6-ITEM PIC 9(16) USAGE IS COMP-6. i1 GROUP-ITEM REDEFINES COMP-6-ITEM. ~3 CHARACTER-ITEM PIC X OCCURS 8 TIMES. The occurrences of the subscripted data item CHARACTER-ITEM map into memory storage as follows: OCCURRENCE OF CHARACTER-ITEM 1 2 3 4 5 6 7 8 BYTE (N) IN FIGURE 4-2 ( 7) (8) (5) (6) ( 3) (4) ( 1) ( 2) 4-3 NUMERIC CHARACTER HANDLING NOTE The internal formats of one-word COMP and COMP-6 data items are identical. addressed word high byte (2) low byte (1) one-word COMPUTATIONAL-6 data item addressed word next word I high byte (4) low byte (3) high byte (2) low byte (1) two-word COMPUTATIONAL-6 data item addressed word next word next word high byte ( 6) low byte (5) high byte (4) low byte (3) high byte (2) low byte (1) three-word COMPUTATIONAL-6 data item addressed word next word next word next word .n&..&;.·"n:J n...... byte (8) low byte (7) high byte (6) low byte (5) l-.irrn .a. ......... '::::t ... " byte ( 4) low byte ( 3) high byte (2) low byte ( 1) four-word COMPUTATIONAL-6 data item Figure 4-2 Memory Storage of COMP-6 Data Items 4-4 NUMERIC CHARACTER HANDLING 4.1.4 COMPUTATIONAL-3 COMP-3 specifies packed-decimal data items. They are stored as two decimal digits per byte (byte-aligned) with an assumed decimal scaling position. The sign is contained in the rightmost half (four bits) of the rightmost byte. The maximum size of a COMP-3 item is 18 decimal digits, regardless of the decimal scaling position. In the following example, both NUM-1 and NUM-2 represent COMP-3 items of maximum size: j3 NUM-1 PIC S9(18) USAGE IS COMP-3 . .0'3 NUM-2 PIC S9(6)V9(12) USAGE IS COMP-3. The description of a COMP-3 data item must have a sign in its PICTURE character-string. When you specify an even number of digits, the value zero is stored in the leftmost four bits of the leftmost byte. Signs resulting from operations in which the receiving item is specified as COMP-3 are: "+" binary ll.0'.0' octal 14 "-" binary ll.0'1 octal 15 The following signs are also recognized as valid, but they are not generated as a result of program operations: Positive signs- binary iin, octal 12 binary ll.0'.0'' octal 14 binary lll.0'' octal 16 binary llll, octal 17 Negative signs- binary ljll, octal 13 binary ll.0'1, octal 15 Figure 4-3 represents the memory storage of COMP-3 data items of one, two, and three digits: 1st byte 5 + 1st byte .0' 3 2nd byte 2 - 1st byte 2 6 2nd byte 2 + PICTURE 89 value: +5 PICTURE S9(2) value: -32 PICTURE S9(3) value: +262 Figure 4-3 Memory Storage of COMP-3 Data Items 4-5 NUMERIC CHARACTER HANDLING 4.2 DECIMAL SCALING POSITION The assumed decimal scaling position, or scaling factor, is not stored as part of an actual numeric value. However, it is used by the OTS to control operations on numeric data items. Consider the following field description: ~l ORDER-PRICE PIC 99V99 COMP VALUE 12.34. PDP-11 COBOL stores this item as a 1-word binary number. The word contains the integer value 1234 and anotner location contains ~ne scaling faptor. In this example, the scaling factor records the fact that this integer has two decimal fractional positions. Thus, the COBOL OTS knows that the stored binary integer is l~~ times larger than the programmer intends it to be. If the compiler encounters the following statement: ADD 1 TO ORDER-PRICE. it generates instructions to add a 1 to the 1234 in ORDER-PRICE. The OTS, however, scales the literal 1 up by two decimal places and adds the resultant literal, l~~, to the number in ORDER-PRICE. Thus, after the ADD operation, ORDER-PRICE contains the new value 1334 (which is actually 13.34 with the stored decimal scaling position). Thus, the PDP-11 COBOL compiler and OTS manipulate the data in DISPLAY, COMP, COMP-6, and COMP-3 data items in much the same way. All four usages have exactly the same accuracy and precision, and can be freely mixed in a program. To illustrate, if a DISPLAY usage number and a COMP usage number are both involved in the same arithmetic statement, the OTS converts them to a common radix with no loss of information. It also converts the result, if necessary, with no loss of significance. The only effect of specifying a binary or packed-decimal usage is that it reduces the space required for most numbers and can speed up the execution of arithmetic statements. 4.3 SIGN CONVENTIONS COMP-3 data items must be signed; however, DISPLAY, COMP, and COMP-6 numeric items can be signed or unsigned. Unsigned numbers can contain values that range from zero to the largest positive value allowed by their declared precision. Negative values are not allowed. All PDP-11 COBOL arithmetic operations yield signed results. When the OTS must store such a result, whether positive or negative, in an unsigned data item, it stores only the absolute value of the result. Thus, unsigned items always contain zero or positive values. This guide does not recommend unsigned numbers for general use. They are usually a source of programming errors, and are handled less efficiently than signed quantities by the OTS. Signed quantities always contain a. numeric value and an operational sign. The OTS stores the sign with the numeric value in a variety of ways depending on the usage of the item and the presence of the SIGN clause. 4-6 NUMERIC CHARACTER HANDLING NOTE If numeric data is read into a field described using the picture character s, then that data must include an operational sign of the appropriate format to pass the NUMERIC test. PDP-11 COBOL always stores signed COMP and COMP-6 items in two's complement binary form. Thus, the high-order bit indicates the sign of the item. Sign representation for COMP-3 data items is described in Section 4.1.4. PDP-11 COBOL always stores signed DISPLAY items as a sequence of byte positions containing numeric ASCII characters. It may include the sign in the high-order byte, the low-order byte, or as a separate, extra, byte on either the high-order or low-order end of the item. When the OTS stores the sign as part of a byte that also contains a numeric digit, the sign causes a value change in that byte and, hence, changes the value of the numeric digit. Table 4-1 shows the actual ASCII character that results when a numeric value and a sign share the same byte. Table 4-1 The Resulting ASCII Character From a Sign and Digit Sharing the Same Byte [ + SIGN - I DIGIT VALUE ~ 1 2 3 4 5 6 7 8 9 t A B c D E F G H I l J KL MN 0 p Q R A byte containing a +~ stores as an octal 173, which prints as either a tor a [ depending on the printing device. l A byte containing a -~ stores as an octal 175, which prints as either a or a ] depending on the printing device. When the OTS stores the sign as a separate distinct character, the actual ASCII character that it stores is the graphic plus sign (octal ~53) or the graphic minus sign (octal ~55). 4-7 NUMERIC CHARACTER HANDLING 4.4 ILLEGAL VALUES IN NUMERIC FIELDS All PDP-11 COBOL arithmetic operations store legal values in their result fields. However, it is possible, by reading invalid data or through redefinition and group moves, to store data in numeric fields that do not obey the descriptions of those fields. (For example, it is possible to place signed values into unsigned fields, and to place non-numeric or improperly signed data into signed numeric DISPLAY fields.) The results of arithmetic operations that use invalid data in numeric fields are unpredictable. 4.5 TESTING NUMERIC FIELDS COBOL provides the following three kinds of tests for evaluating numeric fields: 1. Relation tests, that compare the field's contents to another numeric value; 2. Sign tests, that examine the field's sign to see if it is positive or negative; and, 3. Class tests, that inspect the field's digit positions for legal numeric values. The following sub-sections explain these tests in detail. 4.5.1 Relation Tests A relation test compares two numeric quantities and determines if the specified relation between them is true. For example, the following statement compares FIELDl to FIELD2 and determines if the numeric value of FIELDl is greater than the numeric value of FIELD2. If so, the relation condition is true and program control takes the True path of the statement. IF FIELDl > FIELD2 ... Either field in a relation test may be a numeric literal or the figurative constant, ZERO. (The numeric literals ~' ~~' ~.~, or ZERO are all equivalent, both in meaning and in execution speed.) The sizes of the fields in a numeric relation test do not have to be the same (this includes the sizes of numeric literals). The comparison operation aligns both fields on their assumed decimal positions (through actual scaling operations in temporary locations or by accessing the individual digits) and supplies leading or trailing (as required) zeroes to either or both fields. The comparison operation always compares the signs of non-zero fields and considers positive fields to be greater than negative fields. However, since it does not compare them, positive zeroes and negative zeroes are equal. (A negative zero could arrive in a field through redefinition of the field or a MOVE to a group item.) Further, the operation considers unsigned numeric fields to be positive. 4-8 NUMERIC CHARACTER HANDLING The form of representation of the number (COMP, COMP-6, COMP-3, or DISP-LAY usage) and the various methods of storing DISPLAY usage signs have no effect on numeric relation tests. For comparison purposes, the operation converts any illegal characters stored in DISPLAY usage fields to zeroes. It does not, however, alter the actual values in those fields. 4.5.2 Sign Tests The sign test compares a numeric quantity to zero and determines if it is greater (positive), less (negative), or equal (zero). Both the relation test and the sign test can perform this function. For example, consider the following relation test: IF FIELDl > ~ ··· Now consider the following sign test: IF FIELDl POSITIVE ... Both of these tests accomplish the same thing and would always arrive at the same resu~t. The sign test, however, shortens the statement and shows, at a glance, that it is testing the sign. Table 4-2 shows the sign tests and their equivalent relation tests as applied to FIELDl. Table 4-2 The Sign Tests SIGN TEST ... IF FIELDl POSITIVE ... IF FIELDl NOT POSITIVE ... IF FIELDl NEGATIVE ... IF FIELDl NOT NEGATIVE ... IF FIELDl ZERO ... IF FIELDl NOT ZERO EQUIVALENT RELATION TEST ... IF FIELDl > ~ ... IF FIELDl NOT > ~ ... IF FIELDl < ~ . .. IF FIELDl NOT < ~ ... IF FIELDl = ~ ... IF FIELDl NOT = ~ Sign tests have no execution speed advantage over relation tests. The compiler actually substitutes the equivalent relation test for every correctly written sign test. (Sections 4.2.1 and 4.2.2 discuss the acceptable sign values and the treatment of illegal sign values.) 4-9 NUMERIC CHARACTER HANDLING 4.5.3 Class Tests The class test interrogates a numeric field to determine if it contains numeric or alphabetic data, and uses the result to alter the flow of control in a program. For example, the following statement determines if FIELDl contains numeric data. If so, the test condition is true and program control takes the true path of the statement. IF FIELDl IS NUMERIC When reading in newly prepared data, it is often desirable to check certain fields for valid values. Relation tests and sign tests can only determine if the field's contents are within a certain range, and these tests both treat illegal characters in DISPLAY usage items as zeroes. Thus, some data preparation errors could pass both of these tests. The NUMERIC class test checks numeric (or alphanumeric) DISPLAY usage fields for valid numeric digits. If the field being tested contains a sign (whether carried as an overpunch or as a separate chara~ter), the test checks it for a valid sign value. If the character position carrying the sign contains an illegal sign value, the NUMERIC class test rejects the item and program control takes the false path of the IF statement. If the character position contains a valid sign and all digit positions in the field contain valid numeric digits, the NUMERIC class test passes the item and program control takes the true path of the IF statement. The ALPHABETIC class test checks alphabetic (or alphanumeric) fields for valid alphabetic characters and the space character. If all of the character positions of the field contain ASCII characters (A-Z or space), the item passes the ALPHABETIC class test and causes program control to take the true path of the IF statement. (For further information concerning the ALPHABETIC class test, see Chapter 3, Section 3.3.2.) 4.6 THE MOVE STATEMENT The MOVE statement moves the contents of one field into another. The following sample MOVE statement moves the contents of FIELDl into FIELD2. MOVE FIELDl TO FIELD2. Section 3.5 discusses the basic MOVE statement. This section considers MOVE statements as applied to numeric fields. These MOVE statements can be grouped into the following three categories: 1. Group moves, 2. Elementary moves with numeric receiving fieids, and 3. Elementary moves with numeric edited receiving fields. The following three sub-sections (4.6.l, 4.6.2, and 4.6.3) discuss each of these categories separately. 4-10 NUMERIC CHARACTER HANDLING 4.6.1 Group Moves The software considers a move to be a group move if either the sending field or the receiving field is a group item. It treats both fields in a group move as alphanumeric class fields and performs the move as an alphanumeric to alphanumeric elementary move. If either field in a group move is a numeric elementary item, the OTS treats the storage area occupied by that item as a field of alph?numeric bytes; thus, it ignores the USAGE, sign, and decimal point location characteristics of the numeric item. Only the item's allocated size, in bytes, affects the move operation. The OTS considers a separate sign character to be part of the item and moves it with the numeric digit positions. 4.6.2 Elementary Numeric Moves If both fields of a MOVE statement are elementary items and the rece1v1ng field is numeric, the OTS considers the move to be an elementary numeric move. (The sending field may be either numeric or alphanumeric.) The numeric receiving field may be DISPLAY, COMP, COMP-6, or COMP-3 usage. The elementary numeric move converts the data format of the sending field to the data format of the receiving field. An alphanumeric sending field may be either an elementary data item or any alphanumeric literal other than the figurative constants SPACE, QUOTE, LOW-VALUE, HIGH-VALUE, or ALL "literal". The elementary numeric move accepts the figurative constant ZERO and considers it to be equivalent to the numeric literal i. It treats alphanumeric sending fields as unsigned integers of DISPLAY usage. If necessary, the numeric move operation converts the sending field to the data format of the receiving field and aligns the sending field's decimal point on that of the rece1v1ng field. It then moves the sending field digits to their corresponding receiving field digits. If the sending field has more digit positions than the rece1v1ng field, the decimal point alignment operation truncates the sending field, with the resultant loss of digits. The end truncated (high-order or low-order) depends upon the number of sending field digit positions that find matches on each side of the recelVJng field's decimal point. If the rece1v1ng field has fewer digit positions on both sides of the decimal point, the operation truncates both ends of the sending field. Thus, if a field described as PIC 999V999 is moved to a field described as PIC 99V99, it loses one digit from the left end and one from the right end. Figure 4-4 illustrates this alignment operation (the carat (~ ) indicates the stored decimal scaling position): 4-11 NUMERIC CHARACTER HANDLING g1 AMOUNTl PIC 99V99. MOVE 123.321 TO AMOUNTl. Before execution After execution 23 32 Figure 4-4 Truncation Caused By Decimal Point Alignment If the sending field has fewer digit positions than the receiving field, the move operation supplies zeroes for all unfilled digit positions. Figure 4-5 illustrates this alignment (the carat ( ) indicates the stored decimal scaling position): g1 TOTAL-AMT PIC 999V99. MOVE 1 TO TOTAL-AMT. Before execution After execution Figure 4-5 Zero Filling Caused By Decimal Point Alignment The following statement produces the same results: MOVE JJl.JJ TO TOTAL-AMT. Consider the following two MOVE statements and their resultant truncating and zero-filling effects: STATEMENT TOTAL-AMT AFTER EXECUTION MOVE JJlJJ TO TOTAL-AMT MOVE "JJlJJ" TO TOTAL-AMT Literals with leading or trailing zeroes have no significant advantage in space or execution speed with PDP-11 COBOL, and· the zeroes are often lost by decimal point alignment. The MOVE statement's receiving field dictates how the sign will be moved. A signed DISPLAY usage receiving field causes the sign to be moved as a separate quantity. An unsigned DISPLAY usage rece1v1ng field causes no sign movement. A COMP or COMP-6 usage receiving field, whether signed or unsigned, causes the sign to be moved; however, if the receiving field is unsigned, the OTS sets its value to absolute. A COMP-3 receiving field always causes the sign to be moved. 4-12 NUMERIC CHARACTER HANDLING 4.6.3 Elementary Numeric Edited Moves The PDP-11 COBOL object time system considers an elementary numeric move to a receiving field of the numeric edited category to be an elementary numeric edited move. The sending field of an elementary numeric edited move may be either numeric or alphanumeric and, if numeric, its usage can be DISPLAY, COMP, COMP-6, or COMP-3. The OTS treats alphanumeric sending fields in numeric edited moves as unsigned DISPLAY usage integers. The OTS considers the receiving field to be numeric edited category if it is described with a BLANK WHEN ZERO clause, or a combination of the following symbols: B Space insertion position; P Decimal scaling position; V Location of assumed decimal point; Z Leading numeric character position to be replaced by a space if the position contains a zero; g Zero insertion position; 9 Position contains a numeric character; I Slash insertion position; Comma insertion position; Decimal point insertion position; * Leading numeric character position to be replaced by an asterisk if the position contains a zero; + Positive editing sign control symbol; Negative editing sign control symbol; CR Credit editing sign control symbol; DB Debit editing sign control symbol; cs Currency symbol ($) insertion position. A numeric edited field may contain 9, V, and P, but combinations of those symbols without an editing character do not make the field numeric edited. The numeric edited move operation first converts the sending field to DISPLAY usage and aligns both fields on their decimal point locations, truncating or padding (with zeroes) the sending field until it contains the same number of digit positions on both sides of the decimal point as the receiving field. It then moves the resulting digit values to the receiving field digit positions following the COBOL editing rules. 4-13 NUMERIC CP.ARACTER HANDLING The COBOL editing rules allow the numeric edited move operation to perform any of the following editing functions: · Suppress leading zeroes with either spaces or asterisks; · Float a currency sign and a plus or minus sign through suppressed zeroes, inserting the sign at either end of the field; · Insert zeroes and spaces; · Insert commas and a decimal point. Figure 4-6 illustrates several of these functions with the statement, MOVE FLD-B TO TOTAL-AMT. (Assume that FLD-B is described as S9999V99.) FLD-B TOTAL-AMT PICTURE STRING CONTENTS AFTER MOVE 111123 1111 111185 90 1234 1111 111112 34 11111111 3 4 1234 1111 111112 34 111112 34 11111111 1111 111112 3M 111Jl2 34 ZZZZ.99 ++++.99 Z,ZZZ.99 $,$$$.99 $,$$9.99 $$,$$$.99 $$9,999.99 $$$$,$$$.99 $$$,$$$.$$ ++++.99 $***,***.99 23.1111 -85.96 1,234.1111 $12.34 $11. 3 4 $1,234.1111 $11,,012.34 $12.34 -12.34 $*****12.34 Figure 4-6 Numeric Editing The currency symbol ($) and the editing sign control symbols (+ -) are the only floating symbols. To float them, enter a string of two or more occurrences of the symbol. 4.6.4 Common Errors, Numeric MOVE Statements The most common errors made when writing numeric MOVE statements are: · Placing an incorrect number of repl~cement characters in a numeric edited item. · Moving non-numeric data into numeric fields with group moves. · Trying to float the $ or + insertion characters past the decimal point to force zero values to appear as .1111 instead of spaces. (Use $$.99 or ++.99.) · Forgetting that the $ or + insertion characters require an aaa1~1onal pos1~1on on the leftmost end that cannot be replaced by a digit (unlike the * insertion character which can be completely replaced) . 4-14 NUMERIC CHARACTER HANDLING 4.7 THE ARITHMETIC STATEMENTS The COBOL arithmetic statements, ADD, SUBTRACT, MULTIPLY, DIVIDE, and COMPUTE allow COBOL programs to perform simple arithmetic operations on numeric data. This section covers the use of COBOL arithmetic statements. The first five sub-sections (4.7.1 through 4.7.5} discuss the statements' common features, and the following five (4.7.6 through 4.7.li) discuss each statement individually. 4.7.1 Intermediate Results Most forms of the arithmetic statements perform their operations in temporary work locations, then move the results to the receiving fields, aligning the decimal points and truncating or zero filling the resultant values. This temporary work field, called the intermediate result field, has a maximum size of 18 numeric digits. The actual size of the intermediate result field varies for each stateme~t, and is determined at compile time based on the s; '70 c of the operands used statement. When the compiler determines that the size of the intermediate result field exceeds 18 digits, it truncates the excess high-order digits. Thus, a program that requests a multiplication operation between the following two fields, PIC 9(18) and PIC V99. (which would otherwise cause the compiler to set up a 2i-digit intermediate result field 9(18}V99) actually causes the following intermediate result field PIC 9(16)V99. PDP-11 COBOL truncates high-order digits or low-order digits to the right of the decimal point, based on the assumption that most large data declarations are larger than ever need be, so zeroes occupy most of their high-order digit positions. Numeric data may be declared as PIC 9(12) or PIC 9(15) but the values that are placed in these fields will probably not exceed nine digits of range (1 billion) in most applications. When using large numbers (or numbers with many decimal places) that are close to 18 digits long, examine all of the arithmetic operations that manipulate those numbers to determine if truncation will occur. If truncation is a possibility, reduce the size of the number by dividing it by a power of lj prior to the arithmetic operation. (This scaling down operation causes the low-order end to lose digits, but these are probably less critical.} Then, after the arithmetic operation, multiply the result by the same power of lj. To save the low-order digits in such an operation, move the field to a temporary location before the scaling DIVIDE, perform separate, identical arithmetic operations on both the original and the temporary fields, then, after the scaling MULTIPLY, combine their results. 4-15 NUMERIC CHARACTER HANDLING 4.7.2 The ROUNDED Phrase Rounding-off is an important tool with most arithmetic operations. The ROUNDED phrase causes the OTS to round-off the results of COBOL arithmetic operations. The phrase may be used on any COBOL arithmetic statement. Rounding-off takes place only when the ROUNDED phrase requests it, and then only if the intermediate result has more low-order digits than the result field. PDP-11 COBOL rounds-off by adding a 5 to the leftmost truncated digit of the absolute value of the intermediate result before it stores that result. Consider the following illustration and assume an intermediate of 54321. 2468: Coding: J .01 FLD-A PIC S9(5)V9999. ....01 FLD-B PIC S9(5)V99. ... ADD FLD-A TO FLD-B ROUNDED. result I Intermediate result field: PIC S9C6)V9999. The ROUNDED operation: J Intermediate result field: ,054321. 24 ROUNDED: (ADD) .,0,0 FLD-B's ROUNDED result: ,054321. 25 Truncated digits 6 ,LEFT-MOST 5,0 truncated 18 digit Figure 4-7 Rounding Truncated Decimal Point Positions The following ROUNDING example rounds-off to the decimal scaling position (P). Assume an intermediate result of 2468g. (Section 4.5.4 discusses the GIVING phrase in numeric operations.) Coding: ,01 AMOUNTl PIC 9999. ,01 AMOUNT2 PIC 9999PP. MULTIPLY AMOUNTl BY 1.0 GIVING AMOUNT2 ROUNDED. Figure 4-8 Rounding Truncated Decimal Scaling Positions 4-16 NUMERIC CHARACTER HANDLING J Intermediate re-sul t field: PIC 999999. The ROUNDED operation: 1 Truncated Intermediate result field: i246 80. digits ROUNDED AMOUNT2's (ADD) : ROUNDED result: 0247 3i. Figure 4-8 (continued) Rounding Truncated Decimal Scaling Positions 4.7.3 The SIZE ERROR Phrase The SIZE ERROR phrase detects the loss of high-order non-zero digits in the results of COBOL arithmetic operations. The phrase may be used on any COBOL arithmetic statement. When the execution of a statement with no SIZE ERROR phrase results in a size error, the OTS truncates the high-order digits and stores the result without notifying the user. When the execution of a statement with a SIZE ERROR phrase results in a size error, the OTS discards the entire result (it does not alter the receiving fields in any way) and executes the SIZE-ERROR imperative phrase. If the statement contains both ROUNDED and SIZE ERROR phrases, the OTS rounds the result before it checks for a size error. The phrase cannot be used on numeric MOVE statements. Thus, if a program moves a numeric quantity to a smaller numeric field, it may inadvertently lose high-or.der digits. For exampl~, consider the following MOVE of a field to a smaller field: i1 AMOUNT-A PIC 9(8)V99. i1 AMOUNT-B PIC 9(4)V99. MOVE AMOUNT-A TO AMOUNT-B. This MOVE operation always loses four of AMOUNT-A's high-order digits. Either of the following two statements could determine whether these digits are zero or non-zero, and could be tailored to any size field: 1. IF AMOUNT-A NOT > 9999.99 MOVE AMOUNT-A TO AMOUNT-B ELSE ... 2. ADD ZERO TO AMOUNT-A GIVING AMOUNT-B ON SIZE ERROR ... 4-17 NUMERIC CHARACTER HANDLING Both of these alternatives allow the MOVE operation to occur only if AMOUNT-A loses no significant digits. If the value in AMOUNT-A is too large, both alternatives avoid altering AMOUNT-B and take the alternative execution path. 4.7.4 The GIVING Phrase The GIVING phrase moves the intermediate result field of an arithmetic operation to a receiving field. (The phrase acts exactly like a MOVE statement with the intermediate result serving as a sending field and the data item following the word GIVING (in the statement) serving as a receiving field.) The phrase may be used on the ADD, SUBTRACT, MULTIPLY, and DIVIDE statements. If the data item following the word GIVING is a numeric edited field, the OTS performs the editing the same way it does for MOVE statements. 4.7.5 Multiple Operands in ADD and SUBTRACT Statements Both the ADD and SUBTRACT statements may contain a string of more than one operand preceding the word TO, FROM, or GIVING. Multiple operands in either of these statements cause the OTS to add the string of operands together and use the intermediate result of that operation as a single operand to be added to or subtracted from, the receiving field. The following three equivalent coding groups illustrate how the software executes the multiple operand statements: 1. Statement: ADD A B C D TO E F G H. Equivalent coding: ADD A B, GIVING TEMP. ADD TEMP, C, GIVING TEMP. ADD TEMP, D, GIVING TEMP. ADD TEMP, E, GIVING E. ADD TEMP, F GIVING F. ADD TEMP, G GIVING G. ADD TEMP, H GIVING H. 2. Statement: SUBTRACT A, B, C, FROM D. Equivalent coding: ADD A, B, GIVING TEMP. ADD TEMP, C GIVING TEMP. SUBTRACT TEMP FROM D GIVING D. 3. Statement: ADD A B C D GIVING E. Equivalent coding: ADD A B GIVING TEMP. ADD TEMP C GIVING TEMP. ADD TEMP D GIVING E. 4-18 NUMERIC CHARACTER HANDLING (Just as with all COBOL statements, any commas in these statements are optional.) Only statement 3 may have a numeric edited receiving field, since it is the only statement containing a GIVING phrase. 4.7.6 The ADD Statement The ADD statement adds two or more operands together and stores the result. The statement may contain multiple operands (with the exception of Format 3) and the ROUNDED and SIZE ERROR phrases. It may be written in one of the following formats: Format 1. ADD FIELDl ··· TO FIELD2 FIELD3 . · . . Format 2. ADD FIELDl FIELD2 . . · GIVING FIELD3 FIELD4 Format 3. ADD CORRESPONDING FIELDl TO FIELD2. In Format 1, the receiving fields (FIELD2, FIELD3) are one of the addends. These must not be in the numeric edited category. In Format 2, the receiving fields (FIELD3, FIELD4) are not one of the addends. They may either be numeric or numeric edited. When using this format, omit the word TO. In Format 3, the receiving field (FIELD2) is one of the addends. Both FIELDl and FIELD2 must be qroup items. The corresoondinq elements of FIELDl are added to the corresponding elements of FIELD2.- 4.7.7 The SUBTRACT Statement The SUBTRACT statement subtracts one, or the sum of two or more, operands from another operand and stores the result. The statement may contain multiple operands (with the exception of Format 3) and the ROUNDED and SIZE ERROR phrases. It may be written in one of the following formats: Format 1. SUBTRACT FIELDl FROM FIELD2 FIELD3 . · · . Format 2. SUBTRACT FIELDl FROM FIELD2 GIVING FIELD3 FIELD4 Format 3. SUBTRACT CORRESPONDING FIELDl FROM FIELD2. In Format 1, the rece1v1ng fields (FIELD2, FIELD3) are both the subtrahend and the difference (the result). These must not be in the numeric edited category. In Format 2, the receiving fields (FIELD3, FIELD4) are used only to store the result. They may be either numeric or numeric edited. In Format 3, the receiving field (FIELD2) is both the subtrahend and the difference (results). Both FIELDl and FIELD2 must be group items. The corresponding elements of FIELD2. 4-19 NUMERIC CHARACTER HANDLING 4.7.8 The MULTIPLY Statement The MULTIPLY statement multiplies one operand by another and stores the result. The statement may contain the ROUNDED and SIZE ERROR phrases. It may contain multiple receiving operands. It may be written in either of the following formats: Format 1. MULTIPLY FIELDl BY FIELD2, FIELD3 . · · . Format 2. MULTIPLY FIELDl BY FIELD2 GIVING FIELD3, FIELD4 ·.·. In Format 1, the receiving fields (FIELD2, FIELD3) are also the multipliers. These must not be in the numeric edited category. In Format 2, the receiving fields (FIELD3, FIELD4) are neither multiplier nor multiplicand. These may be either numeric or numeric edited. COBOL's "near English" format could cause a problem with the MULTIPLY statement, since it is common to speak of multiplying a number (multiplicand) by another number (multiplier) and to think of the result as a new value for the multiplicand; thus: MULTIPLY EARNINGS BY i.24. Multiplier Multiplicand This statement is incorrect since the OTS stores the result in the multiplier field, and this multiplier is a literal. The compiler could diagnose this error, but would not diagnose it if the multiplier were a data item. Consider this multiplier written as a data item: MULTIPLY EARNINGS BY TAX-RATE. The compiler would not diagnose this statement's error, and would store the result of the operation in TAX-RATE. A good practice when using MULTIPLY statements is to always write them in Format 2. This ensures that the result is properly stored. The following two statements safely capture their results: MULTIPLY EARNINGS BY i.24 GIVING EARNINGS. or MULTIPLY EARNINGS BY TAX-RATE GIVING EARNINGS. 4-20 NUMERIC CHARACTER HANDLING 4.7.9 The DIVIDE Statement The DIVIDE statement divides one operand into another and stores the result. The statement may contain the ROUNDED and SIZE ERROR phrases. With the exception of Formats 4 and 5, it may not contain multiple receiving operands. It may be written in any of the following formats: Format l. Format 2. Format 3. DIVIDE FIELDl INTO FIELD2 FIELD3 ... . DIVIDE FIELDl INTO FIELD2 GIVING FIELD3 FIELD4 ... . DIVIDE FIELD2 BY FIELDl GIVING FIELD3 FIELD4 Format 4. DIVIDE FIELDl INTO FIELD2 GIVING FIELD3 REMAINDER FIELD4. Format 5. DIVIDE FIELDl BY FIELD2 GIVING FIELD3 REMAINDER FIELD4. In Format 1: the receiving fields (FIELD2: FIELD3) are also the dividends. These must not be in the numeric edited category. In Formats 2 and 3, the rece1v1ng fields (FIELD3, FIELD4 are neither dividends nor divisor. These may be either numeric or numeric edited. In Formats 4 and 5, the receiving field (FIELD3) is neither a dividend nor a divisor. FIELD4 is the remainder. The receiving field and the remainder may be either numeric or numeric edited. 4.7.l~ The COMPUTE Statement The COMPUTE statement computes the value of an arithmetic expression and stores the value in the result. The statement may contain the ROUNDED and SIZE ERROR phrases. It may contain multiple receiving operands. The COMPUTE statement has the following format: COMPUTE FIELDl FIELD2 arithmetic-expression. The receiving fields (FIELDl, FIELD2) may be either numeric or numeric edited. 4.7.11 Common Errors, Arithmetic Statements The most common errors made when using arithmetic statements are: · Using an alphanumeric class field in an arithmetic statement. The MOVE statement allows data movement between alphanumeric class fields and certain numeric class fields, but arithmetic statements require that all fields be numeric. 4-21 NUMERIC CHARACTER HANDLING · Writing the ADD or SUBTRACT statements without the GIVING phrase, but attempting to put the result into a numeric edited field. · Writing a Format 2 ADD statement with the word TO; For example: ADD A TO B GIVING C. · Subtracting a 1 from a numeric counter that was described as an unsigned quantity, and testing for a value of less than zero. · Forgetting that the MULTIPLY statement, without the GIVING phrase, stores the result back into the second operand (multiplier). · Performing a series of calculations in such a way as to generate an intermediate result that is larger than 18 digits when the final result will be fewer digits. (The programmer should be careful to intersperse divisions with multiplications or to drop non-significant digits that result from multiplying large numbers (or numbers with many decimal places) . · Performing an operation on a field that contains a value greater than the precision of its data description. This can happen only if the field was disarranged by a group move or redefinition. · Forgetting that, in an arithmetic statment containing multiple rece1v1ng fields, the ROUNDED phrase must be specified for each receiving field that is to be rounded. · Forgetting that, in an arithmetic statement containing multiple receiving fields, the ON SIZE ERROR phrase, if specified, applies to all rece1v1ng fields. Only those receiving operands for which a size error condition is raised are left unaltered. The ON SIZE ERROR imperative statement is executed after all the receiving fields are processed by the OTS. 4.8 ARITHMETIC EXPRESSION PROCESSING COBOL provides language facilities for manipulating user-defined data arithmetically. In particular, the language provides the arithmetic statements ADD, SUBTRACT, MULTIPLY, and DIVIDE and the facilities of arithmetic expressions using the +, -, *, /, and ** operators. In simple terms, a given arithmetic functionality may be expressed in one of several ways. For example, consider a COBOL application in which the total yearly sales of a salesman are to be computed as the sum of the four individual sales quarters. Figure 4-9 illustrates one method of expressing a solution to this problem in COBOL: 4-22 NUMERIC CHARACTER HANDLING MOVE J TO TEMP. ADD lST-SALES TO TEMP. ADD 2ND-SALES TO TEMP. ADD 3RD-SALES TO TEMP. ADD 4TH-SALES TO TEMP GIVING TOTAL-SALES. Figure 4-9 Explicit Programmer-Defined Temporary Work Area In figure 4-9, the COBOL programmer chooses to use a series of single ADD statements to develop the final value for TOTAL-SALES. In the process of computing TOTAL-SALES, a COBOL data-name, called TEMP, is used to develop the partial sums {i.e.,· intermediate results). The important point here is that the programmer explicitly defines and declares the temporary work area TEMP in the data division of the COBOL program. That is, the attributes (i.e., class, USAGE, number of integer and decimal places to be maintained) are specified explicitly by the COBOL programmer. Figure 4-lJ below illustrates another way of expressing a solution to the problem: ADD lST-SALES, 2ND-SALES, 3RD-SALES, 4TH-SALES GIVING TOTAL-SALES. Figure 4-lJ Arithmetic Statement Intermediate Result Field Attributes Determined from Composite of Operands 4-23 NUMERIC CHARACTER HANDLING In this example, the programmer chooses to compute TOTAL-SALES with a single ADD statement. Analogous to the previous example, an intermediate result field is required to develop the partial sums of the four quarterly sales quantities. In Figures 4-9, the programmer is cognizant of this requirement, but chose to define the intermediate result area TEMP explicitly in the data division of his COBOL program. However, for the example in Figure 4-1~, the compiler defines the intermediate result field in a manner transparent to the COBOL source program. That is, the compiler allocates storage for and assigns various attributes to this "transparent" intermediate result field according to a well-defined set of rules defined by the COBOL language specification. In particular, the attributes of number-of-integer-places, number-of-decimal-places, and USAGE assigned by the software to the intermediate result field are a function of the composite of source operands in the ADD statement. (The reader should read the PDP-11 COBOL Reference Manual for details concerning the composite of operands for the arithmetic statements.) The important point here is that the ANS-74 COBOL language standard prescribes rules for determining the attributes of intermediate result fields for the arithmetic statements, and the language processor, the PDP-11 COBOL compiler, must implement those rules. As a final example, consider the following solution to our problem: COMPUTE TOTAL-SALES = !ST-SALES + 2ND-SALES + 3RD-SALES + 4TH-SALES. Figure 4-11 Arithmetic Expression Intermediate Result Field Attributes Determined by Implementor-Defined Rules In Figure 4-11, the programmer solves the problem by using a single CO~PUTE statement with an embedded arithmetic expression. Again, an intermediate result field is required and, as in Figure 4-1~, is defined by the software. However, in defining the attributes of intermediate result fields for COBOL arithmetic expressions, the ANS-74 COBOL language standard is not as helpful to the user as it could be. In fact, the COBOL language standard gives almost complete freedom to the implementor in defining the attributes of the arithmetic expression intermediate result fields. The only rules imposed by the ANS-74 COBOL language specifications are: 1. Arithmetic operations are to be combined without restrictions on the composite of operands and/or receiving fields. 2. Each implementor will indicate techniques used in handling arithmetic expressions. 4-24 NUMERIC CHARACTER HANDLING Thus, the user can and should expect differences between various implementations of ANS-74 COBOL. The rest of this section describes how the PDP-11 COBOL compiler computes the sizes of intermediate result fields. The compiler computes the size of an intermediate result field for each component operation of an arithmetic expression. Each operation can be stated as: OPl OPR OP2 where: OPl is the first operand OPR is an arithmetic operator OP2 is the second operand The size of an intermediate result is described in terms of the number of inceger places (IP) and the number of decimal places (DP). The symbol DPEXP represents the maximum number of decimal places in the entire arithmetic OPR + and - IP max(IP(OPl), IP(OP2)) + l DP max (DP (OPl), DP (OP2)) * IP IP(OPl) + IP(OP2) DP DP(OPl) + DP(OP2) I IP IP(OPl) + DP(OP2) DP max(DPEXP, max(DP{OPl), DP(OP2) + 1)) ** For exponents that convert to one-word values, a OP2 b = OP2 + DP(OPl) Otherwise, a= 9, if IP(OP2) = l, otherwise, a = 19 b DPEXP and IP DP IP(OPl) * a max(DPEXP, DP(OPl) * b) 4-25 CHAPTER 5 TABLE HANDLING 5.1 INTRODUCTION With COBOL, as with any other language, any data item to which the program refers must be uniquely identified. This unique identification of data items is usually accomplished by assigning a unique name to each item. However, in many applications this is tedious and inconvenient; often programs require too many names for items that have different names but contain the same tvoe of information. Tables provide a simple solution to this problem. PDP-11 COBOL includes full table handling capabilities as outlined for standard COBOL in the 1974 ANSI Standards. A table is a repetition of one item (element) in memory. This repetition is accomplished by the use of the OCCURS clause in the data description entry. The literal value in the OCCURS clause causes the software to duplicate the data description entry as many times as indicated by that value, thus creating a matrix or table. The elements may be initialized with the VALUE clause or with a procedural instruction. They may contain synchronized or unsynchronized data. They may be accessed only with subscripted procedural instructions. A subscript is a parenthesized integer or data name (with an integer value). The integer value represents the desired occurrence of the element. This chapter discusses how to set up tables and access them accurately and efficiently. It attempts to cover any problems that may be encountered while handling tables. Read it through carefully before setting up tables with PDP-11 COBOL. Section 6 of the PDP-11 COBOL Reference Manual for the PDP-11 contains reference information on the individual table handling instructions (OCCURS, USAGE IS INDEX, SET, and SEARCH). 5.2 DEFINING TABLES To define a table with PDP-11 COBOL, simply complete a standard data description for one element of the table and follow it with an OCCURS clause. The OCCURS clause contains an integer which dictates the number of times that element will be repeated in memory, thus creating a table. 5-1 TABLE HANDLING The OCCURS phrase has two formats: Format 1 OCCURS integer-2 TIMES ASCENDING } [{ DESCENDING KEY IS data-name-2 [INDEXED BY index-name-1 [, ... J [, da ta-name-3] J index-name-2] ... Format 2 OCCURS integer-! TO integer-2 TIMES DEPENDING ON data-name-1 ASCENDING } [{ DESCENDING KEY IS data-name-2 J [, data-name-3] ··· J [INDEXED BY index-name-! [ , index-name-2] ... In either format, the system generates a buffer large enough to accommodate integer-2 occurrences of the data description. Therefore, the amount of storage allocated in either case is equal to the amount of storage required to repeat the data entry integer-2 times. The software will automatically map the elements into memory. When mapping a table into memory, the software follows the rules for mapping which depend on whether the element contains synchronized items or not. If they do not contain synchronized items, the software maps them into adjacent memory locations and the size of the table can be easily calculated by multiplying the size of the element times the number of occurrences (5Xl0 for the table illustrated in Figure 5-1, or 50 bytes of memory) . 01 A-TABLE 03 A-GROUP PIC X(5) OCCURS 10 TIMES. Figure 5-1 Defining a Table 5.2.1 The OCCURS Phrase - Format 1 When Format 1 is used, a fixed length table is generated, whose length (number of occurrences) is equal to the value specified by integer-2. This format is useful for storing large amounts of frequently used reference data whose size never changes. Tax tables, used in payroll deduction programs, are an excellent example of where a Format 1 (fixed length} table might be used. 5.2.2 The OCCURS Phrase - Format 2 Format 2 is used to generate variable length tables. When used, a table whose length (number of occurrences} is equal to the value specified by data-name-i is generated. 5-2 TABLE HANDLING NOTE Data-name-1 must always be a positive integer whose value is equal to or greater than integer-1 but not greater than integer-2. Unlike format 1 tables, the number of occurrences of data items in format 2 tables can be dynamically expanded or reduced to satisfy user needs. By generating a variable length table, the user is, in effect, saying; "build me a table that can contain at least integer-1 occurrences, but no more than integer-2 occurrences, and set its number of occurrences equal to the ~alue specified by data-name-1". Data-name-1 always reflects the number of occurrences available for user access. To expand the size (number of occurrences available for use) of a table, the user need only increase the value of data-name-1 accordingly. Likewise, reducing the value in data-name-1 will reduce the number of occurrences available for user access. 5.3 MAPPING TABLE ELEMENTS As mentioned in Section 5.2, when the software detects an OCCURS clause in an unsynchronized item, it maps the table elements into adjacent locations in memory. Consider the following data description of a simple table and the way it is mapped into memory: Table Description: 01 A-TABLE. 03 A-GROUP PIC X(5) OCCURS 10 TIMES. Memory Map: words bytes l1B111TI1ft I J1 I VLITIB A-GROUP A-GROUP A-GROUP A-GROUP Figure 5-2 Mapping a Table into Memory The data description in Figure 5-2 causes the software to set up ten items of five bytes each (elements) and place them in adjacent ascending memory locations for a total of 50 character positions, thus creating a table. Since the length of each A-GROUP element is odd (5), the memory addresses of each subsequent element will alternate between odd and even locations. The SYNCHRONIZED clause causes the software to add a fill byte to items that contain an odd number of bytes, thereby making the number of bytes in that item even. This ensures that each subsequent occurrence of the element will not alternate between odd and even addresses, but will map the same (odd or even) as the first repetition of that element. 5-3 TABLE HANDLING If the data description of A-GROUP contained a SYNCHRONIZED clause, the software would map it quite differently. If A-GROUP were synchronized, it would expand its length to three words. The item will, by default, be synchronized to the left occupying the first five characters of the three words. The software supplies a padding character to fill out the third word. This padding character is not a part of the A-GROUP element and table instructions referring to A-TABLE will not detect the presence or absence of the character. The padding character does, however, affect the overall length of the group item and, hence, the table. Without the SYNCHRONIZED clause, A-TABLE required only 50 character positions; now, with the clause, it requires 60 character positions. (This length includes the last padding character -- following the tenth element in the table.) Although the SYNCHRONIZED clause has little value when used with alphanumeric fields, an understanding of the concept is essential before attempting to use COMP and INDEX data items in tables. The software automatically synchronizes all COMP and INDEX usage data items, and will most probably alter the size of any table (often drastically) that contains these data types. Consider the following illustration of a synchronized data item being mapped by the software: Table Description: 01 A-TABLE. 03 A-GROUP OCCURS 20 TIMES. 05 ITEMl PIC X. 05 ITEM2 PIC 8999 COMP. Memory Map: words bytes A-GROUP A-GROUP A-GROUP A-GROUP Figure 5-3 Synchronized COMP Item in a Table 1--ITEMl 2--ITEM2 S--SLACK BYTE Since the software synchronizes the ITEM2 fields (COMP), these fields each occupy a single word in memory; thus, a slack byte follows each occurrence of ITEMl. Each repetition of A-GROUP consumes four bytes of memory -- one byte for ITEMl, one byte for the slack byte, and two bytes for ITEM2. A-TABLE, then, requires 80 bytes of memory (20 elements of four bytes each). Now, consider the e.ffect of adding a 1-byte field to A-TABLE. If we place the field between ITEMl and ITEM2, it will take the space formerly occupied by the slack byte. This has the effect of adding a data byte but leaving the size of the table unchanged. Consider the foiiowing iiiustration: 5-4 TABLE HANDLING Table Description: 01 A-TABLE. 03 A-GROUP OCCURS 20 TIMES. 05 ITEMl PIC X. 05 ITEM3 PIC X. 05 ITEM2 PIC 8999 COMP. Memory Map: words bytes ~ liii- li2· Dii· 2 ... 1--ITEMl 2--ITEM2 3--ITEM3 A-GROUP A-GROUP A-GROUP Figure 5-4 Adding a Field without Altering the Table Size If, however, we place the 1-byte field after ITEM2, it has the effect of adding its own length plus another slack byte. Now, each element requires six full bytes and the complete table consumes 120 bytes of memory (6X20) ! This is due to the fact that the first repetition of ITEMl falls on an even byte and, in order to keep the mapping of each A-GROUP element the same, the software allocates each successive repetition of ITEMl to an even byte address. Thus, it assigns ITEM3 to the even byte of the third word and adds a slack byte to guarantee that the next element begins on an even byte. Consider the following illustration: Table Description: 01 A-TABLE. 03 A-GROUP OCCURS 20 TIMES. 05 ITEMl PIC X. 05 ITEM2 PIC 8999 COMP. 05 ITEM3 PIC X. Memory Map: Odd or Even E 0 E 0 E 0 E 0 E 0 E 0 E 0 E 0 E 0 ~~~~:I..---1-k-~...-?J-I-2~1-~-M-fililil...-i-v---..-2-v-2 ~-@---rl-Y-~-~~...-i-g_2_I.--l3_b_J:@--r----..--1 A-GROUP A-GROUP A-GROUP Figure 5-5 Adding One Byte which Adds Two Bytes to the Element Length NOTE The illustrations in this section show each byte with an even address (E} as the leftmost byte, and each byte with an odd address (O) as the rightmost byte. (The two bytes, odd and even, are reversed in actual memory.) 5-5 TABLE HANDLING If, however, we use a FILLER byte to force the first allocation of ITEM! to occur on an odd byte, A-GROUP again requires only four bytes and no slack bytes. Figure 5-6 illustrates this. Since the FILLER item occupies the even byte of the first word, ITEM! falls on an odd byte. The software requires that each repetition of ITEM! must be an even number of bytes in length in order to guarantee that the synchronized item(s) will map onto word boundaries. No slack bytes are needed and A-GROUP elements are again only foqr bytes long, and A-TABLE requires only 81 bytes. Table Description: 01 A-TABLE. 03 FILLER PIC X. 03 A-GROUP OCCURS 20 TIMES. 05 ITEMl PIC X. 05 ITEM2 PIC S999 COMP. 05 ITEM3 PIC X. Memory Map: Ji hlllilJillifilihl]illf odd or even E 0 E 0 E 0 E 0 E 0 E 0 E 0 .. . words bytes I .. . F 1 2 2 3 1 2 2 3 1 2 2 3 .·. FILLER A-GROUP A-GROUP A-GROUP Figure 5-6 Forcing an Odd Address By Adding a 1-Byte FrLLER Item to the Head of the Table If we try to force ITEMl onto an odd byte with a SYNCHRONIZED RIGHT clause, the software maps ITEMl into the odd byte, but prohibits all repetitions of the element from using the even byte. Thus, the first repetition of A-GROUP has a slack byte at its beginning and, so that the next element can begin (with a slack byte) at an even address, another slack byte (odd) following ITEM3. This expands the element length to six bytes and the table length to 120 bytes. Table Description: Memory Map: 01 A-TABLE. 03 A-GROUP OCCURS 20 TIMES. 05 ITEM! PIC X SYNCHRONIZED RIGHT. 05 ITEM2 PIC S999 COMP. 05 ITEM3 PIC X. A=GROUP A-GROUP Figure 5-7 The Effect of a SYNCHRONIZED RIGHT Clause Instead of a FILLER Item as shown in Figure 5-6 5-6 TABLE HANDLING To determine how the software will map a given table, apply the following two rules: 1. The software maps all items in the first repetition of a table element into memory words as with any item properly defined with a data description, obeying any implicit or explicit synchronization requirements. 2. If the first repetition contains any elementary items with implicit or explicit synchronization, the software maps each successive repetition of the element into memory words in the same way as the first repetition. It does this by adding one slack byte, if necessary, to make the size of the element even. 5.3.l Initializing Tables If a table contains only DISPLAY items, it can be set to any desired initial value (initialized). To initialize a table, simply specify a VALUE phrase on the record level preceding the item containing the OCCURS clause. The sample data definitions, below, will set up initialized tables: Table Description: 01 A-TABLE VALUE IS 11 JANFEBMARAPRMAY JUNJULAUGSEPOCTNOVDEC 11 · 03 MONTH-GROUP PIC XXX USAGE DISPLAY OCCURS 12 TIMES. Memory Map: words byte contents~..._..._~_.__....L--+---'-_.__-+-_,__,_-t-___.____._-+~_.__._-+---'----'---+--'--'--'--+--- MONTH-GROUP MONTH-GROUP MONTH-GROUP MONTH-GROUP MONTH-GROUP MONTH-GROUP MONTH-GROUP MONTH-GROUP Figure 5-8 Initializing Tables Often a table is too long to initialize with a single literal, or it contains items that cannot be initialized (numeric, alphanumeric, or COMP). These items can be individually initialized by redefining the group level preceding the level that contains the OCCURS clause. Consider the following sample table descriptions: 5-7 Table Description: TABLE HANDLING 01 A-RECORD-ALT. 05 FILLER PIC XX VALUE "AX". 05 FILLER PIC 99 COMP VALUE 1. 05 FILLER PIC XX VALUE "BX". 05 FILLER PIC 99 COMP VALUE 2. 01 A-RECORD REDEFINES A-RECORD-ALT. 03 A-GROUP OCCURS 26 TIMES. 05 ITEMl PIC X. 05 ITEM2 PIC S99 COMP. Memory Map: words byte contents at initialization time A-GROUP A-GROUP Figure 5-9 Initializing Mixed Usage Fields In the preceding example, the slack bytes in the alphanumeric fields (ITEMl) are being initialized to X. Table Description: 01 A-RECORD-ALT. 03 FILLER PIC X(30) VALUE IS "AAAAAAAAAABBBBBBBBBBCCCCCCCCCC". 03 FILLER PIC X(30) VALUE IS "DDDDDDDDDDEEEEEEEEEEFFFFFFFFFF". (etc. ) 01 A-RECORD REDEFINES A-RECORD-ALT. 03 ITEMl PIX X(lO) OCCURS 26 TIMES. Memory Map: word I II IV byte A A A A A A contents at initialization ITEMl time VI VII VIII IX X XI BBBBBB BBBBCC ITEMl Figure 5-10 Initializing Alphanumeric Fields In the preceding example, each FILLER item initializes three 10-byte table elements. When redefining or initializing table elements: allow space for any slack bytes that may be added due to synchronization (implicit or explicit). The slack bytes do not have to be initialized; however, they may be and, if initialized to an uncommon value, they may even serve as a debugging aid for situations such as a statement referring to the record level above the OCCURS clause or another record redefining that level. 5-8 TABLE HANDLING Sometimes the length and format of table items are such that they would best be initialized by statements in the Procedure Division. This initialization coding could be executed once and then overlaid (due to the automatic segmentation feature) if the entire Procedure Division is too large to be held in memory at one time. Once the OCCURS clauses have established the necessary tables, the program must be able to access the elements of those tables individually. Subscripting and indexing are the two methods provided by COBOL for accessing individual elements. 5.4 SUBSCRIPTING AND INDEXING To refer to a particular element within a table, simply follow the name of the desired element with a parenthesized subscript or index. A subscript is an integer or a data-name that has an integer value; the integer value represents the desired occurrence of the element an integer value of 3, for example, refers to the third occurrence of the element. An index is a data-name that has been named in an INDEXED BY phrase in the OCCURS clause. 5.4.1 Subscripting with Literals A literal subscript is simply a parenthesized integer whose value represents the occurrence number of the desired element. In figure 5-11, the literal subscript in the MOVE instruction (2) causes the software to move the contents of the second element of the table, A-TABLE, to I-RECORD. Table Description 01 A-TABLE. 03 A-GROUP PIC X(5) OCCURS 10 TIMES. Procedural Instruction MOVE A-GROUP(2) TO I-RECORD. Figure 5-11 Literal Subscripting If the table has more than one level (or dimension), follow the name of the desired item with a list of subscripts, one for each OCCURS clause to which the item is subordinate. The first subscript in the list applies to the first OCCURS clause to which the item is subordinate. (This is the most encompassing level -- A-GROUP in the following example.) The second subscript in the list applies to the next most encompassing level, and the last subscript applies to the lowest level OCCURS clause being accessed (or the desired occurrence number of the item named in the procedural instruction -- ITEMS in the following example). Consider Figure S-12; the subscripts (2,11,3) in the MOVE instruction cause the software to move the third repetition of ITEMS in the eleventh repetition of ITEM3 in the second repetition of A-GROUP to I-FIELDS. (For illustration simplicity, I-FIELDS is not defined.) (ITEMS(l,1,1) would refer to the first occurrence of ITEMS in the table and ITEMS(S,20,4) would refer to the last occurrence of ITEMS.) S-9 TABLE HANDLING Table Description 01 A-TABLE. 03 A-GROUP OCCURS S TIMES. OS ITEMl PIC X. OS ITEM2 PIC 99 COMP OCCURS 20 TIMES. OS ITEM3 OCCURS 20 TIMES. 07 ITEM4 PIC x. 07 ITEMS PIC xx OCCURS 4 TIMES. Procedural Instruction MOVE ITEMS(2, 11, 3) TO I-FIELDS. Figure S-12 Subscripting a Multi-Dimensional Table NOTE Since ITEMS is not subordinate to ITEM2, an occurrence number for ITEM2 is not permitted in the subscript list. Figure S-13 summarizes the subscripting rules for each of the above items and shows the size of each field in bytes. NAME OF FIELD NUMBER OF SUBSCRIPTS REQUIRED TO REFER TO THE NAMED FIELD A-TABLE A-GROUP I TE Ml ITEM2 ITEM3 ITEM4 ITEMS NONE ONE ONE TWO TWO TWO THREE * Plus a slack byte Figure S-13 Subscripting Rules for a Multi-Dimensional Table SIZE OF FIELD 1110 222 l* 2 9 1 2 S.4.2 Operations Performed by the Software When a literal subscript is used to refer to an item in a table, the software performs the following steps to determine the exact address of the item: 1. The compiler converts the literal to a 1-word binary value. 2. The compiler range checks the subscript value (the value must not be less than 1 nor greater than the number of repetitions specified by the OCCURS clause) and prints a diagnostic message if the value is out of range. 3. The compiler decrements the value of the subscript by 1 and multiplies it by the size of the item that contains the OCCURS clause corresponding to this subscript, thus forming an index value; it then stores this value, plus the literal subscript, in the object program. S-10 TABLE HANDLING 4. At object execution time for a fixed length table, the run time system adds the index value (from 3 above) to a base address, thus determining the address of the desired item. For a variable length table reference, the procedure for fixed length tables is preceded by the procedure described in Section 5.4.6. 5.4.3 Subscripting with Data-Names As discussed earlier in this section, subscripts may also be specified using data-names instead of literals. To use a data-name as a subscript, simply define it as a numeric integer (COMP or DISPLAY). It may be signed, but the sign must be positive at the time it is used as a subscript. The sample subscripts in figure 5-14 refer to the same element accessed in Figure 5-12, (2' 11, 3) . Data Descriptions of Subscript data-names 01 KEY! PIC 99 USAGE DISPLAY. 01 KEY2 PIC 99 USAGE COMP. PIC £\, T7rii-,::7' "'l U.1. L'\.C..I..J ,... £\ £\ ~-:J-:J. Procedural Instructions MOVE 2 TO KEY!. MOVE 11 TO KEY 2 . MOVE 3 TO KEY3. GO TO TABLERTN. TABLERTN. MOVE ITEM5(KEY1 KEY2 KEY3) TO I-FIELDS. Figure 5-14 Subscripting with Data-Names 5.4.4 Operations Performed by the OTS When a data-name subscript is used to refer to an item in a table, the OTS performs the following steps at object execution time: 1. If the data-name's data type is DISPLAY, the software converts it to a !-word binary value. 2. For fixed length tables, the software range checks the subscript value (the value must not be less than 1 nor greater than the number of repetitions specified by the OCCURS clause) and terminates the object program (with a diagnostic message) if it is out of range. For variable length tables, the procedure described in Section 5.4.6 is followed. 3. The software decrements the value of the subscript by 1 and multiplies it by the size of the item that contains the OCCURS clause corresponding to this subscript, thus forming an index value. 4. The software adds the index value (from 3 above) to a base address, thus determining the address of the desired item. 5-11 TABLE HANDLING 5.4.5 Subscripting with Indexes The same rules apply for the specification of indexes as apply to subscripts except that the index must be named in the INDEXED BY phrase of the OCCURS clause. An index-name item (an item named in the INDEXED BY phrase of the OCCURS clause) has the ability to hold an index value. (The index value is the product formed in step 3 of the operations performed by the software for literal or data-name subscripts ~- the relative location, within the table, of the desired item.) The compiler allocates a 2-part data item for each name that follows an INDEXED BY phrase. These index-name items cannot be accessed as normal data items; they cannot be moved about, redefined, written to a file, etc. However, the SET verb can change their values and relation tests can examine their values. One part of the 2-part index-name item contains a subscript value and the other part contains an index value. Consider the following illustration: SUBSICNRDIEPXT PPAARRTT -------:1'-1-----------1l Figure 5-15 Index-Name Item Whenever a SET statement places a new value in the subscript part, the software performs an index value computation and stores the result in the index part. Only the subscript part of the item acts as a sending or receiving field. The index part is never altered by any other operation and is never moved to another item. It is used only when the index-name is used as an index referring to a table item. The sample MOVE statement in Figure 5-16 would move the contents of the third repetition of A-GROUP to I-FIELD. (For illustration simplicity, once again, I-FIELD is not defined.) Table Description 01 A-TABLE. 03 A-GROUP OCCURS 5 TIMES INDEXED BY IND-NAME. Procedural Instructions SET IND-NAME TO 3. MOVE A-GROUP (IND-NAME) TO I-FIELD. Figure 5-16 Subscripting With Index-name Items 5.4.6 Operations Performed by the OTS The OTS performs the following steps when it executes the SET statement: 1. The OTS converts the c>ontents of the sending field of the SET statement to a 1-word binary value. 2. The OTS range checks the value (the value must not be less than 1 nor greater than the number of repetitions specified in the OCCURS clause) and terminates the object program with a diagnostic message if it is out of range. 5-12 TABLE HANDLING 3. The OTS decrements the value by 1 and multiplies it by the size of the item that contains the OCCURS clause, thus forming an index value. For fixed length tables, once the SET statement has been executed and the software has encountered the index-name item as an index, it only has to add the index value (from 3 above) to a base address to determine the address of the desired item. Since this is the only action performed, the execution speed of a procedural statement with an indexed data-name is equivalent to a reference with a literal subscript. For a variable length table, when the index-name is encountered as an index, the procedure described in Section 5.4.6 is invoked before following the fixed length table logic. However, the SET statement itself is not impacted by the fixed/variable characteristic of the associated table. PDP-11 COBOL initializes the value of all index-name items to a subscript value of 1 (index value of 0), hence an attempt to use an index-name item as an index before it has been the receiving field of a SET verb will not result in an out-of-range termination. NOTE Initialization of index-name items is an extension to the ANSI COBOL standards. Users concerned with writing COBOL programs that adhere to standard COBOL should not rely on this feature. 5.4.7 Relative Indexing To perform relative indexing, when referring to a table item, simply follow the index-name with a plus or minus sign and an integer literal. Relative indexing, albeit easy to use, causes additional overhead to be generated each time a table item is referenced in this fashion. At compile time, the compiler has to compute the index value corresponding to the specified literal; and transfer this index value to the object file. At object run time, the index value for the literal is added to (+) or subtracted from (-) the index value of the index-name. The resulting index value is stored in a temporary location. The OTS adds this temporary index value to the base address of the table to determine the address of the desired table item. At this point, a range check is performed on the temporary index value to insure that the resulting index is within the permissible range for the table. For fixed length tables, this index manipulation is relatively straightforward. The size of the table is known at compilation time, and this size is passed along to the OTS in the object file. A simple compare against this fixed value is all that is required to determine if a given index value is within the permissable range for the table. For a variable length table, h'owever, the process is more involved. The current number of occurrences (data-name-1) for the table must be determined and range checked; the index value corresponding to the current number of occurrences must be calculated; then the temporary index value must be range checked using the current number of occu-r rence' s index value. 5-13 TABLE HANDLING The object time overhead required for the relative indexing of variable length tables is significantly greater than that required for fixed length tables. In either case, the index portion of the index-name is not altered. If any of the range checks reveals an illegal (out of range) value, execution is terminated with an apropriate error message. The sample MOVE instruction in Figure 5-17 moves the fourth repetition of A-GROUP to I-FIELD if IND-NAME has not been altered with a SET verb. MOVE A-GROUP{IND-NAME + 3) TO I-FIELD. Figure 5-17 Relative Indexing The actual operation of accessing a table element is shorter at run time since the compiler has calculated the index value of the literal at compile time and has stored it in the object program ready for use. Relative indexing, therefore, involves two additions and a range check during object execution. It leaves the index-name item unaltered. 5.4.8 Index Data Items Often a program will require that the value of an index-name item be stored outside of that item. It is for this purpose that PDP-11 COBOL provides the index data item. Index data items are 1-word binary integers with implicit synchronization. {The 1-word size corresponds to the subscript part of the index-name item.) They must be declared with a USAGE IS INDEX phrase and they may be modified (explicitly) only by the SET statement. Subscript Part~~~---1-~~~~~~-- Figure 5-18 Index Data Item Since index data items are considered to contain only the subscript part of an index-name item, when a SET statement "moves" an index-name item to an index data item, only the subscript part is moved. Likewise, when a SET statement "moves" an index data item to an index-name item, a new index value is computed by the software. This is done to guarantee that an index-name item will always contain a good index value. The only advantage gained by using index data items over numeric, COMP items is that the data description is shorter, easier to write, and more self-documenting. Further, the restrictions placed on access to index items may be useful in debugging the program. 5.4.9 The SET Statement The SET statement alters the value of index-name items and copies their value into other items. When used without the UP BY/DOWN BY clause, it functions like a MOVE statement. Figure 5-19 illustrates the legal data movements that the SET statement can perform. 5-14 TABLE HANDLING INDEX-NAME ITEM NUMERIC LITERAL (INDEX PART) INDEX DATA ITEM 1-----1- (SUBSCRIPT-PART)1---__._ "---~~~~~~----' '--~~~~~~-----' NUMERIC DATA NAME (COMP OR DISPLAY) INDEX-NAME ITEM _J!_N~~~y~~TJ. (SUBSCRIPT PART) Figure 5-19 Legal Data Movement with the SET Statement The SET statement may be used with the UP BY/DOWN BY clause to alter the value of an index-name item arithmetically. The numeric literal is added to (UP BY) or subtracted from (DOWN BY) the subscript part, and the index part is recalculated by the software after the appropriate range check against the number of repetitions for the table. The SET statement is not affected by whether the table is fixed or variable length. 5.4.10 Referencing a Variable Length Table Element at OTS Time At OTS time, when a procedural reference involves an element in a variable length table, the following procedure is used: 1. Determine the number of occurrences in the table (the value contained in data-name-1), and verify its legality. (integer-1 <= data-name-1 <= integer-2) 2. Verify that the subscript is within the legal range. (subscript <= data-name-1) If any of the above checks fails, execution is terminated with an appropriate error message. 5.4.11 Referencing a Dynamic Group at OTS Time A dynamic group is defined as a group item that contains a subordinate item that is a variable length table. At OTS time, when a dynamic group is referenced, the following procedures are followed: 1. The number of occurrences of the subordinate variable length table is determined, and checked for legality; i.e., integer-l<=data-name-l<=integer-2. If this check fails, execution terminates and the appropriate error message is issued. 2. The size of the dynamic group is calculated. The number of occurrences of the variable length table (data-name-1) is multiplied by the size of one table entry. The resulting number is then added to the fixed size of the dynamic group. 5-15 TABLE HANDLING NOTE The fixed size of a dynamic group is the size of the group up to but not including the variable length table. 5.4.12 The SEARCH Verb The SEARCH verb has two formats: Format 1, which performs a sequential search of the specified table beginning with the current index setting; and Format 2 which performs a selective (binary) search of the specified table, beginning with the middle of the table. Both formats allow the programmer to specify imperative statements within the SEARCH verb. At OTS time, an imperative statement contained within a search verb is executed only when one of the exit paths (success or failure) is taken. The failure path is defined either explicitly by the AT END statement, in which case the imperative statement which follows it is executed; or by default, in which case control is passed to the next procedural sentence. In either case (success or failure), after an imperative statement is executed, control is passed to the next procedural sentence. 5.4.13 The SEARCH Verb - Format 1 Format 1 directs the OTS to search the indicated table sequentially. The OCCURS clause for the table being searched must contain the INDEXED by phrase. Unless otherwise specified in the SEARCH statement, the first index is the controlling index for the table search. The search begins with the current index setting, and progresses through the table, augmenting the index by one as each occurrence is interrogated. If any of the specified conditions is true (success), the associated imperative statement is executed; the search exits; and the index remains at the current setting. If the possible number of occurrences for the table is exhausted before any of the specified conditions are met, the specified failure exit path is taken. That is, either the AT END exit path (if specified) is taken, or control is passed to the next procedural sentence. Figure 5-20 contains an example of using the SEARCH verb to search a table in a serially. Associated with Format 1 is the optional VARYING phrase. This phrase can be specified by using any of the following methods: 1. default ~ phrase omitted 2. VARYING index-name-n 3. VARYING identif ier-2 4. VARYING index-name-2 5-16 TABLE HANDLING NOTE The following is true regardless of which of the above methods is used. a. An index name associated with the table is methodically augmented by one, by the OTS, for each cycle of the serial search. This controlling index, when compared to the allowable number of occurrences for the table, dictates the permissible range of search cycles at OTS time. When an exit occurs (success or failure), this index remains at the current setting. b. The OTS will not initialize the index when the search begins. It is the programmers responsibility to insure that the initial index setting is the appropriate one. The OTS will begin processing the table with the setting it finds when the search is initiated. . _ When method 1 -- ----I i <:! 11<:!on +-ho F.- ir<: .... .._ !- +-- W6. .. _ i n n o v ..._.., .. _ _ , .. .n.,..~ ,_,.m ,,...o.... f \ .i -. ..n.. _n._o,.v., -n .. .. ~,~m.....,o--1_\.I associated with the table is used as the controlling index. Only this index is set to consecutive values by the OTS serial search processor. See Figure 5-20, Example 2, for an example of using method 1. When method 2 is used, index-name-n is any index that is associated with the table being searched. It becomes the controlling index for the table. It alone is set to consecutive values by the OTS search processor. See Figure 5-20, Example 3, for an example of using method 2. When method 3 is used, identifier-2 is augmented by one each time the first index (controlling index) for the table is augmented by one. Identifier-2 is not a substitute index. It merely allows the programmer to maintain an additional pointer to elements within a table. See Figure 5-20, Example 4, for an example of method 3. When method 4 is used, index-name-2 is an index that is associated with a table other than the one being searched. Each time the controlling index (1st index for the table) of the searched table is augmented, index-name-2 is also augmented. See Figure 5-20, Example 5. 5.4.14 The SEARCH Verb - Format 2 Format 2 is used to direct the OTS to search the indicated table selectively. The selective (binary) search is predicated upon the ASCENDING/DESCENDING KEY attributes of the table being searched. Therefore, an ASCENDING and/or DESCENDING KEY(s) must be specified in the OCCURS clause that defines the table, to inform the OTS that the keys are stored within the table in ascending or descending order. The INDEXED BY phrase must also be specified. When the binary search is executed, the OTS uses the first or only index associated with the table as the controlling index for the search. 5-17 TABLE HANDLING The selective (binary) search is implemented in the OTS as follows: 1. The OTS examines the range of permissible values for the index of the table being searched; selects the median value; and assigns this median value to the index. 2. The OTS then proceeds to process the sequence of simple tests for equality, beginning with the first, with the index set to the median value. 3. If all of the tests for equality are true (success), the search is terminated; the associated imperative statement is executed; the search exits; and the index retains its current value. 4. If any of the tests for equality is false, the following results occur. a. The OTS determines if all of the possible occurrences for the table have been tested. If the table has been exhausted, the imperative statement which accompanies the AT END statement (if specified) is executed. In either case, control is passed to the next procedural statement. b. The OTS will now determine which half of the table is to be eliminated from further consideration. This determination is predicated on whether the key being tested is in ascending or descending order, and whether the test failed because of a greater than or less than comparison. For example, if the key values being tested are stored in ascending order, and the median table element being tested is greater than the value being tested for equality, the OTS will assume that all key elements following the one tested are also greater than the value being tested for equality. Therefore, the lower half of the table, those items which follow the current index setting, are no longer in contention. c. Once the direction of search is determined, half of the table is eliminated from further consideration. A new range of permissible index values is computed from the remaining half of the table. d. Processing begins all over again from step 1. See Figure 5-20, Example 6, for an example of searching a table using Format 2 of the SEARCH verb. 5-18 TABLE HANDLING FED·TAX·TABLES, 02 ALLOWANCE·DATA, 03 FILLER PIC XC70) VALUE "0001440 "0202880 "0304320 "0405760 "0$07200 1 0&08oU0 "0710080 "0811520 "0q12~60 "10144~0"· 02 ALLOWANCE·TABLE REDEFINES ALLOWANCE·OATA, 03 FED·ALLOWANCES OCCURS 10 TIMES ASCENDING KEV lS ALLOWANCE·NUMBER INDEXED BV IND·1, 04 ALL0W4NCE·NUMBER PIC XX, 04 ALLOWANCE P?C qqqv99, 02 SINGLES·DEOUCTION·OATA, 03 FILLER PIC XC112) VALUE ·~~·~nAL·A~~~~-~~ . ~C~~~~O(~~~~~~lC "0~700115000b7220 "115001830016321.3 1 1s3002400031qo21 "2400027900~3q32b "2790034o005U0730 ·1ab00qqqqq7u173~"· 02 SINGLES·OEOUCTION·TABLE REDEFINES SINGLES·OEDUCTION·OATA, 03 SINGLES·TABLE OCCURS 7 TIMES ASC~NDING KEY ?S S·M!N·RANGE !·MAX·RANGE INDEXED BV IN0·2, TEMP·INOEX, 04 S·MIN·RANGE PIC qqqvqq, 04 S·MAX·RANGE PIC qqqvqq, 04 S·TAX PIC qqyqq, 04 S·PERCENT PIC yqq, 02 MARRIED·DEOUCTION·OATA, 03 FI~~£R PIC XC119) VA~UE "048000~6000000017 "0qo001130~00a1020 "173002~4000235617 "2b40034b000390325 "34600433000595328 n43300s00000e38932 "S0000qqqqq105333b", 02 MARRIED·DEDUCTION·TABLE REDEFINES MARRIED·OEOUCTION·OATA, 03 MARRIED·TABLE OCCURS 7 TIMES ·SCENOJNG KEY IS M·MIN·RANGE M·MAX·RANGE INDEXED BY IN0·0, IND·3, 04 M·MIN·RANGE PIC qqqyqq, 04 M·MAX·RANGE PIC 999V99, 04 M·T4X PIC qqqyqq, 04 M·PERCENT PIC vqq, TEMP·INDEX USAGE INDEX, Figure 5-20 Example of Using SEARCH To Search a Table 5-19 TABLE HANDLING Example 1 SINGLE. IF TAXABLE·INCOME c 024~q GO TO ENO·FEO·COMP, SET IND·2 TO 1, SEARCH SINGLES·TAB~E VARYING IND·2 AT ENO GO TO TABLE·2·ERROR WHEN TAXABLE·lNCOME · S·MIN·RANGECINO·Z) MOVE S·TAX(lN0·2) TO FEO·TAX·DEOUCTION OF OUTPUT·MASTER GO TO STORE·FEO·TAX WHEN TAXABLE·?NCOME c S·MAX·RANGECIN0·2) SUBTRACT S·MIN·RANGECIN0·2) FROM TAXABLE·INCOME MULTIPLY TAXABLE·INCOME BY S·PERCENTCIND·2) ROUNDED ADD TAXABLE·?NCOME TO FEO·TAX·DEDUCTION OF OUTPUT·MASTER, Example 2 SINGLE, IF TAXABLE·INCOME c 024qq GO TO ENO·FED·COMP, SET IND·2 TO 1. SEARCH SINGLES·TABLE VARVING IND·2 AT END GO TO TABLE·2·ERROR WHEN TAXABLE·INCOME · S·MIN·RANGECIN0·2) MOVE S·TAXCIND·2) TO FED·TAX·OEOUCTlON OF OUTPUT·MASTER GO TO STORE·FEO·TAX WHEN TAXABLE·INCOME c S·MAX·RANGECIND·2) SUBTRACT S·~IN·RANGECINO·c) FROM TAXABLE·INCOME MULTIPLV TA~ABLE·INCOME BY S·PERCENTCIN0·2) ROUNDED ADO TA~ASLE·tNCOME TO FED·TAX·O!DUCTION OF OUTPUT·MASTER, Example 3 MARRIED, IF TAXABLE·INCOME c 047q~ ~OVE ZEROS TO FEO·T·X·OEDUCTION OF OUTPUT·MASTER, GO TO ENO·FEO·COMP, SET INO·l TO 1. SEARCH MARRIED·TABLE VARYING IND·3 AT END GO TO TABLE·3·ERROR WHEN TAXABLE·INCOME · M·MIN·RANGECIND·3) MOVE M·TAXClND·3) TO FED·TAX·OEOUCTION OF OUTPUT·MASTER, GO TO STORE·FED·TA.X, WMEN TAXABLE·INCOME c M·MAX·RANGE(IN0·3) MOVE M·TAXCINO·l) TO FED·TAX·OEOUCTION OF OUTPUT·MASTER, SUBTRACT M·MIN·RANGECIND·3) FROM TAXABLE·INCOME ROUNDEO, MULTIPLY TAXAB~E·INCOME BY M·PERCENTCIN0·3) ROUNDED, ADO .TAXABLE·INCOME TO FEO·TAX·OEDUCTION OF OUTPUT·MASTER ROUNOEO, GO TO STORE·FED·TAX, Figure 5-20 (Cont.) Example Of Using SEARCH To Search a Table 5-20 TABLE HANDLING SINGLE, IF TAXABLE·INCOME < 021q~ GO TO ENO·FED·COMP, SET IND·2 TO 1. SEARCH SINGLES·TAB~E VARYING TEMP·IN.DEX AT ENO GO TO TABLE·2·ERROR WHEN TAXABLE·INCOME : S·MIN·RANGECIN0·2) MOVE S·TAXCIND·2) TO FED·TAX·OEOUCTION OF OUTPUT·MASTER GO TO STORE·FED·TAX WHEN TAXABLE·INCOME c S·MAX·RANGECIN0·2) SUBTRACT S·MIN·RANGECIND·2) FROM TAXABLE·INCOME MULTIPLY TA.XABLE·INCOME BV S·PERCENTCIN0·2) ROUNDED ADO TAXAB~E·INCOME TO FED·TAX·DEOUCTION OF OUTPUT·MASTER, Example 5 SINGLE, !F TAX·BLE·!NCOME < 024qq GO TO ENO·FEO·COMP, SET IN0·2 TO 1, SEARCH SING~ES·TAS~E VARYING IND·0 AT ENO GO TO TAB~E·2·ERROR = WHEN TAXAB~E·INCOME S·MIN·RANGECIN0·2) MOVE S·T4XCIN0·2) TO F!D·TAX·OEOUCT!ON OF OUTPUT·MASTER GO TO STORE·FED·TAX WHEN TAXABLE·INCOME c S·MAX·RANGECIN0·2) SUBTRACT S·MIN·RANGECIN0·2) FROM TAXABLE·INCOME MU~TIPLY TAXABLE·INCOME BY S·PERCENTCIN0·2) ROUNOEC ADO TAXABLE·INCOME TO FED·TAX·OEOUCTION OF OUTPUT·MASTER, Example 6 FED·DEOUCT·COMPUTATION, SET IND·1 TO 1, SEARCH ALL FED·ALLOWANCES AT END GO TO TABLE·1·ERROR WHEN ALLOWANCE·NUMBERCIND·1) m NR·OEPENOENTS OF OUTPUT·MASTER, SUBTRACT ALLO~ANCECIND·t)· FROM GROSS·WAGE OF OUTPUT·MASTER GIVING TAXAR.LE·INCOME ROUNDED, IF MARRITAL·STATUS OF OUTPUT·MASTER · "M" GO TO MARRIE"· Figure 5-20 (Cont.) Example of Using SEARCH To Search a Table 5-21 CHAPTER 6 FILE HANDLING PDP-11 COBOL provides three ways to arrange the records in its files (file organization): sequential, relative, and indexed. The ORGANIZATION in the Environment Division clause specifies the file organization for COBOL files. NOTE Indexed file organization is available only to users with RMS-11K software. PDP-11 COBOL provides three ways to process the records in its files (file access): sequential, random, and dynamic. The ACCESS MODE clause specifies the file access mode for each file used by COBOL programs. The following chart shows the three file organizations and the file access methods that apply to each of them: FILE ORGANIZATIGN SEQUENTIAL RELATIVE INDEXED FILE ACCESS SEQUENTIAL SEQUENTIAL RANDOM DYNAMIC SEQUENTIAL RANDOM DYNAMIC Once a program creates a file, all other programs that access it must describe it with the same file organization. For example, it is not possible to create a sequential file in one program and read it as a relative file with another program. However, programs can use different access methods to process records in the same file as long as the organization of the file supports the access method. 6-1 FILE HANDLING The following table compares the different file organizations with their file manipulation capabilities. Table 6-1 COBOL File Types Access Capabilities File Type (Organization) Sequential Relative Indexed Sequential Yes Yes Yes Random No Yes Yes Record Replacement Limited Yes Yes Record Addition (at end of file) Yes Yes Yes Record Insertion No Limited Yes Record Deletion No Yes Yes COBOL I/O statements allow COBOL programs to communicate with the system devices. These statements differ for sequential, relative, and indexed file organizations. Therefore, the COBOL I/O statements are discussed separately by file organization. Section 6. 1 discusses sequential organization, Section 6.2 discusses relative organization, and Section 6.3 discusses indexed organization. All file processing is performed by the COBOL object time system (OTS), regardless of organization. Table 6-2 shows which statements apply to each file organization methods: Table 6-2 I/O Statements Sequential I/O Statements Relative and Indexed I/O Statements CLOSE OPEN READ REWRITE WRITE CLOSE DELETE OPEN READ REWRITE START WRITE 6-2 FILE HANDLING 6.1 SEQUENTIAL FILE ORGANIZATION Sequential file organization arranges the records in a file serially; each record (except the first) has another record preceding it and each record (except the last) has another record following it. The records remain in the order in which they were written. Thus, COBOL statements cannot delete records from the file, insert new records between existing records, or alter the order of the existing records in any way. However, they can replace existing records (providing the length of the replacement record is identical to the original) and add new records onto the end of the file. The opening operation for reading, writing, or updating sequential files must begin with the first record in the file and proceed by the prescribed order through the file. For example, to read a particular record in the file, say the 15th record, the program must open the file and successfully execute 14 READ statements before the 15th execution can read the desired record. The program can read all of the remaining records (from record 16 on), but it cannot read any record prior to record 16 without opening the file again and beginning with record 1. Sequential files always contain an end-of-file mark that designates the end of the file. COBOL statements can write over the end-cf-file mark and, thus, extend the length of a file. (The software inserts another end-of-file mark after the last record written.) Since the end-of-file mark indicates the end of useful data, PDP-11 COBOL provides no method for reading beyond the end-of-file mark; even though the amount of space reserved for the file exceeds the amount actually used. See Figure 6-1. End-of-File Mark~~- Unused Portion of Medium Reserved for File Figure 6-1 Placement of End-of-File Mark Occasionally a file with sequential organization is so large that it requires more than one volume (such as a multi-reel magnetic tape file). An end-of-volume label marks the end of recorded information on each volume and signals the file system to switch to a new volume. On multi-volume files, the end-of-file mark appears once, at the end of the last record on the last volume. See Figure 6-2. NOTE RSTS/E does not support multi-volume files. 6-3 FILE HANDLING ? VOL. 1 ~ REC REC REC ~ REC REC REC End-of-Volume ~Label H VOL. 2 ~ REC REC REC REC REC REC End-of-Volume r---Label ? VOL. 3 { REC REC REC ? REC I~ t End-of-File Mark Figure 6-2 Placement of the End-of-Volume Label and End-of-File Mark in a Multi-Volume File 6. 1.1 RECORD SIZE If there is only one record description for a file or if there are more than one that describe the same length record, that file contains fixed-length recorrs. If the data descriptions for a sequential file consist of more than one record description, which describe several different-sized records, that file contains variable-length records. When a program creates a sequential file with variable-length records, the software places a count field in front of each record it writes into the file. This count field contains the number of character positions in the record. When a COBOL statement requests the record, the software releases a record whose length is that specified by the count field. The OTS creates and uses the count field automatically. COBOL statements cannot access it during input operations, and the 01 level record description entries must not describe it. REC REC 6. 1.2 RECORD CONTAINS Clause The RECORD CONTAINS clause, when specified without the "integer-1 TO" option, is for documentation purposes only. The compiler determines record size from the data descriptions. When the "integer-1 TO" option is specified, it forces the compiler to generate a variable length record file, even if the data descriptions describe fixed length records. Conversely, if the data descriptions for a sequential file describe variable-length records, the software sets up variable sized records automatically and ignores this clause. Even though the software ignores the values in the "integer-1 TO ... " phrase, the clause may be used in any program to document record sizes. 6-4 FILE HANDLING 6.1.3 SAME RECOR~ AREA Ciause The file system reserves a record processing area in memory for each file. This area is the current record area. The system fixes the location of the current record area when it opens the file. It also reserves a byte preceding ~nd following each current record area for possible print-control characters. The current record area always begins on an even byte boundary. Two or more files may share a current record area if a SAME RECORD AREA clause contains their ~ile-names. This clause causes the system to begin the current record area of each file listed at a common location. (Thus, current record areas that share space are aligned on their leftmost bytes.) The records do not have to be the same size and the current record areas need not have the same maximum size. The following sample statement would cause FILEA and FILEB to share the same current record area: I-0-CONTROL. SAME RECORD AREA FOR FILEA FILEB Since the system places a file's current record area in a separate location from its buffers, each READ; WRITE; and REWRITE operation causes a record to move between the buffers and the current record area. When a program reads a record from a file, modifies it, and writes it into another file, a SAME RECORD AREA clause, containing both file-names, can save an entire move of the record. The following illustration shows these record movements: WITHOUT SHARING A CURRENT RECORD AREA READ WRITE FIL EA Buff er MOVE FI LEA Current Record Area FILEB Current Record Area SHARING A CURRENT RECORD AREA FILEB Buff er READ WRITE FI LEA Buff er FILEB Buff er FILEA & FILEB Current Record Area Record Movement Caused by Reading, Processing, and Writing Records in Two Files 6-5 FILE HANDLING 6.1.4 PRINT-CONTROLLED RECORDS If a sequential file is described in a LINAGE IS clause, an APPLY PRINT-CONTROL clause, or is referenced in a WRITE statement with the ADVANCING clause specified, and the file is not going directly to a printing device (is going to be spooled), the software designates the file as a print-controlled file. Print-controlled files contain form advancing information with each record. Explicit forms control bytes are placed directly into the file. Therefore, any COBOL program trying ~n process a print-controlled file may have unpredictable results. 6. 1.5 RECORD BLOCKING The manner in which the file system blocks the records of sequential files depends on the device to which the file is assigned and the presence and format of the BLOCK CONTAINS clause. COBOL programs can assign sequential files to disk which requires fixed-length virtual blocks, and to magnetic tape, which allows variable-length blocks. The BLOCK CONTAINS clause of a COBOL program refers to a logical block size. For magnetic tape, the logical block size and virtual block size are the same. For disk, however, the logical block size is equal to one or more virtual blocks. (A virtual block on disk is 512 bytes). For files assigned to disk, the OTS packs records together (end-to-end) until a logical block is filled. The logical block is written to disk, and any portion of the previously processed record that did not fit into the logical block is put into the next logical block. This process is called record spanning in that it allows records to span virtual block boundaries. Record spanning is prohibited for files assigned to magnetic tape. For these files, only complete records (fixed or variable length) are placed end-to-end in a logical block. The OTS writes the logical block out to the file when it determines that the block is full to the extent that the next record will not fit into it. There are three ways to specify block size in a COBOL program; by default; by using the BLOCK CONTAINS integer RECORDS clause; or by using the BLOCK CONTAINS integer CHARACTERS clause. The default philosophy is to make the logical block size as small as possible; thus minimizing the memory buffer space required. By using the BLOCK CONTAINS (integer RECORDS or integer CHARACTERS) clause, you can increase the memory buffer space required. Increasing the buffer space, allows for faster I/O by decreasing the number of I/O operations required to process a file. Use the BLOCK CONTAINS clause only if you can afford the price of additional memory buffer space for the ability to process your files faster. The following paragraphs further define the three blocking methods: Default By default, the logical block size is made equal to the record size (add four bytes for variable length records on magnetic tape or two bytes for variable length records on disk). For disk files, the logical block size is rounded up to the next even multiple of 512 bytes to make the logical block size an integral number of virtual blocks. For example: 6-6 FILE HANDLING If the maximum record size for a disk file is 510 bytes, and the file contains variable length records, then the logical block size is 1024 bytes. (510 plus 4 for variable length reccrds is 514, and 514 rounded up to the next even multiple of 512 is 1024.) BLOCK CONTAINS integer RECORDS If this clause is used, the logical block size is equal to the record size (plus four bytes for variable length records on magnetic tape or two bytes for variable length records on disk) times the number of records per block. For disk files, the logical block size is rounded up to the next even multiple of 512 bytes to make the block size an integral number of virtual blocks. For example: If the record size for a fixed-length disk file is 100 bytes and the clause BLOCK CONTAINS 10 RECORDS is specified, the logical block size is 1024 bytes. (100 times 10 is 1000, and 1000 rounded up to the next even multiple of 512 is 1024). BLOCK CONTAINS integer CHARACTERS If this clause is used, the logical block size is equal to the number of characters given in the clause. If the specified number of characters is less than the actual record size (plus four bytes for variable-length records on magnetic tape or two bytes for variable length records on disk) the compiler generates a block size that is equal to the actual record size. For disk files, the specified number of characters must equal an even multiple of 512. If the number you specify is not correct, the OTS will round the logical block size it finds to the next even multiple of 512 bytes. When a program assigns a file to) magnetic tape, all programs that access the file must describe it the same way that the creating program described it in order to guarantee an accurate allocation of buffers. Note: The previous discussion has used the following format: [BLOCK CONTAINS integer RECORDS }] { CHARACTERS If the following format is used: BLOCK CONTAINS[integer-1 TOJinteger-2 [ RECORDS }] { CHARACTERS the compiler ignores integer-1, and integer-? is used as the integer. 6. 1. 6 BUFFERING When the system performs an input operation, it reads a block from the medium into the buffer, and moves a record from the buffer to the current record area. Each subsequent read operation moves a record from the buffer to the current record area. When it has exhausted the buffer (has read an entire block), the system reads another block into the buffer. 6-7 FILE HANDLING When performing an output operation, each write operation moves a record from the file's current record area into the file's buffer. Each subsequent write operation moves a record from the current record area into the buffer. The system writes the block to the medium when it has filled the buffer. The following subsections discuss the size of the buffers, the number of buffers, and the sharing of buffers. 6.1.6.1 Buffer Size - Buffer size depends on the size of the largest record in the file and on the blocking factor. For files with sequential organization, the buffer size will be at least 512 bytes. 6.1.6.2 I-0 Buffer Areas - The RESERVE clause in the Environment Division specifies the number of I-0 buffer areas to be allocated for each file. Each I-0 area represents the space for one logical block. A minimum of one and a maximum of two are permitted for sequential files. One is the default. Since two I-0 areas do not increase the speed of access and take additional memory space, it is recommended that this clause not be used. 6. 1.6.3 Buffer Space - To calculate the total amount of buffer space required for each sequential file, the following algorithm may be used: Buffer space = record size + (logical blocksize * no. of areas) + 234 In addition there are 76 bytes of buffer space that are shared among all files. 6.1.6.4 Sharing Buffer Space Among Files - The SAME AREA clause provides a simple method of sharing buffer space among several files. Two or more files may share the same buffers if the SAME AREA clause contains their file-names and only one of them is open at any time during program execution. Further~ since only one file is open at a time, the files will also share the same current record area. The size of the current record area is set to the size of the largest record description specified in the group. If only one of these files is open at a time, the following sample statement causes them all to share the same buffer and current record area. I/0-CONTROL. SAME AREA FOR FILEA FILEB FILEC. 6-8 FILE HANDLING 6.1.7 SEQUENTIAL I/O STATEMENTS PDP-11 COBOL provides the following I/O statements for sequential files: · CLOSE · OPEN · READ e REWRITE e WRITE Before a COBOL program can access a file, it must open the file; then, when the program is finished with the file, it must close the file. A COBOL program may open a sequential file in one of four modes, INPUT, OUTPUT, I-0 (input/output), or EXTEND. In INPUT mode, records may be read from the file; in OUTPUT mode the file is created and records can only be written to it; in I-0 mode, records can be read from the file and updated; in EXTEND mode, records may be added onto the end of the file. Table 6-3 shows which statements apply to the four different OPEN modes of sequential files. (The table does not include the OPEN and CLOSE statements since they apply to all modes.) Table 6-3 Sequential OPEN Modes Statement READ REWRITE WRITE Input x Open Mode Output Input-Output x x x Extend x 6.1.7.1 Opening Sequential Files - The OPEN statement makes a file available for processing by a COBOL program. A program must execute an OPEN statement for a file before it executes any other I/O statement for that file. Consider the following sample OPEN statement. It opens the file named THOREAU for input/output. The program containing this statement could, after executing it, READ, REWRITE, and CLOSE THOREAU. 6-9 FILE HANDLING ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT THOREAU ASSIGN TO "DK1:". DATA DIVISION. rlL~ SECTION. FD THOREAU PROCEDURE DIVISION. OPEN I-0 THOREAU. The OPEN statement must refer to the file by the file-name appearing in both the SELECT clause in the Environment Division and the FD paragraph in the Data Division. When the OTS executes an OPEN statement, it performs the following actions for the file named in the statement: · If the file is already open, the OTS generates an error message and performs the USE procedure section (if specified). (Section 6.8 discusses USE procedures and Section 12.3 discusses error messages.) · When opening an existing file, the attributes (i.e., record length, block size, etc.) of the file are used for accessing the file. Those specified in the program are ignored. Be sure that the attributes specified in the COBOL program agree with the actual attributes of the file. · If the SELECT clause of the File-Control paragraph declares the file OPTIONAL, the OTS displays the following message: "FILE nnn ... OPTIONAL FILE MOUNTED? YORN?" (nnn represents the file-name.) If the file is available for processing, type a Y. If not, type an N. If the file is not available (N), the OTS disables all I/O processing on the file except READ and CLOSE; a later READ statement causes program control to take the AT END imperative path. · If a SAME AREA clause contains the name of the file and none of the other files named in the clause is open, the OTS allocates buffer space for the file. · When the file has passed all of the preceding checks and is ready for opening, the OTS instructs the Record Management Services to open the file. If the Record Management Services fails to open the file, the OTS reports an error condition and performs any applicable USE procedure (if present). 6-10 FILE HANDLING · If the program is creating the file (OPEN OUTPUT) and the file description specifies LINAGE or APPLY PRINT-CONTROL, the OTS initializes the LINAGE counters. · Finally, depending on which statements apply to the open mode, the OTS enables or disables all of the program's I/O statements that refer to the file (see Table 6-3). For example, if the OPEN mode is INPUT, it enables all READ statements for that file and disables all REWRITE and WRITE statements for that file. Since the EXTEND mode simply allows the WRITE statement to add records onto the end of the file, files opened in this mode must already exist on disk or tape (only the last file on magnetic tape can be extended). If the file does not exist, the OPEN statement fails and the OTS issues an error message. 6.1.7.2 Reading Sequential Files~ The READ statement makes the next logical record of an open sequential file available to the program. If the preceding I/O operation was an OPEN: it makes the first record of the file available to the program. Consider the following example. If the last I/O operation on the file named THOREAU was an OPEN, this statement would provide the program with the first record in the file THOREAU. Every time the statement is executed, it provides the program with the next sequential record in THOREAU. Program control transfers to the paragraph named LIBRARY when an end-of-file mark is encountered during the READ. BEGIN. OPEN THOREAU. LOOP. READ THOREAU AT END GO TO LIBRARY. GO TO LOOP. If the file contains variable-length records, the program must determine the length of the record just read. No such information is supplied to the user program. NOTE RSTS/E processes records from unit record devices as variable length records. This means that records read in from a card reader or paper tape reader will have trailing blanks deleted. For example, reading blank records will not change the user record area. To avoid problems, move blanks into the record area before each read. If the file is open in the I-0 mode, the successful execution of a READ statement enables any following REWRITE of the record just read. (For further information on the REWRITE statement, see the next subsection -- 6.1.7.3.) 6-11 FILE HANDLING If the file has more than one record description, the records automatically share the same current record area. The OTS does not clear this area before it executes the READ statement (no blank filling, etc.). Therefore, if the record read by the latest READ statement does not fill the entire current record area, the area not overlaid by the incoming record remains unchanged. For example, if the file's record area contains ten 3's, and a READ operation moves in a 6-character record containing all 1 's, the current record area then contains six 1 's followed by four 3's. Consider the following example: Current Record Area with all 3's Next Record in the File 133333333331 11111111 Current Record Area after READ 111111133331 6. 1.7.3 Rewriting Records into Sequential Files - The REWRITE statement places the record just read from an input-output file back into its file on disk or magnetic tape. (The WRITE statement cannot access I-0 files.) The following sample statement writes the record, REC1, back into its file. (REC1, of course, must be a record in the file read by the preceding READ for that file.) REWRITE REC1 Before the REWRITE statement can refer to a record, the program containing the statement must meet the following conditions: · The file containing the record must be open in the I-0 mode; · The last I/O operation on the file containing the record must have been a successful READ; · The record length of the record to be rewritten must be the same as the record last read from the file. 6. 1.7.4 Writing Sequential Files - The WRITE statement releases a logical record to an output file, thereby creating an entirely new record in the file. The following sample WRITE statement releases the record PRINT-LINE to the device assigned to that record's file, then skips three lines. When it reaches the end of a page (as specified by the LINAGE clause), it causes program control to transfer to the subroutine, HEADER-RTN. WRITE PRINT-LINE BEFORE ADVANCING ~ .J T T'llr.'C'I L .Ll'lCu AT EOP GO TO HEADER-RTN. Note that this produces two blank lines following every line printed. The WRITE statement releases records to files that are open in either the output or extend mode. The following text discusses the two modes separately. · OUTPUT Mode - The WRITE statement can create the following two kinds of files in the OUTPUT mode: 6-12 FILE HANDLING 1. P~int-files - A print-file produces a listing on a printing device. The LINAGE clause, the APPLY PRINT-CONTROL clause, or a WRITE statement with the ADVANCING option included, designates a file as a print-file. One or more records containing carriage-control characters are written to perform line spacing. The WRITE statement does not have to release print-files directly to a printing device, but may also release them to a storage medium such as disk for printing at a later time. 2. Storage files - A storage file remains on disk or tape for future reference. All files that are not print-files are storage files. A sample storage file WRITE statement follows; this statement writes a record named WALDEN into a file: WRITE WALDEN · EXTEND Mode - A WRITE to a storage file opened in the EXTEND mode simply adds new records logically in sequence after the last record in the file. As the statement extenu~ Lne file, the Record Management Services automatically handles requests for additional storage space. (Print-files on disk should only be opened for EXTEND if they are being opened as a print-file.) 6.1.7.5 Closing Sequential Files - The CLOSE statement terminates processing on the file referred to in the statement. The following sample CLOSE statement terminates processing on the file named THOREAU: CLOSE THOREAU When the CLOSE statement closes a file, no other I/O operation can access that file until another OPEN statement opens the file. If the statement specifies the LOCK option, the program cannot open the file again in this run. The CLOSE statement with the LOCK clause is shown below: CLOSE THOREAU WITH LOCK The lock option has no effect on the physical device containing the file. If a SAME AREA clause contains the name of the file just closed, the program may open one of the other files named in the clause. 6.2 RELATIVE FILE ORGANIZATION Relative file organization arranges the records of the file into numbered record positions. It assigns each record position a number that identifies that position relative to the beginning of the file (the first record position in the file has record number 1, the second has record number 2, etc.). 6-13 FILE HANDLING I I I 2 3 4 5 6 7 8 9 10 Record Positions in a Relative File When a program executes a random DELETE, REWRITE, READ or WRITE operation on a relative file, the value in the relative key is used to select records from these numbered record positions in the same way that a subscript selects an item in a table. Thus, while sequential and relative files both arrange their record positions in a serial order, COBOL statements can address the record positions of a relative file by their position numbers, and successive accesses do not have to proceed through the file in a prescribed, serial, order. Another significant feature of relative file organization is that each record position does not have to contain a valid record. Although each position actually occupies one record space, a byte preceding the record on the storage medium indicates whether or not that space contains a valid record. Thus, a file may have fewer records than it has record positions, and the indicated empty record positions may be anywhere in the file. The numerical order of the record positions remains the same during all operations on a relative file; however, the accessing statements can move a record from one position to another, delete a record from a position, or insert new records into empty positions. 6.2. 1 RECORD SIZE A relative file may contain either fixed-length or variable-length records. (Fixed-length records have one or more record descriptions that describe the same size record. Variable-length records have more than one record description that describe several different sized records.) However, the COBOL compiler allocates a record area on the I/O device, equal to the largest record described plus one. This extra byte is an existence byte. It indicates whether the record area contains a valid record. For variable length records in a relative file, the software adds a two byte count field. On a write operation the actual record is written out to the I/O device not the maximum length record. The length of this record is placed in the two byte count field. On a read operation this two byte count field is used to determine the length of the record to be read in. 6.2.2 RECORD CONTAINS Clause The RECORD CONTAINS clause, when specified without the "integer-1 TO" option, is for documentation purposes only. The compiler determines record size from the data descriptions. When the "integer-1 TO" option is specified, it forces the compiler to generate a variable length record file, even if the data descriptions describe fixed length records. Conversely, if the data descriptions for a sequential file describe variable-length records, the software sets up variable sized records automatically and ignores this clause. Even though the software ignores the values in the "integer-1 TO ... " prrase, the clause may be used in any program to document record ~izes. 6-14 FILE HANDLING 6.2.3 SAME RECORD AREA Clause The SAME RECORD AREA clause is identical for all file organizations. See Section 6.1.3. 6.2.4 RECORD BLOCKING The size of a file is expressed as an integral number of virtual blocks. Virtual blocks are physical storage structures. That is, each virtual block within a file is a unit of data whose size depends on the physical medium on which the file resides. Relative files may reside only on disk. The size of virtual blocks within files on disk devices is always 512 bytes. Relative files use a logical storage structure known as a logical block or bucket. A bucket consists of from 1 to 32 virtual blocks. This distinction should be made clear. A virtual block is a physical entity which is fixed in size and cannot be changed. A bucket, however, is a logical enLiLy. Its size is airecLiy under your control. Records may span virtual block boundaries. They may never span bucket boundaries. Increasing the bucket size increases the speed of sequential processing of a file because fewer I/O operations are needed to access the smaller number of buckets in the file. On the other hand, a larger bucket size means that more memory space is taken up by the I/O buffers. Increasing the bucket size may not increase the speed of random processing of a relative file. There are three ways that the bucket size may be specified in a COBOL program; by default, by using the construct BLOCK CONTAINS integer RECORDS, or by using the construct BLOCK CONTAINS integer CHARACTERS. The default is to make the bucket size as small as possible, to m1n1m1ze the memory buffer space required. By using the BLOCK CONTAINS integer (RECORDS of integer CHARACTERS) clause, you can increase the memory buffer space required. Increasing the buffer space allows for faster I/O by decreasing the number of operations required to access a file. The following paragraphs further define the three blocking methods: Default The default philosophy is to make the bucket size as small as possible to m1n1m1ze the memory buffer space required. The algorithms for calculating the bucket size follow: Bnum= ((1+Rlen)/512)+1 Fixed length record Bnum= ((3+Rmax)/512)+1 Variable length record Where: Bnum is the number of virtual blocks per bucket. Rlen is the fixed record length (in bytes). Rmax is the maximum record length (in bytes) if the record length is variable. 6-15 FILE HANDLING The number 1 is for the existence byte. The number 3 is for the existence byte plus 2 bytes for the record length. Table 6-4 gives the bucket size for record lengths. Table 6-4 Bucket Sizes for Record Lengths Bnum Rlen Rmax 1 1-511 1-509 2 512-1023 510-1021 3 1024-1535 rn'22-1533 4 1536-2047 1534-2045 5 2048-2559 2046-2557 6 2560-3071 2558-3069 7 3072-3583 3070-3581 8 3584-4095 3582-4093 ··· · ·· · ·· BLOCK CONTAINS Rnum RECORDS If the BLOCK CONTAINS Rnum RECORDS clause is used, where Rnum is an integer, then the following algorithms are used to calculate the bucket size. Bnum= (((Rlen+l)*Rnum)/512)+1 Fixed length record or Bnum= (((Rmax+3)*Rnum)/512)+1 Variable length record Where: Bnum is the number of virtual blocks per bucket, ranging from 1 to 32. Rlen is the fixed record length (in bytes). Rmax is the maximum record length (in bytes) if the record length is variable. Rnum is the number of records per bucket as given in the BLOCK CONTAINS clause. BLOCK CONTAINS Cnum CHARACTERS If the BLOCK CONTAINS Cnum CHARACTERS clause is used, where Cnum is an integer, then Cnum is subject to the following constraints. (1) Cnum Rlen+1 Cn um Rm ax+ 3 for fixed length records or for variable length records (2) Cnum mod 512 = 0 6-16 FILE HANDLING Based on CNUM, the bucket size is calculated as follows: Bnum=Cnum/512 where: Cnum is the number of characters per bucket as given in the BLOCK CONTAINS clause. Rlen is the fixed record length (in bytes). Rmax is the maximu~ record length (in bytes) if the record length is variable. Bnum is the number of virtual blocks per bucket, ranging from 1 to 32. Violation of constraint (1) causes a warning error and the default method is used to calculate the bucket size. Constraint (2) means that Cnum should be a mu1t1p1e of 512. If not, a warning error is given and Cnum is increased to the next even m111f-;?"\1o r..f' i::1? 1.lJ.\,A_.. V..&..t"..I..'- .....,~ J I'- e The bucket size must be the same when the file is created and each time the file is accessed. Therefore, the BLOCK CONTAINS clause must never change for a particular file. Note: The previous discussion has used the following format: i L rBLOC-K CONTAINS integer RECORDS }] (CHARACTERS If the following format is used: RECORDS }] [BLOCK CONTAINS[integer-1 TO ]integer-2 { CHARACTERS the compiler ignores integer-1, and integer-2 is used as the integer. 6.2.5 BUFFERING When the system performs a sequential or random input operation, it reads a bucket from the medium into the buffer, and moves a record from the buffer to the current record area. Any subsequent sequential read operations move a record from the buffer to the current record area. When it has exhausted the buffer (has read an entire bucket), the system reads another bucket into the buffer. When performing a random read operation, the appropriate bucket is read into a file's buffer. The record is then moved from the buffer to the current record area. When performing a sequential output operation, each write operation moves a record from the file's current record area into the file's buffer. Each subsequent sequential write operation· moves a record from the current record area into the buffer. The system writes the bucket to the medium when it has filled the buffer. 6-17 FILE HANDLING When performing a random output operation, the appropriate bucket is read and the record is moved from the file's current record area into the appropriate position in the file's buffer. The system writes the bucket back out to the medium before reading any additional blocks. The following subsections discuss the size of the buffers, the number of buffers, and the sharing of buffers. 6.2.5.1 Buffer Size - Buffer size depends on the size of the largest record in the file and on the blocking factor. For relative files, buffer size must be some multiple of 256 words (512 bytes). 6.2.5.2 I/O Buffer Areas - The RESERVE clause in the Environment Division specifies the number of I/O buffer areas to be allocated for each file where an area represents the space for one bucket. A minimum of one and a maximum of two I/O areas are permitted for relative files. One is the default. It is recommended that this clause not be used, because two I/O areas do not increase the speed of access and take up additional space. 6.2.5.3 Buffer Space - To calculate the total amount of buffer space in bytes required for each Relative file, the following algorithm may be used: Buffer space = record size + bucket size + 266 In addition, there are 76 bytes of buffer space that are shared among all files. 6.2.5.4 Sharing Buffer Space Among Files - The SAME AREA clause provides a simple method of sharing buffer space among several files. This clause is identical for all file organizations. See Section 6.1.6.4. 6.2.6 RELATIVE I/O STATEMENTS The COBOL I/O statements, CLOSE, DELETE, OPEN, READ, WRITE, REWRITE, and START can refer to relative files. A COBOL program may open a relative file in one of three modes, INPUT, OUTPUT, or I-0, and access an open relative file in one of three ways, sequentially, randomly, or dynamically. In INPUT mode, records may be read from the file; in OUTPUT mode, the file is created and records may be written to the file; in I-0 mode, records may be read from the file, updated on the file, deleted from the file, or written to the file. The following table shows which statements and access methods apply to the three different OPEN modes of relative files. 6-18 FILE HANDLING Table 6-5 Relative OPEN Modes FILE ACCESS MODE STATEMENT INPUT OPEN MODE OUTPUT DELETE READ x Sequential REWRITE START x WRITE x DELETE READ x Random REWRITE START TwTR .T.. Tit;;.' x DELETE READ x Dynamic READ NEXT x REWRITE START x WRITE x I-0 x x x x x x x I v A x x x x x x NOTE The term, current record pointer, used in the following sections, refers to a location in the operating system used to determine the record number of the next available record in a file. 6.2.6.1 Access Modes - The ACCESS MODE clause in the File-Control paragraph dictates which of the three access modes may be used on that file. When the ACCESS MODE clause specifies SEQUENTIAL, the I/O statements must refer to the records in the file sequentially, starting (after opening) with the first record and stepping through with each reference to the end of the file. The I/O statements ignore record positions that do not contain valid records. When the ACCESS MODE clause specifies RANDOM, the I/O statements refer to the records in the file by record position. Thus, the statements may refer to record positions that do not contain valid records. The program must specify the desired record position number by placing a value in the file's relativ~ key: If an I/O statement refers to a record position with the relative key, and that record position does not exist (either because the position does not contain a record or because it is beyond the end of the file), the INVALID KEY imperative statement may be executed depending on the particular I/O ~tatement used. (The INVALID KEY imperative statement is explained with each of the relative I/O statements in this section.) 6-19 FILE HANDLING When the ACCESS MODE clause specifies DYNAMIC, the I/O statements may refer to the records in the file either sequentially or randomly. The OTS determines which access method to use from the OPEN mode (INPUT, OUTPUT, or I-0) and the form of the I/O statement. For example, if the statement READ ... INVALID KEY is to access an open input file dynamically, the OTS uses the relative key for random access; if the statement READ NEXT ... is to access an open input file dynamically, the OTS sequentially accesses the next existing record. The following sections (6.2.5.2 through 6.2.5.8) ~~ using the I/O statements themselves contain additional information about access modes. 6.2.6.2 Opening Relative Files - The OPEN statement for a relative file makes an INPUT, OUTPUT, or I-0 mode file available so the COBOL program can access the records in the file sequentially, randomly, or dynamically. The OPEN statement sets the current record pointer for the file to zero. For example, the following sample OPEN statement opens the file named ARTICHOKE for input, and sets ARTICHOKE's current record pointer to zero. The program containing this statement could, after executing the statement, access ARTICHOKE with READ and START statements in the sequential access mode, READ statements in the random access mode, or READ, READ NEXT, and START statements in the dynamic access mode. OPEN INPUT ARTICHOKE. When the OTS executes an OPEN statement, it performs the following actions for the file named in the statement: · If the file is already open, the OTS generates an error message and performs the USE procedure section (if specified). (Section 6.8 discusses USE procedures and Section 12.3 discusses error messages.) · When opening an existing file, the attributes (i.e., record length, block size, etc.) of the file are used for accessing the file. Those specified in the program are ignored. Be sure that the attributes specified in the COBOL program agree with the actual attributes of the file. · If a SAME AREA clause contains the name of the file and none of the other files named in the clause is open, the OTS allocates buffers space for the file. · When the file has passed all of the preceding checks and is ready for opening, the OTS instructs the Record Management Services to open the file. If the Record Management Services fails to open the file, the OTS reports an error condition and performs any applicable USE procedure (if present). · Finally, depending on ~hich statements apply to the open mode, the OTS enables or disables all of the program's I/O statements that refer to the file (see Table 6-5). For example, if the OPEN mode is INPUT, it enables all READ and START statements for that file .and disables all REWRITE, DELETE and WRITE statements for that file. FILE HANDLING If the file is being accessed randomly or dynamicallyj the program must maintain a correct value in the relative key. If the file is being accessed sequentially, the OTS ignores the value of the relative key, but updates it to contain the position number of the record being accessed. 6.2.6.3 Reading Relative Files - When applied to a file being accessed sequentially, the READ statement makes the next logical record of an open file available to the program. When applied to a file being accessed randomly, the READ statement selects a specified record from an open file and makes it available to the program. The value of the relative key for the file identifies the specific record. When applied to a file being accessed dynamically, the READ statement has two formats so that it can either select the next logical record (sequentially) or select a specified record (randomly) and make it available to the program. The READ NEXT statement takes the number in the current record pointer and finds the next present record. The following sample READ statement reads the file named ARTICHOKE sequentially and, when it exhausts the file, causes program control to transfer to the subroutine named FILEOUT: READ ARTICHOKE NEXT RECORD AT END GO TO FILEOUT. For further information concerning the mechanics of the READ NEXT statement, see Section 6.2.5.7, Specifying the Next Record to be Read. The READ with key takes the value in the relative key, moves it to the current record pointer, and reads the record being pointed to. The following READ (with key) statement reads the file named ARTICHOKE randomly, selecting records through the value in the file's relative key. If the relative key supplies a value that does not contain a valid record, the statement causes program control to transfer to the subroutine named NO-REC. READ ARTICHOKE RECORD INVALID KEY GO TO NO-REC. If the file has more than one record description, the records automatically share the same current record area. The OTS does not clear this area before it executes the READ statement (no blank filling, etc.). Therefore, if the record read by the latest READ statement does not fill the entire current record area, the area not overlaid by the incoming record remains. unchanged. For example, if the file's record area contains ten 3's, and a READ operation moves in a 6-character record containing all 1 's, the current record area then· contains six 1 's followed by four 3's. Consider the following example: Current Record Area with all 3's I 13333333333 Next Record in the File Current record Area after READ I 1111111 I I 1111113333 6-21 FILE HANDLING 6.2.6.4 Rewriting Records into a Relative File - The REWRITE statement places a record back into its file on disk or magnetic tape. The following sample statement writes the record, BREAKERS, back into its file. REWRITE BREAKERS. If the file is open in the sequential access mode, the statement rewrites the record just successfully read. If the file is open in either the random or dynamic access mode, the statement rewrites the record to the record position specified by the relative key. 6.2.6.5 Writing Records in a Relative File - The WRITE statement releases a logical record to a file. The following sample WRITE statement releases the record BREAKERS to the device assigned to that record's file. If the record already exists, program control transfers to the subroutine, WRITE-ERR. WRITE BREAKERS INVALID KEY GO TO WRITE-ERR. The WRITE statement releases records to files that are open in either the OUTPUT or I/O mode. The following text discusses the two modes separately: · OUTPUT Mode - The WRITE statement's only function with output files is to place entirely new records into the file. If more space is required for new record positions, the Record Management Services automatically extends the file size, regardless of the access mode being employed. · I/O Mode - The statement's function with input-output files is to place records in record positions that already exist and are empty. The length of the records must not exceed the maximum length record specified for the file when it was created. The relative WRITE statement creates only storage files since print-files are sequential files. The following SAMPLE statement writes a record named BREAKERS into its file: WRITE BREAKERS. 6.2.6.6 Deleting Records from a Relative File - The DELETE statement logically removes an existing record from a relative file. After a DELETE statement has successfully removed a record from a file, that record can no longer be· accessed. If the file is open in the sequential access mode, the statement removes the record just successfully read. For example, the following sample statement removes the record just read from the file named ARTICHOKE: DELETE ARTICHOKE RECORD. 6-22 FILE HANDLING If the file is open in either the random or dynamic access mode, the statement removes the record from the record position specified by the relative key. For example, the following sample statement deletes the record specified by the relative key from the file named ARTICHOKE; if the relative key supplies a value that does not contain a valid record, the statement transfers control to the subroutine named NO-REC. DELETE ARTICHOKE RECORD INVALID KEY GO TO NO-REC. 6.2.6.7 Specifying the Next Record to be Read - The START statement specifies which record in a file will be the next one to be referenced sequentially. A READ NEXT statement should follow the START statement since the READ NEXT statement reads the next record from the one being pointed to by the current record pointer. If the data area, SOMETHING, in the following example contains a 30 and position 33 in the file contains the next present record, the START statement sets the current record pointer to one less than 33 (32). The READ NEXT statement would then find the next present record, which we know is 33. WORKING-STORAGE SECTION. 77 SOMETHING PIG S99 VALUE 30. 77 ARTKEY PIG 99. RD-SET. MOVE SOMETHING TO ARTKEY. START ARTICHOKE KEY IS GREATER THAN ARTKEY INVALID KEY GO TO NEWKEY. IN1. READ ARTICHOKE NEXT RECORD AT END GO TO FILEOUT. The value of the RELATIVE KEY data item specified in the statement (ARTKEY in the preceding example) together with the conditional phrase specified in the statement (IS GREATER THAN in the preceding example) determines which record in the file will be accessed by the READ NEXT statement. The START statement uses the value in the RELATIVE KEY data item to set the current record pointer. If record positions 30 and 33 contain valid records and ARTKEY contains 30, the START statement would set the current record pointer and RELATIVE KEY data item as follows: 1. If the conditional phrase specifies KEY IS GREATER THAN ARTKEY, the statement sets the current record pointer to 32. 2. If the conditional phrpse specifies KEY IS EQUAL TO ARTKEY or NOT LESS THAN ARTKEY, the statement sets the current record pointer to 29. The READ NEXT statement takes the number in the current record pointer and finds the next present record from that number. (If the pointer contains a 30 and the next present record is in position 33, it finds record number 33). The READ NEXT statement gets that record and places its record position number (3~) into the current record pointer and the relative key. 6-23 FILE HANDLING A subsequent READ NEXT takes the number in the current record pointer, which is now 33 in our example, and finds the next present record. It fetches that record and places its record position number in the current record pointer and relative key. 6.2.6.8 Closing Relative Files - The CLOSE statement terminates processing on the file referred to in the statement. The following sample CLOSE statement terminates processing on the file named ARTICHOKE: CLOSE ARTICHOKE. When the statement closes a file, no other I/O operation can access that file until another OPEN statement opens the file. If the statement specifies the LOCK option, the program cannot open the file again in that run. If a SAME AREA clause contains the name of the file just closed, the program may open one of the other files named in the clause. 6.3 INDEXED FILE ORGANIZATION WARNING Indexed file organization is available only to users having RMS-11K software. Unlike the physical ordering of records in a sequential file or the relative positioning of records in a relative file, the location of records in the indexed file organization is transparent to your program. The presence of keys in the records of the file governs the placement of records in an indexed file. A key is a character string present in every record of an indexed file. The location and length of this character string is identical in all records. When creating an indexed file, you decide which character string in the file's records is to be a key. By selecting such a character string, the contents (i.e., key value) of that string in any particular record written to the file can be used by a program to identify that record for subsequent retrieval. You must define at least one key for an indexed file. This mandatory key is the primary key of the file. Optionally, you can define up to 255 additional keys (i.e., alternate keys). Each alternate key represents an additional character string in records of the file. The key value in any one of these additional strings can also be used as a means of identifying the record for retrieval. As programs write records into an indexed file, the values contained in the primary and alternate keys are used to locate the record in the file. From the values in keys within records a tree-structured table known as an index is built. An index consists of a series of entries. Each entry contains a key value copied from a record that a program wrote-into the file. With each key value is a pointer to the location in the file of the record from which the value was copied. A separate 6-24 FILE HANDLING index is built and maintaine_d for each key you define for the file~ Each index is stored in the file. Thus, every indexed file contains at least one index, the primary key index. When you define alternate keys, an additional index is built and maintained for each alternate key. Figure 6-3 shows the general structure of an indexed file that has been defined with only a single key. Figure 6-4 depicts an indexed file defined with two keys, a primary key and one alternate key. KEY DEFINITION ABLE I I ··I i ELM AV 24379 i JONES : MAIN ST I . . . I 19724 I I I I SMITH HOLT RD : 35888 Figure 6-3 Single Key Indexed File Organization 6-25 KEY DEFINITIONS PRIMARY INDEX (Employee Name) ALTERNATE INDEX [fB2?J,~~~~~\ij,~~tt / t:EJ H ~ 11733 45591 °I ' IV °' ~ --------- --- -_,,,,.,,. --- __?.......\--~~-- --- - - - ~ 0 t-t z H G"l I~ ABLE 1I ELM AV I 24379 · · -~·---w------ 1 JONES I MAIN ST 19724 I SMITH I HOLT RD 11733 I I I I L--~~-..L.___.._ _..._~--- '- -~----~---~-~~-~~--DATA R E C O R D S - - - - - - - - - - - - - - - - - - - ' Figure 6-4 Multi-key Indexed File Organization FILE HANDLING 6.3.1 RECORD SIZE A relative file may contain either fixed-length or variable-length records. (Fixed-length records have one or more record descriptions that describe the same size record. Variable-length records have more than one record description that describe several different sized records.) For variable length records in an indexed file, the software adds a two byte count field. On a write operation the actual record is written out to the I/O device not the maximum length record. The length of this record is placed in the two byte count field. On a read operation this two byte count field is used to determine the length of the record to be read in. 6.3.2 RECORD CONTAINS Clause The RECORD CONTAINS clause, when specified without the "integer-1 TO" option, is for documentation purposes only. The compiler determines record size from the data descriptions. When ~ne "integer-1 TO" option is specified, it forces the compiler to generate a variable length record file, even if the data descriptions describe fixed length records. Conversely, if the data descriptions for a sequential file describe variable-length records, the software sets up variable sized records automatically and ignores this clause. Even though the software ignores the values in the "integer-1 TO ... " phrase, the clause may be used in any program to document record sizes. 6.3.3 SAME RECORD AREA Clause The SAME RECORD AREA clause is identical for all file organizations. See Section 6.1.3. 6.3.4 RECORD BLOCKING The size of a file is expressed as an integral number of virtual blocks. Virtual blocks are physical storage structures. That is, each virtual block within a file is a unit of data whose size depends on the physical medium on which the file resides. Indexed files may reside only on disk. The size of virtual blocks within files on disk devices is always 512 bytes. Indexed files, like relative files, use a logical storage structure known as a logical block or bucket. A bucket consists of 1 to 32 virtual blocks. The user may specify the number of virtual blocks contained within each bucket by using the BLOCK CONTAINS clause. This distinction should be made clear. A virtual block is a physical entity which is fixed in size and cannot be changed by the user. A bucket is a logical entity and its size is directly under user control. Records may span virtual block boundaries. They may never span bucket boundaries. 6-27 FILE HANDLING Increasing the bucket size increases the speed of processing of a file because fewer I/O operations are needed to access the smaller number of buckets in the file. On the other hand, a larger bucket size means that more memory space is taken up by the I/O buffers. There are three ways that the bucket size may be specified by the user in a COBOL program: by default, by using the construct BLOCK CONTAINS integer RECORDS, or by using the construct BLOCK CONTAINS integer CHARACTERS. The default is to make the bucket size as small as possible to min1m1ze the memory buffer space required. By using the BLOCK CONTAINS (integer RECORD or integer CHARACTERS) clause, you can increase the memory buffer space required. Increasing the buffer space allows faster I/O by decreasing the number of operations to process a file. The following paragraphs further define the three blocking methods: Default The default philosophy is to make the bucket size as small as possible to min1m1ze the memory buffer space required. The algorithms for calculating the bucket size follow: Bnum= ((22+Rlen)/512)+1 Fixed length record or Bnum= ((24+Rmax)/512)+1 Variable length record where: Bnum is the number of virtual blocks per bucket. Rlen is the fixed record length (in bytes). Rmax is the maximum record length (in bytes) if the record length is variable. The number 22 comes from a bucket overhead of 15 bytes and a fixed length record header of 7 bytes; 24 comes from a bucket overhead of 15 bytes and a variable length record header of 9 bytes. Table 6-6 gives the bucket size for record lengths. Table 6-6 Bucket Size for Record Lengths Bnum 1 2 3 4 5 6 7 8 ·9·· Rlen 1-490 490-1002 1003-1514 1515-2026 2027-2538 2539-3050 3051-3562 3563-4074 4075·-·4· 095 6-28 Rmax 1-488 489-1000 1001-1512 1513-2024 2025-2536 2537-3048 3049-3560 3561-4072 4073·-·4· 095 FILE HANDLING BLOCK CONTAINS Rnum RECORDS If the BLOCK CONTAINS num RECORDS clause is used, where num is an integer, then the following algorithms are used to calculate the bucket size. Bnum= ((15+(Rlen+7)*Rnum)/512)+1 Fixed length r.ecord or Bnum= ((15+(Rlen+9)*Rnum)/512)+1 Variable length record where: Bnum is the number of virtual blocks per bucket, ranging from 1 to 32. Rlen is the fixed record length (in bytes). Rmax is ~ne maximum record length (in bytes) if the record length is variable. Rnum is the number of records per bucket as given in the BLOCK CONTAINS clause. The number 15 is bucket overhead, 7 is the fixed length record header and 9 is the variable length record header. BLOCK CONTAINS Cnum CHARACTERS If the BLOCK CONTAINS Cnum CHARACTERS clause is used, where Cnum is an integer, then Cnum is subject to the following constraints. (1) Cnum Rlen+1 for fixed length records or Cnum Rmax+3 for variable length records (2) Cnum mod 512=0 Based on Cnum, the bucket size is calculated as follows: Bnum=Cnum/512 where: Cnum is the number of characters per bucket as given in the BLOCK CONTAINS clause. Rlen is the fixed record length (in bytes). Rmax is the maximum record length (in bytes) if the record length is variable. Bnum is the number of virtual blocks per bucket, ranging from 1 to 32. 6-29 FILE HANDLING Violation of constraint (1) causes a fatal error and the default method is used to calculate the bucket size. Constraint (2) means that Cnum should be a multiple of 512. If not, a warning error is given and Cnum is increased to the next even multiple of 512. The bucket size must be the same when the file is created and each time the file is accessed. Therefore, the BLOCK CONTAINS clause must never change for a particular file. Note: The previous discussion has used the following format: [ BLOCK CONTAINS integer If the following format is used: RECORDS }] { CHARACTERS RECORDS }] [BLOCK CONTAINS[integer-1 TO]integer-2 { CHARACTERS the compiler ignores integer-1, and integer-2 is used as the integer. L 6.3.5 BUFFERING When the system performs a sequential or random input operation, one or more index buckets are read into the buffer area until the bucket containing the specified record is located. The bucket containing the record is then read into the buffer area. Any subsequent sequential read operations will use the current index buffer to locate and read subsequent records in the current or other record buckets. When it has exhausted the current index buffer (has read all the records identified in the bucket), the system reads the next index bucket into the buffer area. When performing a sequential or random output operation, the system moves a record from the files current record area into the files buffer. Each subsequent write operation moves a record from the current record area into the buffer. The system writes the bucket to the medium when it has filled the buffer. Every output operation also causes the appropriate index bucket to be read into the buffer area, the indexes for each of the keys to be added to the appropriate buckets, and the buckets to be rewritten to the storage medium. 6.3.5. 1 Buffer Size - Buffer size depends on the size of the largest record in the file and on the blocking factor. For indexed files, buffer size must be some multiple of 256 words (512 bytes). 6.3.5.2 I/O Buffer Areas - The RESERVE clause in the Environment Division specifies the number of I/O buffer areas to be allocated for each file. Each I/O area represents the space for one bucket. A minimum of two is required for an Indexed file (this is the default). Three areas will increase the speed of random access. Four areas will increase the speed of random access if the file is being accessed on 6-30 FILE HANDLING two different keys. For each additional key, an additional area will increase the speed of access. Therefore, to speed up random access time, the optimum number of buffer areas is equal to the number of keys by which the file is being accessed plus two. Of course, each area means that more memory space is being taken up. 6.3.5.3 Buffer Space - To calculate the total amount of buffer space required for each Indexed file, the following algorithm may be used: Buffer Space = record size+((bucket size+20)*no. of areas) +(48*no. of keys in file)+((MAXKSIZ*2+MAXNKEY+3)/4*4) +272 where: MAXKSIZ is the maximum key size in the program. MAXNKEY is the maximum number of record keys for any file in the program. Note that in the division, the result is truncated to the next lowest integer. In addition to the above, there are 76 bytes of buffer space that are shared among all files and 44 times MAXNKEY bytes of buffer space that are shared among all indexed files. 6.3.5.4 Sharing Buffer Space Among Files - The SAME AREA clause provides a simple method of sharing buffer space among several files. This clause is identical for all file organizations and is described in Section 6. 1.6.4. 6.3.6 INDEXED I/O STATEMENTS The COBOL I/O statements, CLOSE, DELETE, OPEN, READ; WRITE, REWRITE, and START can refer to indexed files. A COBOL program may open an indexed file in one of three modes, INPUT, OUTPUT, or I-0, and access an open indexed file in one of three ways, sequentially, randomly, or dynamically. In INPUT mode, records may be read from the file; in OUTPUT mode, the file is· created and records may be written to the file; in I-0 mode, records may be read from the file, updated on the file, deleted from the file, or written to the file. The following table shows which statements and access methods apply to the three different OPEN modes of indexed files. 6-31 FILE HANDLING Table 6-7 Indexed OPEN Modes File Access Mode Sequential Random Dynamic Statement Input DELETE READ I x REWRITE START x WRITE DELETE READ x REWRITE START WRITE DELETE READ x READ NEXT x REWRITE START x WRITE O~en Mode Output I I-0 x x x x x x x x x x x x x x x x x NOTE The term, current record pointer, used in the following sections, refers to a location in the operating system used to store the record number of available record in a file. 6.3.6.1 Access Mode - The ACCESS MODE clause in the File-Control paragraph indicates which of the three access modes may be used on that file. When the ACCESS MODE clause specifies SEQUENTIAL, the I/O statements must refer to the records in the file sequentially, starting (after opening) with the first record and stepping through with each reference to the end of the file. When the ACCESS MODE clause specifies RANDOM, the I/O statements refer to the records in the file by the value of the key or keys. Usually the prime key is used unless a specific alternate key is designated. If an I/O statement refers to a record with a key, and that record does not exist, the INVALID KEY imparative statement may be executed depending on the particular I/O statement used. (The INVALID KEY imperative statement is explained with each of the indexed I/O statements in this section.) When the ACCESS MODE clause specifies DYNAMIC, the I/O statements may refer to the records in the file either sequentially or randomly. The OTS determines which access method to use from the OPEN mode (INPUT, OUTPUT, or I-0) and the form of the I/O statement. For example, if the statement READ ... INVALID KEY is to access ~a open input file dynam±cally, the OTS uses the designated key for random access. If the statement READ NEXT ... is to access an open input file dynamically, the OTS sequentially accesses the next existing record. 6-32 FILE HANDLING The following sections (6.3.6.2 through 6.3.6.8) on using the I/O statements themselves contain additional information about access modes. 6.3.6.2 Opening Indexed Fil~s - The OPEN statement for an indexed file makes an INPUT, OUTPUT, or I-0 mode file available so the COBOL program can access the records in the file sequentially, randomly, or ~ynamically. Consider the following example: Example The following sample OPEN statement opens the file named ARTICHOKE for input, and sets ARTICHOKE's current record pointer to the first record in the file. The program containing this statement could, after executing the statement, access ARTICHOKE with READ and START statements in the sequential access mode, READ statements in the random access mode, or READ, READ NEXT, and START statements in the dynamic access mode. OPEN INPUT ARTICHOKE. When the OTS executes an OPEN statement, it performs the following actions for the file named in the statement: · If the file is already open, the OTS generates an error message and performs the USE procedure section (if specified). (Section 6.8 discusses USE procedures and Section 12.3 discusses error messages.) · When opening an existing file, the attributes (i.e., record length, block size, etc.) of the file are used for accessing the file. Those specified in the program are ignored. Be sure that the. attributes specified in the COBOL program agree with the actual attributes of the file. · If a SAME AREA clause contains the name of the file and none of the other files named in the clause is open, the OTS allocates buffer space for the file. · When the file has passed all of the preceding checks and is ready for opening, the OTS instructs the Record Management Services to open the file. If the Record Management Services fails to open the file, the OTS reports an error condition and performs any applicable USE procedure (if present). · Finally, depending on which statements apply to the open mode, the OTS enables or disables all of the program's I/O statements that refer to the file (see Table 6-7). For example, if the OPEN mode is INPUT, it enables all READ and START statements for that file and disables all REWRITE, DELETE and WRITE statements for that file. The OPEN statement sets the current record pointer for the file to the first existing record in the file as established by the prime record key. If the file is being accessed randomly or dynamically, the program should maintain correct values in the prime and aternate key fields. 6-33 FILE HANDLING 6.3.6.3 Reading Indexed Files - When applied to a file being accessed sequentially, the READ statement makes the next logical record of an open file available to the program. The information made available is based on positioning by the OPEN, START, or last READ operation. When applied to a file being accessed randomly, the READ statement selects a specified record from an open file and makes it available to the program. The value of the specified key (prime key, if the no key is specified) identifies the record. When applied to a file being accessed dynamically, the READ statement has two formats so that it can either select the next logical record (sequentially) or select a specified record (randomly) and make it available to the program. The READ NEXT statement takes the number in the current pointer and finds the next present record. The following sample READ statement reads the file named ARTICHOKE sequentially and, when it exhausts the file, causes program control to transfer to the subroutine named FILEOUT: READ ARTICHOKE NEXT RECORD AT END GO TO FILEOUT. For more information concerning the mechanics of the READ NEXT statement see Section 6.3.6.6, Specifying the Next Record To Be Read. The READ with key takes the value in the specified key, moves it to the current record pointer, and reads the record being pointed to. The following READ (with key) statement reads the file named ARTICHOKE randomly, selecting records through the value in the file's primary key. If the designated key supplies a value that is not identified with a valid record, the statement causes program control to transfer to the subroutine named NO-REC. READ ARTICHOKE RECORD INVALID KEY GO TO NO-REC. Note: a random read repositions the current record pointer and thus effects further sequential reads. If the file has more than one record description, the records automatically share the same current record area. The OTS does not clear this area before it executes the READ statement (no blank filling, etc.). inerefore, it ~ne record read by the latest READ statement does not fill the entire current record area, the area not overlaid by the incoming record remains unchanged. For example, if the file's record area contains ten 3's, and a READ operation moves in a 6-character record containing all 1's, the current record area then contains six 1's followed by four 3's. Consider the following example: Current Record Area with all 3's I 33333333331 Next Record in the File Current Record Area after READ 11111111 I 11111133331 6.3.6.4 Rewriting Records into an Indexed File - The REWRITE statement releases a logical record to an output or input-output file. In all of the access modes, the record is positioned based on the 6-34 FILE HANDLING prime key, any alternate keys are also processed properly, including duplicate keys. If more space is required for new record positions, the Record Management Services automatically extends the file size, regardless of the access mode being employed. If the file is open in sequential access mode and the records are not written in ascending order of the prime key values, an INVALID KEY condition exists. In any access mode an attempt to write an existing record having the same prime key value or an alternate key value where duplicates are not allowed, results in an INVALID KEY condition. The following sample WRITE statement releases the record BREAKERS to the indexed file. If the record already exists, program control transfers to WRITE-ERR. WRITE BREAKERS INVALID KEY GO TO WRITE-ERR. The indexed WRITE statement creates only storage files because print-files are sequential files. 6.3.6.5 Deleting Records from an Indexed File - The DELETE statment logically removes an existing record from a file. After a DELETE statement has successfully removed a record from a file, that record can no longer be accessed. If the file is open in the sequential access mode, the statement removes the record just successfully read. For example, the following sample statement removes the record just read from the file named ARTICHOKE: DELETE ARTICHOKE RECORD. If the file is open in either the random or dynamic access mode, the statement removes the record from the record specified by the prime key. For example, the following sample statment deletes the record specified by the prime key from the file named ARTICHOKE. If the prime key supplies a value that does not contain a valid record, the statement transfers control to NO-REC. DELETE ARTICHOKE RECORD INVALID KEY GO TO NO-REC. 6.3.6.6 Specifying the Next Record to be READ - The START statement specifies which record will be the next record to be referenced sequentially in a file opened for INPUT or I-0 processing. The START statement updates the current record pointer for future sequential READs. Suppose we have the following START statement: START FILE-A KEY IS EQUAL TQ SUB-KEY-A. SUB-KEY-A must be alphanumeric. In addition, SUB-KEY-A must be a record key or alternate record key or subordinate to a record key or alternate record key whose leftmost character position corresponded to its own leftmost character position. For example, if the following fields were defined in the record: 6-35 FILE HANDLING 02 KEY-A. 03 SUB-KEY-A. 04 SUB-KEY-A1 PIC XXX. 04 SUB-KEY-A2 PIC XX. 03 SUB-KEY-B PIC XXX. and if KEY-A was a record key or alternate record key, then the following would be legal START statements: START FILE-A KEY IS EQUAL TO KEY-A. START FILE-A KEY IS EQUAL TO SUB-KEY-A. START FILE-A KEY IS EQUAL TO SUB-KEY-A 1. The following START statements are illegal. START FILE-A KEY IS EQUAL TO SUB-KEY-A2. START FILE-A KEY IS EQUAL TO SUB-KEY-B. The leftmost character positions of SUB-KEY-A2 and SUB-KEY-B do not correspond to the leftmost character position of KEY-A. The relational operator IS EQUAL TO (or IS =) means that the current record pointer is set to point to the record associated with the first key equal to SUB-KEY-A. If SUB-KEY-A is shorter than the record key or alternate record key, then the record keys or alternate record keys in the file are truncated on the right to the same length as SUB-KEY-A for the purposes of the comparison. If the following START statement is used: START FILE-A KEY IS GREATER THAN SUB-KEY-A. or START FILE-A KEY IS > SUB-KEY-A. then the current record pointer is set to point to the record associated with the first key that is greater than SUB-KEY-A. Thus, if the file had records with the following keys: Record # 743 629 ~15 KEY-A ABCDDZZX ABCDEABC ABCDEXYZ ABCDEZZZ ABCDGAAA ABCDGZZX and SUB-KEY-A contained ABCDE, then the current record pointer would be set to point to record number 233. If the following START statement is used: START FILE-A KEY IS NOT LESS THAN SUB-KEY-A. or START FILE-A KEY IS NOT < SUB-KEY-A. then the current record pointer is set to point to the record associated with the first key that is greater than or equal to SUB-KEY-A. In the previous example that would be record number 629. 6-36 FILE HANDLING If there is no record that satisfies the comparison, the invalid key exit is taken. In our example the following statement: START FILE-A KEY IS EQUAL TO SUB-KEY-A. would take the invalid key exit if SUB-KEY-A contained ABCDF. If the comparison is satisfied and the current record pointer is set, then subsequent READs would update the current record pointer using KEY-A as the key of reference. If the key phrase is not specified, then the default key is the prime record key and the default comparison is IS EQUAL TO. 6.3.6.7 Closing Indexed Files - The CLOSE statement terminates processing on the file referred to in the statement. The following sample CLOSE statement terminates processing on the file named ARTICHOKE: CLOSE ARTICHOKE. When the statement closes a file, no other I/0 operation can access that file until another OPEN statement opens the file. If the statement specifies the LOCK option, the program cannot open the file again in that run. If a SAME AREA clause contains the name of the file just closed, the program may open one of the other file~ named in the clause. 6.4 DEVICES The PDP-11 COBOL object time system supports any devices supported by the Record Management Se~vices. Table 6-8 contains a partial list of these devices: Table 6-8 Device Codes Device Device Code Card Reader CR Disk (RK03/RK05) DK Disk (RF 11IRS11 ) DF Disk (RS03/RS04) DS* Disk (RP11/RP02/RP03) DP Disk (RJP04) DB Line Printer LP Magnetic Tape (TU10/TS03) MT Magnetic Tape (TU16/TU45) MM *The DS device code does not apply to RSTS/E. 6-37 FILE HANDLING Some devices are better suited to certain uses than others. For example, since PDP-11 COBOL is a disk-oriented system, the disk provides COBOL files with the best performance and reliability. On the other hand, COBOL files on magnetic tape are limited to sequential organization. The following subsections discuss the devices that are available and how to use them to best advantage. 6.4.1 DISK The primary means for storage and processing of PDP-11 COBOL files is a disk. Several disk units are supported, including RK05, RF11, RP11/RP03, RP04 and RS04. Each device has its own file handling characteristics, and differs with respect to capacity, speed, and portability. The following table compares these characteristics. The values, low, mod (moderate), and high, describe the relative characteristics of the devices in the table. The efficiency characteristic commbines the values of capacity, speed, and portability for that unit into a single value. Table 6-9 Comparison of PDP-11 Disk Devices Device RK05 RF 11 RP11/RP03/RP04 CAPACITY LOW/MOD (4800 BLOCKS) LOW VERY HIGH I ( 1024 BLOCKS) I (80,0'0'0 BLOCKS) (RP04 160,000' BLOCKS) SPEED MOD HIGH HIGH PORTABILITY HIGH (EASY) NONE HIGH (BULKY) EFFICIENCY HIGH MOD HIGH RS04* I LOW (2048 BLOCKS) HIGH NONE MOD *RSTS/E supports the RS04 only as a swapping device. It cannot be used for user files. The characteristics of the devices in the table suggest suitable applications. Consider the Tnllnwin~ - - - - - ·· - '"''"'O P- Y...... ~- -m..-nr l- P- R- ~... · The portable, moderate capacity RK~5 is ideal for storage of COBOL source and object files as well as small data files; · The fast, low capacity RF11 is ideal for scratch files requiring either random or sequential access; · The high-capacity RP11/RP03/RP0'4 is excellent for large files requ1r1ng high volume access in either the random or sequential modes. Further, its portability makes it ideal for master file storage on multiple systems. 6-38 FILE HANDLING 6.4.2 MAGNETIC TAPE All PDP-11 operating systems support magnetic tape files; all COBOL operations concerned with magnetic tape are fully supported by the compiler, including the MULTIPLE-FILE TAPE clause and the CLOSE REEL [WITH NO REWIND] clause. (RSTS/E does not support multi-reel files.) 6.4.3 CARD READER AND~ PRINTER COBOL programs can use both the card reader and the line printer as I/O devices. If these devices have been assigned logical names in the Special-Names paragraph of the Environment Division, the ACCEPT and DISPLAY statements can access them. For example, consider the following coding: ENVIRONMENT DIVISION. SPECIAL-NAMES. CARD=READER IS CARDS LINE-PRINTER IS LOG. PROCEDURE DIVISION. ACCEPT INREC FROM CARDS. DISPLAY PRINTREC UPON LOG. Figure 6-5 Assigning Logical Names to the Card Reader and Line Printer If filenames have been assigned to these devices in the SELECT clause of the File-Control paragraph, the READ and WRITE statements can access them for I/O files. For example, consider the following coding: 6-39 FILE HANDLING FII~-CONTROL. SELECT INFILE ASSIGN TO "CR:". SELECT OUTFILE ASSIGN TO "LP:". FD OUTFILE DATA RECORD IS OUTREC. PROCEDURE DIVISION. READ INFILE. WRITE OUTREC. Figure 6-6 Assigning the Card Reader and Line Printer to Files 6.5 FILES AND FILENAMES The OTS and the operating system use the device codes described in Section 6.4 to communicate with the devices. Further, the COBOL OTS uses the operating system's file specification and interfaces for all file manipulation with file storage devices (disk and magtape). The VALUE OF ID clause (discussed in the following subsection) in the FD entry describes the file specification to the OTS. The format for the full file specification follows: dev:[uic] filename.typ;version/switches where: dev: - device code [uic] - user's identification code or the code of the user for whom the file was created - the user directory ID. (The brackets [ ] are required.) filename - an alphanumeric field containing up to nine characters that identifies the file (RSTS/E allows a length of from one to six characters). typ an alphanumeric field containing up to three characters that qualify the filename. version - a numeric field containing up to five octal digits that give the version number of the file. By specifying version numbers, the user can maintain several versions of the same file on a directory device. (Not available with RSTS/E.) switches - identifies certain actions for the operating system to perform for the file. (See Chapter 14, Optimization.) 6-40 FILE HANDLING These entries default as follows: dev: - the device code of the disk containing the operating system. [uic] - the user identification code of the user currently using the system. filename - null typ - null version the version number defaults differently for IAS and RSX-11M input and output files. · input files - the highest numbered version of the file (thus selecting the latest version); · output files one greater than that of the highest numbered version of the file (thus creating the latest version). switches - null For example, the following sample file specification causes the file system to process version 3 of a file on disk named ARIES. The user has an identification code of 140,222. DK:[140,222]ARIES;3 The following sample RSTS/E file specification causes the file system to process a file on disk named ARIES. The user has an identification code of 140,222. Note that RSTS/E does not support the version number feature. DK:[140,222]ARIES. 6.5.1 USING EXPLICIT FILENAMES (VALUE OF ID CLAUSE) The VALUE OF ID clause, in the FD entry, describes the file specification to the COBOL OTS. The VALUE OF ID clause is optional; however, the system requires it whenever the program refers to an explicit file unless a sufficient file description is provided in the ASSIGN clause. The clause accepts either a literal entry or an identifier entry. Consider the following sample literal form of the clause: VALUE OF ID IS "DK:[140,222]ARIES;3" Elements of the file specification appearing in the VALUE OF ID clause supersede their counterparts specified in the ASSIGN clause for the file. (Subsection 6.5.2 discusses the ASSIGN clause.) When written in the literal form, the literal may be a complete file specification or a part of a file specification. When written in the identifier form, the value of the identifier may be a complete or partial file specification. The identifier form of this clause is especially useful when different 6-41 FILE HANDLING runs of a program process different files. If a program must process different files in the same way on different runs, an ACCEPT statement in the Procedure Division can request a file specification from the user at the user's console or from a batch input stream. The following example illustrates how a COBOL program could request a file specification from an interactive terminal: DATA DIVISION. FD FILEIN VALUE OF ID IS INFILE. WORKING-STORAGE SECTION. 11 INFILE PIC X(20). PROCEDURE DIVISION. DISPLAY "TYPE IN INPUT FILE SPEC". ACCEPT INFILE. OPEN INPUT FILEIN. This sample coding causes the following interaction between the program and the user (the message printed by the program is underlined): TYPE IN INPUT FILE SPEC DK1:THOREAU RET Following this interaction, the sample OPEN statement will open (for inputj the file, THOREAU on DKi. 6-42 FILE HANDLING 6.5.2 DEVICE ASSIGNMENT BY ASSIGN CLAUSE If the VALUE OF ID clause does not specify a complete file specification, the ASSIGN clause in the File-Control paragraph can assign a defalt to those components not specified. The ASSIGN clause must be written as part of the SELECT statement as shown below: SELECT THOREAU ASSIGN TO "DK1:" This example assigns a default device code "DK1:" for the location of the file THOREAU. Another device code specification in the VALUE OF ID clause could override it later in the source program. 6.5.3 FILES AND LOGICAL UNITS Each file in an executable task must have a unique Logical Unit Number (LUN) assigned to it. The COBOL compiler can only generate a relative LUN assignment for each file in a COBOL program, because there may be multiple COBOL programs in a task. (See Figure 2-10 which contains a sample file=to=relative=LUN assignment table.) Actual LUN assignments are made by the COBOL Object Time System (OTS) at task execution time. The number of LUNs needed by a task is equal to 1+n, where n is the total number of individual files included in each program comprising the task. For example, if a task consists of three programs, each program requiring three files, then the number of LUNs required is 10. (The first LUN is reserved for ACCEPT/DISPLAY and message processing.) If more than six LUNs are required for an executable task, the UNITS option must be specified at task-build time, because the Task Builder default is 6. Each LUN must have a physical device associated with it before the associated file can be opened. You can assign a physical device to the file by specifying the VALUE OF ID or ASSIGN clause in your COBOL program, or you can specify the ASG option at task-build time. NOTE The default LUN assignments generated by the Task Builder do not always equate to the system device. (Refer to the Task Builder Manual for your particular operating system for more information concerning task builder options.) As previously stated, each COBOL program receives relative LUN assignments for its files by the compiler. At task-execution time, the OTS converts these relative LUN assignments to actual assignments according to the following rules: 1. If the task consists of only one COBOL program, the OTS adds 1 to each of the relative LUN assignments yielding the actual assignments. Therefore, a 'file rece1v1ng a relative LUN assignment of 2 by the compiler would receive an actual LUN assignment of 3 at execution time. 2. If the task consists of more than one COBOL program having files assigned to it, simply addini 1 to the relative LUN assignments would obviously yield duplicate actual LUN 6-43 FILE HANDLING assignments. The OTS, in the case of multiple program tasks, utilizes the relative assignment +1 formula for the first program in the task. For each subsequent program, it takes the highest actual LUN assignment for the previous program and adds 1 to it to arrive at the first LUN assignment. It then applies the +1 formula to this first LUN assignment to arrive at each subsequent assignment for the program. Consider the following example: Example A task consists of three programs (PROGA, PROGB, and PROGC). Each program has three files with relative LUN assignments of 1, 2, and 3. At execution time, assuming that the programs were presented to the Task Builder or Merge Utility in the order PROGA, PROGB, and PROGC, the OTS would assign actual LUNs as follows: Program LUN assignment 1 (reserved for ACCEPT/DISPLAY and message processing) PROGA I PROGB 2 1st. File 3 2nd. File 4 3rd. File 5 1st. File 6 2nd. File 7 3rd. File PROGC 8 1st. File 9 2nd. File 10 3rd. File 6-44 FILE HANDLING 6.6 COMMUNICATING WITH THE PROGRAM The ACCEPT and DISPLAY statements allow low-volume,- terminal-oriented interaction between a COBOL program and the user of the program. While these statements are primarily intended for use with keyboard devices, PDP-11 COBOL allows the ACCEPT statement to accept cards from a card reader. and the DISPLAY statement to display data on a line printer. The following two Sections (6.6.1 and 6.6.2) discuss these capabilities in greater-detail. 6.6. 1 USING THE ACCEPT STATEMENT The ACCEPT statement makes small amounts of data available to the specified data item. Consider the following example; it causes data to be transferred from the device identified by the mnemonic-name, OPERATOR, to the area represented by the identifier, COMM-AREA. ACCEPT COMM-AREA FROM OPERATOR. OPERATOR must be a mnemonic-name specified for a device in the Special-Names paragraph (in this example, possibly the console). The area represented by the identifier COMM-AREA receives the data requested without any editing. The ACCEPT statement causes the transfer of a stream of bytes from the device specified in the FROM phrase, if it is present (OPERATOR in the previous example). If the FROM phrase is not present, the data is transferred from the user's console. Enough bytes are transferred to fill the identifier's area. The size of COMM-AREA in this example dictates the number of bytes being transferred. If the device contains more data than there are bytes in COMM-AREA, the data is truncated. · If the length of the identifier exceeds 80 bytes, the OTS performs one or more additional transfers of data until it either fills the identifier or transfers less than 80 bytes. · If the length of the identifier is less than or equal to 80 bytes and the length of the data is less than the identifier on a teletype or cards, the OTS pads the identifier with blank characters. The ACCEPT statement has a second format that allows it to retrieve the current DAY, DATE, or TIME from the system, and store it in the specified identifier. (DAY, DATE, and TIME are reserved words that the user does not define. The user must define identifiers into which to accept the values of DAY, DATE, or TIME.} The following sample statements place the current date into the identifier, GREENWICH, and the day of the year into the identifier, DAY-OF-YEAR: ACCEPT GREENWICH FROM DATE. ACCEPT DAY-OF-YEAR FROM DAY. 6-45 FILE HANDLING If the date were February 3, 1979, GREENWICH would contain 790203 (YYMMDD), and DAY-OF-YEAR would contain 79034 (YYDDD). The systems provide the time as follows (HH is the hour; MM is the minutes; SS is the seconds; CC is the hundredths of a second): TIME -- HHMMSSCC If the time were 20 seconds after 5: 15 PM, the systems (which nave a 24-hour clock) would provide the numbers 17152000. (Since the PDP-11 clock has no hundredths of a second capability, the systems place zeroes in the last two positions.) The identifier receives the data according to the rules for the MOVE statement. Chapters 3 and 4 discuss the MOVE statement as applied to non-numeric fields (Chapter 3) and numeric fields (Chapter 4). 6.6.2 ~ l1iE. DISPLAY STATEMENT The DISPLAY statement transfers small amounts of data from he specified data item or literal to the specified device. Consider the following example; it causes the transfer of data from the area represented by the identifier, COMM-AREA, to the device with the mnemonic-name, OPERATOR: DISPLAY COMM-AREA UPON OPERATOR. OPERATOR must be a mnemonic-name specified for a device in the Special-Names paragraph (possibly the console in this example). The area represented by the identifier, COMM-AREA, contains the data being transferred. The DISPLAY statement causes the transfer of a stream of bytes to the device specified in the UPON phrase if it is present (OPERATOR in the preceding example). If the UPON phrase is not present, the OTS transfers the data to the user's console. All of the bytes in all of the identifiers or literals in the DISPLAY statement are transferred first. The size of COMM-AREA, in this example, dictates the number of bytes being transferred. The system does not convert COMP items from binary to ASCII; it simply transfers them as they exist in storage. If a single DISPLAY statement must transfer large amounts of data, that data must contain appropriate vertical and horizontal form control characters. If the data being transferred does not contain form control characters and the length of the data stream exceeds the device's single line capacity, the excess characters will all print in the last position (overprinting each other). Table 6-10 contains several of the terminal form control characters: 6-46 FILE HANDLING Table 6-10 Form Control Characters Octal Code Control Character Function 007 BEL (CTRL G) Bell ringer 011 HT (CTRL I) Horizontal tab 012 LF (CTRL J) Line feed or line space (new line) 013 VT (CTRL K) Vertical tab 014 FF (CTRL L) Form feed to head of form 015 CR (CTRL M) Carriage return When it has transferred all of the data from all of the items listed in the statement, a carriage return and linefeed character are automatically appended onto the data. The WITH NO ADVANCING phrase suppresses this appending operation. NOTE The WITH NO ADVANCING phrase is an extension to the ANS-74 standard. 6.7 FILE COMPATIBILITY WITH OTHER PROGRAMMING LANGUAGES All files generated by other programming languages are compatible with COBOL provided that they were generated using Record Management Services. Files generated by other file systems must conform to Record Management Services formats. 6.7. 1 WRITING FILES FOR OTHER PROGRAMMING LANGUAGES PDP-11 COBOL writes files that can be read only by languages using the Record Management Services system interface for user program I/O. When creating a file that is to be read by a language, that does not use the Record Management Services interface (i.e., BASIC-PLUS), adhere to the following restrictions: · Ensure that the file has sequential file organization. · Ensure that the file is not a COBOL print-file (no LINAGE or APPLY PRINT-CONTROL clauses are applicable to the file). Printer control is handled differently by each PDP-11 programming language. · Do not use the ADVANCING option in WRITE statements when creating the file. The file may contain fixed-length or variable-length records, and the records should only contain only printable ASCII character data. 6-47 FILE HANDLING 6.7.2 READING -F-IL-E-S- WRITTEN -IN- -O-TH-E-R- PROGRAMMING LANGUAGES PDP-11 COBOL reads files that were written only by languages using the Record Management Services system interface for user program I/O. Before reading a file that was written by another language that does not use the Record Management Services interface, be certain that the file meets the following restrictions: · Ensure that the file is an ASCII file. · Ensure that the file does not have a carriage control attribute (the FORTRAN carriage control file attribute must not be set). FORTRAN meets these restrictions when it writes ASCII (not binary) data with formatted WRITE statements. However, the user must disable the carriage control attributes in the OPEN statement for the file. CALL OPEN (UNIT=n, CARRIAGE CONTROL="NONE" WRITE (n,100) list FORMAT( ..... ) BASIC+2 is capable of reading and writing all Record Management Services files. Therefore, files written by BASIC+2 programs are compatible with COBOL. BASIC-PLUS meets all of these restrictions when it writes a formatted ASCII (sometimes called sequential) file as described in the BASIC-PLUS Language Manual. PDP-11 COBOL cannot read BASIC-PLUS Virtual Array files. 6.7.3 DATA FILE TRANSPORTABILITY The user who wishes to transport data files from one language processor to another or from one system to another (RSX-11M to RSTS/E or vice versa) should be careful to write such files using the Record Management Services. Record Management Services is the only file interface used by PDP-11 COBOL. Non-printable ASCII characters are subject to misinterpretation by the different language processors and operating system utilities. If, for example, COBOL were to write records which contained COMPUTATIONAL (binary) data items, the values these items could contain would be written in the file in the same binary format as represented in the cornputere Such binary values may look like non=printable ASCII characters such as CR, LF, CTRL/Z, escape, which could cause system utilities to perform in an unpredictable manner while processing the records. Other ways that non-printable ASCII characters can get into a file are: 1. having data definitions that contain the USAGE IS INDEX clause; 2. moving HIGH-VALUES or LOW-VALUES; 6-48 FILE HANDLING 3. moving any redefinition of a COMP or USAGE IS INDEX field; 4. reading a data file that contains non-printable ASCII characters; 5. having multiple record definitions of varying sizes and filling a shorter record area then writing a longer one. (The excess characters, not filled, may be non-printing.) This list is not complete. There are many other ways for non-printing ASCII characters to find their ways into printable ASCII files. 6.8 PROCESSING I/O ERRORS - USE STATEMENT The USE statement provides COBOL programs with a way to process I/O errors. It allows the program to specify possible recovery steps following the I/O handling procedures performed by the software. When a COBOL program contains a USE procedure and an I/O error occurs, the OTS and Record Management Services execute their standard I/O error handling procedures and then transfer control to the procedure following the USE statement. (For further information concerning run-time I/O errors, see section 12.3.) Consider the following sample coding. When either THOREAU or ARTICHOKE causes an I/O error, the OTS executes its standard I/O error procedures and then transfers control to the paragraph (or paragraphs) that follow the USE statement. PROCEDURE DIVISION. DECLARATIVES. REPAIR SECTION. USE AFTER STANDARD ERROR PROCEDURE ON THOREAU ARTICHOKE. DISPLAY-ERROR. IF ... The paragraphs following the USE statement may contain any valid COBOL statement, except for the following: 1. Those statements that refer to a procedure outside of the DECLARATIVES. (Any attempt to transfer control out of the DECLARATIVES causes the OTS to abort the program.) 2. Those statements that would cause the USE procedure being executed to be invoked again. (Recursive USE procedures cause the ors to abort the program.) USE procedures are executed in the same manner PERFORM ranges in Procedure Division coding. Therefore, paragraphs with the USE procedure section should follow all rules specified for paragraphs within PERFORM ranges. For further information on PERFORM ranges, see Use of the PERFORM Statement in Chapter 7 of this guide.) If a status key is declared for the file in error, all status information is made available for processing in the USE procedure. 6-49 FILE HANDLING 6-50 CHAPTER 7 GOOD PROGRAMMING PRACTICES 7.1 FORMATTING THE SOURCE PROGRAM Since most COBOL programs are usually long, the programmer needs techniques that will help him to simplify and improve the readability of his COBOL programs. The guidelines in this chapter, if followed, will help produce source programs that are easy to read and maintain. Before considering these guidelines, consider the reference formats that are available with PDP-11 COBOL: 1. the Conventional (ANS) format, and 2. the Terminal format. Although the Conventional format produces ANS compatible programs, it also produces source printouts that are somewhat more cluttered than those produced by the Terminal format. These guidelines, therefore, recommend the use of Terminal format and all of the following suggestions and examples assume the use of that format. Besides the obvious advantage of an uncluttered printout, the Terminal format has other programming advantages: 1. it requires less storage area; 2. it requires no line numbers; 3. its statements may be aligned with tab characters. Further, whenever required, the REFORMAT utility program will convert Terminal format programs to the Conventional format. (The REFORMAT utility program is discussed in Chapter 11). The following suggestions should help to further simplify even the most complicated source programs. 1. Begin division, section, and paragraph names in column 1. Although these names may start anywhere in Area A, aligning them in column 1 produces a much more readable listing. When required, place the * and - in column 1. (Column 1 then becomes column 0.) 2. Insert a blank line, o~ one or more comment lines (describing the purpose of the file) before each SELECT statement in the FILE-CONTROL paragraph. Place the phrases of the SELECT statement on separate lines and begin each of them in column 5 (use the tab character to skip over Area A). Consider the following illustration of a typical SELECT statement: 7-1 GOOD PROGRAMMING PRACTICES AREA A AREA B 1. . . 5····. ·· SELECT MASTER-FILE ASSIGN TO "DKl:" ORGANIZATION IS RELATIVE ACCESS IS SEQUENTIAL. 3. Place the phrases of the file description statement on separate lines and begin each of them in column 5. {Use the tab to skip over Area A.} Consider the following illustration of a typical file description entry: AREA A AREA B 1 . 5 · · · · · · . FD MASTER-FILE LABEL RECORDS ARE STANDARD VALUE OF ID IS MASTER-FILE-NAME DATA RECORD IS MASTER-RECORD. 4. In both the File and working-Storage sections, begin all 01 level items in column 1. Indent, by four columns, all subordinate items with higher-valued level numbers. {For example, if the item that is subordinate to a 01-level record description is 05, begin the record description level number in column 1 and the 05 level number in column 5.) Use the tab character for the first indentation, a tab and four spaces for the second, two tabs for the third, etc. When indented in this manner, the listing will show, clearly and neatly, the hierarchical relationships of all of the data names in the program as well as their level number values. Increment level numbers by 5; then later, if it becomes necessary to insert additional group items, they may be inserted without having to change the level numbers of all items that are subordinate to that group. If desired, write the level numbers as single digits (such as 1 instead of 01). Use level number 01 instead of 77 in the Working-Storage Section. (77, as a level number has the same meaning as 01, and 77 may eventually be omitted from the COBOL standard.} Since all elementary items, except for index data items, require PICTURE clauses, these clauses fill a good part of the source program listing. However, the PICTURE clause itself may be simplified to enhance the listing's readability as follows: a. use PIC as an abbreviation for PICTURE, b. omit the noiseword IS, and c. align the PIC clauses on successive lines. {Use the tab character to align the clauses.} 5. Put all paragraph name declarations in the Procedure Division on lines separate from the statements in the paragraph. This not only makes the program more readable, it also makes modification of the first statement in the paragraph easier. 7-2 GOOD PROGRAMMING PRACTICES 6. Follow all imperative statements with a period, making them 1-statement sentences. Place only one statement on a line. In addition to making the lines shorter and more readable, this will prove quite helpful when debugging the program. For example, if the program contains a coding error, it will be on one line and therefore easier to modify without affecting the other portions of the sentence; further, the diagnostic messages will refer to the correct line and their meanings will be clearer. Since left-aligned statements in any program enhance the readability of that program, develop the habit of starting all COBOL sentences in column 5. (Use the tab character to skip over Area A.) Some statements, however, should be further indented, as explained in the following paragraphs. 7. If the true path of a conditional statement contains another conditional statement or more than one imperative statement, place all statements in the true path on lines immediately following the conditional statement and indent them to show their dependence upon that statement. Consider the following illustration of an IF statement and its true path: IF COMPUTED-TAX SUBTRACT TAX-LIMIT FROM COMPUTED-TAX GIVING EXCESS-TAX MOVE TAX-LIMIT TO COMPUTED-TAX ADD EXCESS-TAX TO TOTAL-EXCESS-TAX. If the statement has an ELSE (or false) path, align the word ELSE under the preceding IF and indent all statements that are dependent on the ELSE statement. Thus: IF condition true path statement true path statement ELSE false path statement false path statement. Be sure to place the period after the last statement only! Another good method for simplifying conditionals is to write only a single imperative statement in the true or false path. If the path requires more statements, place them in a separate paragraph and either PERFORM the paragraph from the path or GO to it. This technique avoids the possibility of inadvertently placing a period at the end of a statement within the path, thereby terminating it prematurely. When writing a GO TO ... DEPENDING statement, place each procedure name on a separate line and indent them all. Consider the readability of the following sample statement: GO TO P35 P40 P45 P60 P65 DEPENDING ON P-SWITCH. 7-3 GOOD PROGRAMMING PRACTICES 8. When grouping statements into paragraphs and sections, use the following organizational ideas: Group together logical units of processing into a section. Select a section name that reflects the type of processing being conducted within that section {such as TAX-COMPUTATION SECTION, PRINT-LINE-FORMATTER SECTION, etc.). Follow the section name with sufficient comment lines to explain the processing that is carried out by the statements within that section. Make paragraph names as short and simple as possible. A numbered abbreviation of the section name often suffices. Thus the paragraph names in the TAX-COMPUTATION section might be TClO, TC20, TC30, etc. Use paragraph names sparingly, placing them only where the true and false paths of conditional statements require branch points for GO TO statements. If the temptation arises to give a paragraph a longer name in an attempt to reflect the type of processing in that paragraph, use comment lines instead. {Comment lines usually convey more information, more clearly.) When using simple numbered paragraph names, assign increasing numeric characters to sequential paragraphs. If the numeric portion of the names increases by 5 or 10, new ones may be inserted later without disturbing the sequence of the names. Do not use the PERFORM verb in the form, PERFORM a THRU b. If the paragraphs a thru b must be performed, place them in a section by themselves and PERFORM the section, thus avoiding the use of the THRU option. Place single paragraphs that are to be performed into sections and use the section name as the object of PERFORM verbs. Then, if future design changes introduce complicated conditional logic into the paragraph, requiring additional paragraph names, the PERFORM statements need not be altered. The preceding guidelines divide the Procedure Division into modular blocks of coding. If these guidelines are used, the following additional techniques may be applied. a. Restrict entry to all sections through the first statement of the section by use of a GO TO, a PERFORM, or a "fall through" from the preceding section: b. Ensure that all GO TO statements refer to only section names or paragraph names that are internal to the section containing the GO TO statement. 7.2 USE OF PUNCTUATION Avoid using the COBOL punctuation characters, comma and semicolon. They lend little to the readability of programs that have their statements neatly aligned, as discussed earlier in this chapter. Further, it is quite easy to misuse these characters, which can cause serious errors for many compilers. {Other compilers either ignore incorrect punctuation characters or flag them with warning messages.) At best, even when used correctly and in the proper places, they have no effect on the meaning of the program. 7-4 GOOD PROGRAMMING PRACTICES 7.3 USE OF THE ALTER STATEMENT Avoid using the ALTER statement to change the flow of control in a program. It is impossible to test the setting of an alterable GO statement except by executing it. Also, unless explicit comments accompany an alterable GO statement, it is difficult to tell whether or not it is referenced by ALTER statements or what the possible destinations might be. All of this makes debugging programs that contain these statements quite difficult. There are two other techniques that may be used in their place: 1. If control branches one of two ways (i.e., a binary switch), write the switch as a conditional variable. Consider the following sample coding: 01 P-SWITCH PIC S9 COMP VALUE 0. 88 NO-PRINT VALUE 1. MOVE 1 TO P-SWITCH IF NO-PRINT GO TO P40. P40. MOVE 0 TO P-SWITCH. 2. If control branches more than two ways, use MOVE statements to place integers into a data item, and a GO TO ... DEPENDING ... statement to test the data item and branch accordingly. Consider the following sample coding: 01 P-SWITCH PIC 89999 COMP VALUE O= MOVE 1 TO P-SWITCH MOVE 3 TO P-SWITCH. GO TO PART-TIME PIECE-WORK HOURLY SALARIED-WEEKLY SALARIED-OTHER DEPENDING ON P-SWITCH. * FALL THROUGH IS A BUG DISPLAY "?17". STOP RUN. 7.4 USE OF THE PERFORM STATEMENT The general rules for the PERFORM statement are augmented with the following rules: 7-5 GOOD PROGRAMMING PRACTICES 1. The endpoint of a section and the endpoint of the last paragraph in the same section are two distinct points. This means that it is possible to execute a PERFORM of the section, then while that PERFORM is still active, to execute a PERFORM of the last paragraph. 2. On the start of a PERFORM, if the end point of the new PERFORM is the end point of an already active PERFORM, the OTS aborts the task and issues an error message. 3. At the end of any procedure, a check is made to see if the procedure being ended is the end of the most recent PERFORM range. If so, the most recent PERFORM range is exited. If not, the end point of the most recent procedu~e is checked against the end point of all currently active PERFORMs. If the end point of the procedure is the end point of any currently active PERFORM range, the OTS issues an error message and aborts the task because the perform ranges are not being exited in the reverse of the order in which they were entered. NOTE The OTS error messages are discussed in Section 12.4, Run-time Error Messages. 7.5 USE OF LEVEL 88 CONDITION-NAMES Condition-names provide a convenient method for testing a value or range of values in a field. The use of condition-names makes programs easier to maintain, because it ensures a uniform method of testing fields and helps to reduce recoding when the specifications of the program change. The following example illustrates the use of condition-names and shows the advantages inherent in their use. Suppose the records of a file each describe a student in an educational institution (or an employee in a corporation}. Some of the records contain categories of information which are not present in other records. A "code" field, which contains a digit or letter, indicates the presence (or type) of some categories; while a special value in the information itself (such as a numeric value being zero, negative, or maximum) indicates the presence of other categories. The processing of such a record may vary considerably depending on these indicator fields. The fields may require interrogation at various points in the program; and the interrogation may require more than a simple relation test. Consider a "code" field that holds one of seven values, coded as a mnemonic character. For example, S,1,2,3,4,G,P might be seven values that indicate student categor1es of Special, 1st year, 2nd year, 3rd year, 4th year, Graduate, and Postgraduate. The field is described as follows: 05 STUDENT-CATEGORY PIC X. 7=6 GOOD PROGRAMMING PRACTICES Program logic requires certain processing for enrolled undergraduates, different processing for special students, and still different processing for all students except enrolled undergraduates. Without the aid of condition-names, statements might be written as follows to resolve this problem: IF STUDENT-CATEGORY= "S" ... IF STUDENT-CATEGORY NOT LESS THAN "l" IF STUDENT-CATEGORY NOT GREATER THAN "4" IF STUDENT-CATEGORY EQUAL TO "G" NEXT SENTENCE ELSE IF STUDENT-CATEGORY EQUAL TO "P" NEXT SENTENCE ELSE GO TO ... However, if various level 88 entries follow the STUDENT-CATEGORY description, as shown below, condition-names can simplify this coding. 05 STUDENT-CATEGORY PIC X. 88 UNDERGRADUATE VALUE "l" THRU "4". 88 SPECIAL-STUDENT VALUE "S". 88 GRAD-STUDENT VALUE "G" "P". 88 SENIOR VALUE "4". 88 NON-DEGREE-STUDENT VALUE ~s~ ~P~. Now, the following procedural statements can solve the problem: IF SPECIAL-STUDENT .. . IF UNDERGRADUATE .. . IF GRAD-STUDENT .. . Procedural statements with condition-names are much easier to read and debug than those containing the complete test. For example, the procedural statements, IF UNDERGRADUATE ... , and IF STUDENT-CATEGORY NOT LESS THAN "l" IF STUDENT-CATEGORY NOT GREATER THAN "4" both accomplish the same thing, but the first statement is simpler and less confusing. In addition, the statement, IF NOT UNDERGRADUATE can test the category of not being an undergraduate, which is equivalent to any one of the following statements: IF NOT (STUDENT-CATEGORY NOT < "l" AND STUDENT-CATEGORY NOT > "4") or IF STUDENT-CATEGORY < "l" OR STUDENT-CATEGORY > "4" or IF STUDENT-CATEGORY < "l" NEXT SENTENCE ELSE IF STUDENT-CATEGORY > "4" NEXT SENTENCE ELSE GO TO ... Statements such as these are tedious to write and a frequent source of coding errors. Further, if a change creates a new student category, the recoding takes more time and is even more error prone. A careful and controlled use of condition-names forces a higher degree of programming control and checkout. If the program logic does require the modification of the STUDENT-CATEGORY field, it can even be named FILLER thus removing the opportunity to shortcut the use of condition-names. 7-7 GOOD PROGRAMMING PRACTICES To apply condition-names, follow the description of the item to be tested with a level 88 entry. The item being tested, known as the conditional variable (STUDENT-CATEGORY in the preceding illustrations), may be either DISPLAY or COMPUTATIONAL usage, but not INDEX usage; it may also be a group item. The compiler stores all of the values supplied by the level 88 entries in the object program exactly as written. (They are pooled with all of the literals from the Procedure Division.) A value supplied by a level 88 entry for a conditional variable of COMPUTATIONAL usage is stored in binary format to save conversion at object time. The compiler stores all other values as byte strings with the proper attributes. It does not make the level 88 entries equal to their conditional-variables in size. This means that it neither truncates nor pads (with spaces) non-numeric literals. Further, it neither truncates nor pads (with zeros) numeric literals, but stores them as written or, if converted to binary, in the minimum size COMP item that will hold the converted value. It stores signs as trailing overpunches on numeric DISPLAY literals, and removes and remembers decimal points. Do not enter level 88 items under group items that have subordinate entries containing any of the following clauses: SYNCHRONIZED, JUSTIFIED, COMPUTATIONAL, INDEX. 7.6 USE OF QUALIFIED REFERENCES 7.6.1 Qualified Data References The COBOL language provides facilities to define and reference user-defined data items. Data items are programmer-defined variables declared in the Data Division of a COBOL program. Such variables include, among others, file record descriptions and internal working areas. These data items are processed by procedural statements such as the WRITE, MOVE, and ADD statements. Procedural operations on these data are facilitated through references to the data items by name. For example, to update a variable, YTD-GROSS-PAY, by a weekly gross pay amount WEEKLY-GROSS, write the program fragment shown in Figure 7-1. WORKING-STORAGE SECTION. 01 YTD-GROSS-PAY PIC 9(5)V99. 01 WEEKLY-GROSS PIC 999V99. ADD WEEKLY-GROSS TO YTD-GROSS-PAY. Figure 7-1 Unqualified Data Item Reference In this example, YTD=GROSS-PAY and WEEKLY-GROSS are defined in the working Storage Section of the Data Division as COBOL variables with a level number of 01. The variable representing the "year-to-date gross 7-8 GOOD PROGRAMMING PRACTICES pay (YTD-GROSS-PAY)" is computed by incrementing its present value by the "weekly gross pay (WEEKLY-GROSS)" amount through reference to the appropriate data items in the ADD statement. References are made to the data items by the singular, unqualified names of YTD-GROSS-PAY and WEEKLY-GROSS. Since YTD-GROSS-PAY and WEEKLY-GROSS are defined with level numbers of 01 in the working Storage Section, these variables must be unique in their spelling and, hence, can only be referenced by the spelling of each data item's name without any COBOL qualification. The example in Figure 7-1 is artificial because the data item representing the "year-to-date gross pay" is defined as a level 1 variable in the Working Storage Section. More realistically, YTD-GROSS-PAY is defined as a field within an employee payroll record residing on an external master payroll file. The process of updating the "year-to-date gross pay" by a "weekly gross pay" amount is shown more appropriately in Figure 7-2. FILE SECTION. FD MASTER-IN LABEL RECORD IS STANDARD VALUE OF ID IS "MASTER.PAY". 01 PAY-RECORD. 03 NAME PIC X(30). 03 EMPLOYEE-NO PIC9(9). 03 YTD-GROSS-PAY PIC 9(5)V99. FD MASTER-OUT LABEL RECORD IS STANDARD VALUE OF ID IS 11 MASTER.PAY 11 · 01 PAY-RECORD. 03 NAME PIC x (30) · 03 EMPLOYEE-NO PIC 9 (9) . 03 YTD-GROSS-PAY PIC 9(5)V99. WORKING-STORAGE SECTION. 01 WEEKLY-GROSS PIC 999V99. PROCEDURE DIVISION. !NIT. OPEN INPUT MASTER-IN. OPEN OUTPUT MASTER-OUT. ADD WEEKLY-GROSS, YTD-GROSS-PAY OF MASTER-IN GIVING YTD-GROSS-PAY OF MASTER-OUT. Figure 7-2 Qualified Data Item Reference 7-9 GOOD PROGRAMMING PRACTICES In this example, YTD-GROSS-PAY is defined as a field in both the input and output record descriptions. There are two separate data items whose spellings are identical. To reference each data item, it is necessary to qualify the name of each data item with sufficient information to constitute a unique reference. Thus, to reference the "year-to-date gross pay" amount in the output record, we write "YTD-GROSS-PAY OF MASTER-OUT" where such a reference is called a qualified reference. The filename MASTER-OUT is functioning as a qualifier in the reference. The reserved word "OF" is the qualification connector and may be used interchangeabely with the reserved word "IN" in this context. Another way of referencing the same data item is to write "YTD-GROSS-PAY OF PAY-RECORD IN MASTER-OUT". This reference is called a completely qualified reference because all possible qualifiers are specified in the reference. A reference of the form "YTD-GROSS-PAY" or "YTD-GROSS-PAY OF PAY-RECORD" is illegal since it does not uniquely identify which of the two data items is desired. Such a reference is termed an ambiguous reference. In the area of data item definition and referencing, COBOL is unlike other languages such as FORTRAN and ALGOL 60. While FORTRAN requires each data item to have a unique name (i.e., no two data items may have a name of identical spelling) , COBOL relaxes this requirement to the extent that each data item must be uniquely referable. That is, two or more data items may have their names spelled identically, but there must exist a way to reference each distinct data item. Thus, there is a distinction between a data item and its name. Central to understanding this distinction is understanding the concept of unique referability. The functionalities of data item definition and referencing may be understood by stating three guidelines which relate the concepts of data item definition, reference format, and unique referability. 7.6.2 Guideline 1 (Data Item Definition) Each data item has a name. Each name is immediately preceded by an associated positive integer called its level number. A name either refers to an elementary item or else it is the name of a group of one or more items whose names follow. In the latter case, each item in the group must have the same level number, which must be greater than the level number of the group item. 7.6.3 Guideline 2 {Reference Format) Data-name qualification is performed by following a data-name or condition-name by one or more phrases of a qualifier preceded by IN or OF. IN and OF are logically equivalent. The general format of a qualified reference to an elementary item or group of items named "name-0" is given in Figure 7-3. name-0 OF name-1 . . . 0F name-m Figure 7-3 General Format of a Qualified Data Reference 7-10 GOOD PROGRAMMING PRACTICES where m >= 0 and where, for 0 <= j < m, name-j is the name of some item contained directly or indirectly within a group item named "name-j+l". A reference of the form given in Figure 7-3 is called a (partially) qualified reference with name-l,name-2, ... ,name-m being called qualifiers. Such a reference is termed a completely qualified reference if "name-j+l" is the father of name-j for 0 <= j <= m-1. In the hierarchy of qualification, names associated with an FD indicator are the most significant, then the names associated with level-number 01, then names associated with level-number 02, ... ,49. The most significant name in the hierarchy must be unique and cannot be qualified. Subscripted or indexed data-names, unsubscripted data-names, and condition variables may be made unique by qualification. The name of a condition variable can be used as a qualifier for any of its condition-names. Enough qualification must be mentioned to make the reference unique; however, it may not be necessary to mention all levels of the hierarchy as the example in Figure 7-2 demonstrates. 7.6.4 Guideline 3 (Unique Referability) If more than one data item is defined with the same name "name-0", there must be a way to refer to each use of the name by using qualification. That is, each definition of "name-0" must be uniquely referable. A data item is uniquely referable if the complete set of qualifiers for the data item are not identical to any partial (including complete) set of qualifiers for another data item. 7.6.5 Qualified Procedure References The facility of qualification may be applied to procedure references. A procedure name is either a paragraph or section name. By definition, a paragraph name is unique only within a section containing the paragraph while, on the other hand, section names must be unique within a COBOL program. The general format of a qualified procedure reference is shown in Figure 7-4. paragraph-name OF section-name Figure 7-4 General Format of a Qualified Procedure Reference A paragraph name may be qualified by its containing section name; a section name may never be qualified in a procedure reference. When a paragraph name is referenced without an explicit section name qualifier, the paragraph name is implicitly qualified by the appropriate section name. If a paragraph name is unique within a COBOL program it is not necessary to qualify the paragraph name in the procedure reference. Finally, if a paragraph name is not unique within a COBOL program, the paragraph name must be qualified in a procedure reference when the reference is made outside of the section which contains the paragraph. 7-11 GOOD PROGRAMMING PRACTICES 7.6.6 Qualification and Compiler Performance Qualification is a powerful language facility for the development of COBOL programs. used wisely, it increases the readability of COBOL programs. However, the user pays a price for utilization of this facility in terms of a slower compilation rate (i.e., COBOL source lines per unit of time). Qualification requires a tree-structured symbol table at compile-time. The time .required for building and looking up on a tree-structured svmbol table is considerably longer than for a non-tree-structured symbol table. This translates into a general degradation of compiler performance. If qualification is not employed in a program compiled by the PDP-11 COBOL compiler, compilation speed is not affected. However, when qualification is used, the compilation rate slows down due to the additional system overhead. In general, if there are deeper levels of qualification, there will be a slower compilation. This is especially so at the end of the Data Division text where duplicate data-name declarations are detected by the compiler. Object-time performance is not affected by usage of the qualification facility. 7-12 CHAPTER 8 REFORMAT UTILITY PROGRAM PDP-11 COBOL accepts source programs that were coded using either the conventional si-column card reference format or the shorter, terminal-oriented PDP-11 terminal format. The REFORMAT utility program reads source programs that were coded in the terminal format and converts them to si-column conventional format source programs. The PDP-11 COBOL Language Reference Manual discusses both formats in detail. Consider the two formats: · The terminal format is designed for ease of use with text editors controlled from an on-line console keyboard and is compatible for use with the PDP-11 system. It eliminates the line-number and identification fields and allows horizontal tab characters and short lines. · The conventional format produces source programs that are compatible with the reference format of other COBOL compilers throughout the industry. REFORMAT lets you write source programs in the terminal format; then, if compatibility is ever required for any of those programs, it provides a simple method for conversion to the conventional format. REFORMAT follows the following steps to expand each line of terminal format coding to the conventional format: · It generates a 6-character line number of iiii1i, places that number in the first six character positions of the line, and increases it by iiii1i for each subsequent line. · It places any continuation or comment symbols {-,*, or/) into character position 7. · It places the coding from the terminal format line into character positions 8-72, thereby creating a line of conventional format coding. · It replaces any horizontal tabs with the appropriate number of space characters to simulate tab stops at character positions 5,13,21,29,37,45,53,61, and 66 of the terminal format line. · It moves spaces into any character positions left between the last character of coding and character position 73; 8-1 REFORMAT UTILITY PROGRAM · It places either identification characters (if they were supplied at program initialization) or spaces into character positions 73-81!; · It right justifies (at position 72) the first line of a continued non-numeric literal, thus guaranteeing that the literal will remain the same length as it was in the default format; e Ti- rinh+- ..;11c+-if:ioeo ..&.'- .... ..L."°='.L.&.'- J'--'...,'-..L..a....L.'-~ l":>i- .... '"".,.;+-;,..,.,.... 7')\ \\..4.\- l:"''-'0..L\....LVl.l 1'6./ +-h,... \...J..1~ first COBOL word that is split over two lines; of any · It creates a line containing a slash (/) in position 7 and space characters in positions 8 through 72 for every form-feed character that it encounters. REFORMAT Command String Since REFORMAT is written in COBOL, it runs as a COBOL object program. It has no logical switches. To run it, enter the following command: RFM RET This causes REFORMAT to begin execution. REFORMAT immediately requests the file specifications for the two files (input and output) to be processed. In response to its prompting messages, type in the file specifications for your two files. RFM-INPUT FILE SPEC: RPM-OUTPUT FILE SPEC: When the system has successfully opened both files, REFORMAT types the following request for an identification entry in columns 73 through 8i. If you desire an identification entry, type in from one to eight characters. REFORMAT places these characters, left justified, in columns 73 through 81! of each output line. If no entry is required, type a carriage return. RFM-COLS 73 TO 8i: Following this response, REFORMAT reads the input file and writes it as 8f!-character records, in conventional reference format. When it has processed the last record in the file, REFORMAT displays the following messages; the first indicating the number (nnnnn) of output records produced and the second requesting another input file. RFM-nnnnn LINES PROCESSED. RFM-INPUT FILE SPEC: If there is another file to be reformatted, follow the s~me sequence with the specifications for the next file. If not, type CTRL-Z to terminate execution. 8-2 REFORMAT UTILITY PROGRAM REFORMAT Error Messages If any of the responses to the prompting messages contain detectable errors, REFORMAT displays the following messages indicating the problem. RFM-ERROR IN OPENING INPUT FILE RFM-TRY AGAIN RFM-INPUT FILE SPEC: The system could not open the input file. Either the file is not present on the device specified (the default device is SY:) or the file name is typed incorrectlyA The usual I/O error messages precede this message. To continue processing that file, examine the input file spec and type in a corrected version. To process another file, type in a new input file specification. To terminate execution, type CTRL-Z. RFM-ERROR IN OPENING OUTPUT FILE RFM-TRY AGAIN RFM-OUTPUT FILE SPEC: The system could not open the output file. An incorrectly typed file specification usually causes this error. (The default device is SY:.) The usual I/O error messages precede this message. To continue, examine the output file specification and type in a corrected version. To terminate execution, type CTRL-Z. RFM-INPUT FILE IS EMPTY RFM-INPUT FILE SPEC: The system successfully opened the input file, but the first READ statement encountered the AT END condition. To continue, type in a new input file specification for another file. To terminate execution, type CTRL-Z. RFM-ERROR IN READING INPUT FILE RFM-INPUT FILE SPEC: The first attempt to read the input file was unsuccessful. This error is usually caused by an input record length exceeding 86 characters. (Although terminal format records should not exceed 66 characters in length, REFORMAT provides a record area of 86 characters and ignores the right-most 2i characters.) To continue, type in a new input file specification for another file. To terminate execution, type CTRL-Z. RFM-ERROR IN READING INPUT FILE RFM-REFORMATTING ABORTED RFM-nnnnn LINES PROCESSED RFM-INPUT FILE SPEC: 8-3 REFORMAT UTILITY PROGRAM While reading input records (other than the first record) , REFORMAT was unsuccessful in an attempt to read a record. It terminates execution and closes both files. To process another file, type in a new input file specification and continue with the prompting message sequence. To terminate execution, type CTRL-Z. RFM-ERROR IN WRITING OUTPUT FILE RFM~REFORMATTING ABORTED RFM-nnnnn LINES PROCESSED RFM-INPUT FILE SPEC: REFORMAT was unsuccessful in an attempt to write an output record. It terminates execution and closes both files. To process another file, type in a new input file specification and continue with the prompting message sequence. To terminate execution, type CTRL-Z. 8-4 CHAPTER 9 SEGMENTATION PDP-11 COBOL allows you to break the Procedure Division up into overlayable and non-overlayable program segments to optimize memory utilization. An overlayable program segment can be overlayed by any other overlayable segment. A non-overlayable program segment, however, can never be overlayed. NOTE The object code generated for the Identification Division through the Data Division is non-overlayable. 9.1 USING THE PDP-11 COBOL SEGMENTATION FACILITY The PDP-11 COBOL Segmentation Facility allows you to specify your own segmentation requirements. To effect segmentation, you must define a segment limit by specifying the SEGMENT-LIMIT IS clause in the Environment Division of your source program. The value you specify in this clause is used by the compiler as a basis for determining whether a program segment is overlayable or non-overlayable. A segment consists of one or more COBOL sections. Each COBOL section should be composed of a series of closely related operations designed to collectively perform a particular function. To designate a section as belonging to an overlayable or non-overlayable segment, assign a segment number to it using the following format: Section-name SECTION segment-number. Where: Section-name Is a user-defined COBOL word that names the section Segment-number Is an inte~er ranging from 0 to 49. If you specify a segment-number whose value is less than the value specified in the SEGMENT-LIMIT IS clause, you have defined the section as being non-overlayable. A segment-number whose value is greater than or equal to the value specified in the SEGMENT-LIMIT IS clause defines the segment as being overlayable. 9-1 SEGMENTATION 9.1.1 Programming Considerations The most frequently used sections of your program should be made non-overlayable. Assign segment-numbers that are less than the value specified in the SEGMENT-LIMIT rs clause to these sections. Infrequently used sections should be made overlayable. Assign segment-numbers that are greater than or equal to the value specified in the SEGMENT-LIMIT IS clause to these sections. Sections that communicate with each other should be assigned to the same segment. Assign the same segment-number to these sections. Sections having identical segment-numbers are assigned to the same segment. 9.2 SEGMENTATION AND THE PDP-11 COBOL COMPILER The previous sections told you how to effect segmentation. This section tells you what segmentation means in terms of code generation. The PDP-11 COBOL compiler breaks up the object code it generates into program sections called PSECTs. One or more PSECTs are generated for each program SECTION. The maximum size PSECT generated is 2000 decimal words. However, this maximum size can be altered by specifying the /CSEG:nnnn switch in the compiler command line. {PSECTs are described in Appendix D: The /CSEG:nnnn Switch is described in Section 9.4, and Section 2.5.3). Also generated, are Overlay Description Language {ODL) directives that group together all PSECTs that belong in the same overlay. These ODL directives are placed in an ODL file to be used as input to the Task Builder. The Task Builder uses the ODL file to generate a task image containing the correct combination of overlayable/non-overlayable PSECTs. If the source program is written without explicit segmentation, all of the generated PSECTs are concatenated into one non-overlayable program. If the source program does contain explicit segmentation, ODL directives are created to group PSECTs together into the correct combination of overlayable and non-overlayable program segments. 9.3 SEGMENTATION USING THE /OV SWITCH The /OV switch, when appended to the compiler command line, directs the compiler to produce ODL directives that make all of the procedural PSECTs overlayable. Therefore, the amount of memory required to store the program is equal to that required to contain the root {non-overlayable portion) and the largest PSECT. (See Figure 9-1, Segmentation Using The /OV Switch; and Section 2.5.3, Compiler Switches). The /OV switch is particularly useful for quickly segmenting programs that were written without explicit segmentation or for overriding explicit segmentation. 9-2 available memory Data and Control PSECTs S1 SECTION SEGMENTATION - - - - - program too big S2 SECTION S3 SECTION procedural PSECTs I .__S__4_S_ ECT!_ 0" II) I available memory n I I I I I l Data and Control PSECTs S1 SECTION generated code using /OV switch l S2 SECTION S3 SECTION S4 SECTION I I J I I I I procedural PSECTs Figure 9-1 Segmentation Using the /OV Switch 9.4 USING THE /CSEG:nnnn SWITCH The PDP-11 COBOL compiler generates a PSECT for each COBOL section. If the code generated for a particular section exceeds the default maximum size for a PSECT (4000 decimal bytes}, more than one PSECT is generated. PDP-11 COBOL provides a switch (/CSEG:nnn) that allows you to control the size of PSECTs generated by the compiler. (See Section 5.2.3 Compiler Switches). If, for example, you compile a program that produces a PSECT that is too large to be task built, you can recompile the program using the /CSEG:nnn switch to reduce the size of the PSECTs generated. See Figure 9-2 for an example of using the /CSEG:nnnn switch. 9-3 SEGMENTATION Command Line (Without /CSEG:nnnn switch specified) CBL> CBLMRG,CBLMRG/MAP=CBLMRG~ SECTION NAME SEGMENTATION MAP SEGMENT NO. NAME SIZE OUTPUT-OOL-USE 00 INPUT-OOL-USE 00 * MAIN-CONTROL 00 PROCESS-INPUT-OOL 00 HOR-CHECK 00 $C$001 $C$002 $C$003 $C$004 $C$005 000172 000172 003336 001130 000322 00061 00061 00879 00300 00105 * One large PSECT is generated Command Line (With the /CSEG:nnnn switch specified) CBL> CBLMRG,CBLMRG/MAP/CSEG:lOOO=CBLMRG~ SECTION NAME SEGMENTATION MAP SEGMENT NO. NAME SIZE OUTPUT-OOL-USE 00 INPUT-OOL-USE 00 * MAIN-CONTROL 00 00 PROCESS-INPUT-OOL 00 HOR-CHECK 00 $C$001 $C$002 $C$003 $C$004 $C$005 $C$006 000172 0001 72 001744 001426 001130 000322 00061 00061 00498 00395 00300 00105 * Two PSECTs are generated Figure 9-2 Using the /CSEG:nnnn Switch 9-4 CHAPTER 10 INTER-PROGRAM COMMUNICATIONS Inter-program communications is the passing of control and optional data from one program within a task to another. PDP-11 COBOL provides you with the ability to Task-build separately compiled COBOL programs into a single task image. During task execution, these separately compiled programs can communicate with each other via the COBOL CALL statement. A task can consist of a stand-alon~ program or a main program and one or more subprograms. A stand-alone program is one that does not call subprograms and cannot itself be called. A COBOL main program is one that calls subprograms but can never be called in return. A COBOL subprogram, however, is always called by another program, either the main program or a subprogram. Inter-program communications deals only with main programs and subprograms. Developing a program as a main program and a set of subprograms offers a number of advantages: 1. Large monolithic programs are no longer required. These large programs can be replaced by a controlling main program and a set of subprograms, where each subprogram is designed to perform a well-defined function. 2. Small subprograms can be developed independently by several members of a programming staff. 3. Small subprograms can be tested more easily than large programs. 4. Small subprograms can be modified and recompiled faster than large programs. 5. General purpose subprograms can be developed and used in more than one programming application. 10.1 COBOL MAIN PROGRAMS VS SUBPROGRAMS A COBOL main program is one that calls other programs (subprograms) but cannot be called in return. A COBOL main program contains at least one CALL statement. A COBOL subprogram is one that is called by another program, either the m~in program or another subprogram. The main program is automatically activated at task execution time. A subprogram, however, is activated only when called by another program. The COBOL compiler differentiates between a main program and a subprogram by the presence or absence of a USING phrase in the Procedure Division header of the program being compiled. The USING 10-1 INTER-PROGRAM COMMUNICATIONS phrase is used only in COBOL subprograms. It defines the program as being a subprogram and optionally identifies the data expected from the calling program. The Procedure Division header has the following format: PROCEDURE DIVISION [USING [data-name-1 da ta-name-2] ... ] . A subprogram, that does not process data (arguments) passed to it by a calling program, has only the word USING appended to the Procedure Division header. For example: PROCEDURE DIVISION USING. A subprogram that processes passed data, has a USING phrase with one or more data-names specified. If a data-name(s) is specified, the program must also contain a Linkage Section in the Data Division. The Linkage Section describes the size and type of data being passed. (See Figure 10-1, Sample LINKAGE SECTION and USING phrase). LINKAGE SECTION. * SUBPROGRAM-DATA. 01 !ST-PARAMETER PIC X(S). 01 2ND-PARAMETER PIC X(S). 01 3RD-PARAMETER PIC X(S). PROCEDURE DIVISION USING 2ND-PARAMETER, 3RD-PARAMETER. NOTES 1. All of the data-names appearing in the using phrase must also appear in the LINKAGE SECTION. 2. Not all of the data-names in the LINKAGE SECTION need appear in the USING phrase. 3. A LINKAGE SECTION can appear in a subprogram even if the USING phrase does not contain a data-name. However, if any of the data-items contained in the LINKAGE SECTION are referenced in procedures, the compiler will issue a fatal diagnostic. Figure 10-1 Sample LINKAGE SECTION and USING Phrase 10.l.l Calling a COBOL Subprogram from a COBOL Program To call a subprogram from a COBOL program, a CALL statement having the following format must be used: CALL literal [USING data-name-1 [, data-name-2] ... ]. 10-2 Where: literal data-name-1 through data-name-n INTER-PROGRAM COMMUNICATIONS is the name that appears in the PROGRAM-ID entry of the called program. identify those data-ite11s in the calling program that can be referred to by the called program. 10.1.2 Returning from a COBOL Subprogram In addition to the required USING phrase and optional LINKAGE SECTION, a subprogram should contain at least one EXIT PROGRAM statement. The EXIT PROGRAM statement identifies the subprogram return point. That is, the point in the subprogram at which control is returned to the calling program. If the EXIT PROGRAM statement is missing, the COBOL compiler will generate one after the last statement in the program. NOTE More than one EXIT PROGRAM statement is allowed in a subprogram. 10.2 UNIQUENESS OF PSECT NAMES The names of all PSECTs within a task must be unique. When a task is composed of more than one COBOL program, you must insure that the PSECTs generated by the COBOL compiler for each program are unique. (See Section D.l, PSECT Naming Conventions). 10.3 COBOL OTS - ERROR CHECKING At task execution, the COBOL OTS performs a check to insure that the number of arguments passed to a called COBOL subprogram is the same as the number expected. That is, the subprogram Procedure Division USING phrase must contain the same number of data-names as the USING phrase in the calling programs CALL statement. If the number of data-names in each USING phrase are not equal, the OTS issues a diagnostic error message and aborts the task. No checks are made to insure that the passed arguments are the same size as the expected arguments. It is your responsibility to insure that these sizes are compatible. Recursive calls to COBOL subprograms are not allowed. If a COBOL subprogram contains a CALL statement that directly or indirectly causes a subprogram to be re-entered before it has exited from its original entry, the OTS will issue a diagnostic error message and abort the task. 10-3 INTER-PROGRAM COMMUNICATIONS 10.4 INCLUDING A NON-COBOL OBJECT MODULE IN A TASK Non-COBOL object modules can be combined with COBOL object modules at task-build time to produce a single task image. However, you are advised to use the same language to write programs that perform I/O operations. This note of caution is very important, because, the PDP-11 programming languages do not share a common OTS. To activate a COBOL subprogram, a non-COBOL calling program must contain the equivalent of a COBOL CALL statement. If data is being passed to the COBOL subprogram, program register R5 must be set to the address of an argument list. The argument list must contain pointers to the data being passed. (See Figure 10-2, Argument List Format}. A non-COBOL subprogram, to be activated by a COBOL program, must contain the equivalent of the COBOL PROGRAM-ID statement and the COBOL EXIT PROGRAM statement (See Example 1 below}. If data is being passed, the non-COBOL subprogram can access that data via program register RS. The following sections provide an example of how non-COBOL programs can be written for inclusion in a COBOL task image. The MACRO programming language is used for the purposes of this example. Example 1 - (Calling MACRO Programs from COBOL} The format for calling any program from COBOL is: CALL literal [USING data-name-1[, data-name-2] .·. ] when a MACRO program is being called, literal contains the global entry point specified in the MACRO program. If the COBOL program contains: CALL "BILBO" USING BOFFIN, BOMBUR, BOFUR. The MACRO program must contain: .GLOBL BILBO! ;entry point - equivalent to PROGRAM-ID BILBO: RTS PC ;return point - equivalent to EXIT PROGRAM If there are any arguments to be passed to the called program (BOFFIN, BOMBUR, and BOFUR in this example}, these arguments can be accessed via program register RS. 10-4 INTER-PROGRAM COMMUNICATIONS Example 2 - (Calling COBOL Programs from MACRO) When the calling program is a MACRO program, control is passed to the called program with the following instruction: JSR PC,subprogram-name Where: Subprogram-name is the first six characters of the COBOL PROGRAM-ID. If the MACRO program contains: .GLOBL FRODO MOV #ARGLST,RS ;point RS to argument list JSR PC,FRODO ;subprogram call statement The COBOL subprogram will contain: PROGRAM-ID. FRODO LINKAGE SECTION. * FRODO-ARGUMENTS. 01 BOFFIN PIC X(S). 01 BOMBUR PIC X(S). 01 BOFUR PIC X(S). PROCEDURE DIVISION USING BOFFIN,BOMBUR. EXIT PROGRAM. The MACRO program, in this example, has set RS to point to the argument list expected by the COBOL program. The COBOL OTS will use RS to access the passed arguments. 10-S INTER-PROGRAM COMMUNICATIONS Word 1 Word 2 ARGUMENT ADDRESS LIST unused l #of arguments in list (n - 1) ~ R5 must be set to point here address of argument #1 Word 3 I address of argument #2 1 Word n address of argument #n - 1 Figure 10-2 Argument Address List 10-6 CHAPTER 11 HAND-TAILORING ODL FILES This chapter is provided as a guide to those of you who are faced with the problem of having to generate ODL files that are compatible with either the Merge Utility or the Task Builder. The most common reason for having to hand tailor an ODL file occurs when non-COBOL programs are being merged into a COBOL task image. The info~mation presented here is predicated vu the assumption that you have read and are familiar with the Task Builder Reference Manual that pertains to your operating system. The following sections describe the standard ODL file as it pertains to PDP-11 COBOL. 11.1 STANDARD ODL FILE The standard ODL file generated by the PDP-11 COBOL compiler consists of a header and a body. The header contains information that is required to merge one or more ODL files. The body contains ODL directives that describe the object program. 11.2 ODL FILE HEADER The ODL file header consists of a sequence of comment lines. Two are required in every ODL file, others are supplied as needed. The required comment lines are: ;COBOBJ=XXXXXX.OBJ ;COBKER=KK Where: XXXXXX.OBJ is the name of the object module being described KK is the kernel that was used to generate the PSECT names for the COBOL program. The following comment lines are supplied as needed: ;COBMAIN This comment line is supplied if the program being described is a main program. The absence of this line means that the ODL file was generated for a COBOL subprogram. ;RMSSEQ=CIOOXY This comment line is specified if the program requires RMS-11 I/O support. One or more lines may be supplied. X and Y represent integer codes that respectively specify the file organization and operational support required for that 11-1 HAND-TAILORING ODL FILES organization. File organization is specified by the following codes: CODE ORGANIZATION 1 sequential 2 relative 3 indexed The values allowed for the operational support code are meaningful only to future versions of PDP-11 COBOL and the Merge Utility. Therefore, they are not defined here. 11.3 ODL FILE BODY The ODL file body describes the overlay £tructure of the COBOL program. The body contains the following ODL directive types: 1. .PSECT defines the name of the code PSECT and makes it known to the Task Builder. 2. .NAME defines the name to be assigned to the overlay segment by the Task Builder. 3. .FCTR describes the contents of the segments. 4. .ROOT defines the root. 5. .END informs the Task Builder that the end of the ODL file has been reached. 6. ;comments contains comment entries. The .ROOT and .END directives are not supplied by the COBOL compiler. They are inserted into the ODL file generated by the Merge Utility. If you are generating a stand alone ODL file, these directives must be supplied by you. If the ODL file you are generating is to be used as input to the Merge Utility, leave these directives out. Within a compiler-generated ODL file, the directives .PSECT, .NAME, and .FCTR are generated around the PSECT kernel. If the PSECT name kernel for a given program is KK, the format of the names generated in the ODL file is: Entity Format of Name .PSECT $KKMMM .NAME KK$MMM .FCTR KKMMM$ Each .PSECT defined in the ODL file begins with a $ followed by the two character kernel ($KK}. Each .NAME directive begins with the two character kernel followed by $ (KK$). Finally, each .FCTR directive begins with the two-character kernel and ends with a $ (KKMMM$). 11-2 HAND-TAILORING ODL FILES 11.4 COMPILER-GENERATED ODL FOR COBOL PSECTS The following sections discuss the ODL directives generated for different types of overlay requirements. The characters NNN when used in examples refer to the three character suffix generated by the compiler for each PSECT. The characters KK refer to the kernel characters that make the PSECT unique to a particular compilation. 11.4.1 ODL Generated for Overlays Containing Only One PSECT For overlays containing only one PSECT, the following lines are generated: .PSECT $KKNNN,GBL,RW,CON,I .NAME KK$NNN,GBL KKNNN$ .FCTR *KK$NNN-$KKNNN 11.4.2 ODL Generated for Overlays containing More Than One PSECT For each overlay that contains more than one PSECT, a .PSECT directive is generated for each PSECT in the overlay. These .PSECT directives are followed by a .NAME and .FCTR directive. Consider the following example. Example Two PSECTs, $AA001 and $AA002, are to be placed .1..u the same overlay. The segment~number assigned to the PSECTs is 20. The following ODL directives are generated: ;DEFINE PSECT $AA001 .PSECT $AA001,GBL,RW,CON,I ;DEFINE PSECT $AA002 .PSECT $AA002,GBL,RW,CON,I ;DEFINE THE OVERLAY NAME .NAME AA$020,GBL ;DEFINE OVERLAY CONTENTS AA020$: .FCTR *AA$020-$AA001-$AA002 11.4.3 ODL Generated for All Overlayable PSECTS All .FCTR directives that desc~ibe the overlayable PSECTs must be collapsed into one final .FCTR directive. This directive describes the entire overlayable portion of the object code. The name associated with this .FCTR directive is derived from the two-character kernel assigned to the PSECTs. If the kernel is KK, then the name of the .FCTR directive that describes the entire overlayable part of the object code is KKOVR$. 11-3 HAND-TAILORING ODL FILES The following example shows how the KKOVR$ factor is developed for various overlay configurations: Example 1: All Code Psects Overlay One Another AA001: AA002$: .PSECT .NAME .FCTR ; .PSECT .NAME .FCTR $AA001,GBL,RW,CON,I AA$001,GBL *AA$001-$AA001 $AA002,GBL,RW,CON,I AA$002,GBL *AA$002-$AA002 AA003$: .PSECT .NAME .FCTR $AA003,GBL,RW,CON,I AA$003,GBL *AA$003-$AA003 AA004$: AA005$: AAOVR$: .PSECT $AA004,GBL,RW,CON,I .NAME AA$004,GBL .FCTR *AA$004-$AA004 ; .PSECT $AA005,GBL,RW,CON,I .NAME AA$005,GBL . FCTR *AA$005-$AA005 ;IN THIS EXAMPLE, ALL PSECTS OVERLAY :ONE ANOTHER. .FCTR (AA001$,AA002$,AA003$,AA004$,AA004$,AA005$) Example 2: Two Code Psects Are in the Same Overlay .PSECT $AA001,GBL,RW,CON,I AA001$: .PSECT ; .NAME .FCTR $AA002,GBL,RW,CON,I AA$001,GBL *AA$001-$AA001-$AA002 AA003$: .PSECT .NAME .FCTR $AA003,GBL,RW,CON,I AA$003,GBL *AA$003-$AA003 AA004$: AA005$: AAOVR$: .PSECT .NAME .FCTR ; .PSECT .NAME .FCTR ; .FCTR $AA004,GBL,RW,CON,I AA$004,GBL *AA$004-$AA004 $AA005,GBL,RW,CON,I AA$005,GBL *AA$005-$AA005 AA001$,AA003$,AA004$,AA005$ Example 3: Two Occurrences of Two Psects in the Same Overlay ;IN THIS EXAMPLE, PSECTS $AA001 AND $AA002 ;ARE IN THE SAME OVERLAY. PSECTS $AA003 ;AND $AA004 ARE IN THE SAME OVERLAY. ;PSECT $AA005 IS IN AN OVERLAY ALL BY ITSELF ; ;PSECT $AA001,GBL,RW,CON,I ; ;PSECT $AA002,GBL,RW,CON,I .NAME AA$001,GBL 11-4 AA001$: AA003$: AA005$: AAOVR$: .FCTR ;PSECT ; .PSECT .NAME .FCTR .PSECT .NAME .FCTR .FCTR HAND-TAILORING ODL FILES *AA$001-$AA001-$AA002 $AA003,GBL,RW,CON,I $AA004,GBL,RW,CON,I AA$003,GBL *AA$003~$AA003-$AA004 $AA005,GBL,RW,CON,I AA$005,GBL *AA$005-$AA005 AA001$,AA003$,AA005$ 11.5 MERGING STANDARD ODL FILES To develop an ODL file for a task composed of more than one COBOL object program, it is necessary to merge the ODL files for each individual object program into a single ODL file that describes the overlay requirements for the task. All of the ODL files to be merged are partial ODL files. Tnat is, none of these ODL files can be submitted directly to the Task Builder to build a task; because, none of the compiler generated ODL files contain a .ROOT directive. The .ROOT directive that describes the task is supplied by the Merge Utility. 11.6 INCLUDING NON-COBOL PROGRAMS IN A TASK To use the Merge Utility to include a non-COBOL object module in a task image, you must: 1. Create a standard COBOL ODL file (use any text editor) 2. Specify this ODL file as input to the Merge Utility. 11.6.l Creating a Standard COBOL ODL File A standard COBOL ODL file for a non-COBOL object module contains one or two directive lines: 1. Object Program ID Line This line is required. It identifies the object module to be included in the task image. The format of this line is: ;COBOBJ=XXXXXX.OBJ Where XXXXXX.OBJ is the name of the object module to be included in the task image. 11-5 HAND-TAILORING ODL FILES 2. Main Program ID Line This line is present only for non-COBOL object modules that are main programs as opposed to being subprograms. The format of the line is: ;COBMAIN For each invocation of the COBOL ODL Merge Utility, one and only one main program ODL file can be specified. If no main program ODL file is specified, the Merge Utility continues to request more input until a main program ODL file is specified. If more than one main program ODL file is specified, all but the first is rejected, and appropriate diagnostic error messages are issued. Consider the following examples. Example 1 MACRO program START.OBJ is a main program in a task consisting of a main program and several subprograms. The ODL file to be hand-generated is: ;COBOBJ=START.OBJ ;COBMAIN Example 2 Macro subprogram SUBX.OBJ is to be part of a task image that consists of several COBOL subprograms and a COBOL main program. The ODL file to be hand-generated is: ;COBOBJ=SUBX.OBJ 11.7 REARRANGING A COMPILER-GENERATED ODL FILE The ODL file generated by the compiler can be rearranged to modify the overlay structure of a task. If the ODL file describes a task that has overlayable segments, one or more of these segments can be converted into non-overlayable segments by: 1. Modifying the compiler-generated ODL file. 2. Specifying a one-line Task Builder option at task-build time for each segment made non-overlayable. 11.7.1 Modifying the Compiler-Generated ODL File Modifying the compiler generated ODL file requires the following steps: 1. Each overlayable segment is named in the ODL file by an ODL .NAME directive. This .NAME directive must be removed. 2. Each name appearing in a .NAME directive is marked with an * and placed as the first element of a .FCTR directive. For each .NAME directive removed by step 1, this .FCTR directive must be removed. 11-6 HAND-TAILORING ODL FILES 3. All references to the name of the .FCTR directive removed in step 2 must be removed from the ODL file. 4. All PSECTs referenced in the .FCTR directive that was removed in step 3, must be removed from the ODL file. Example The task image contains three overlayable segments, C$$010, C$$015, and C$$020. Segment C$$020 is to be forced into the root. Figure 11-1 contains a listing of the merged ODL file. ;MERGED ODL FILE CREATED ON 26-JAN-77 AT 10:50:00 ;COBOL STANDARD ODL FILE GENERATED ON: 26-JAN-77 ;COBOBJ=TESTl.OBJ ;COBKER=C$ ;COBMAIN .NAME C$$010,GBL .PSECT $C$003,GBL,I,RW,CON C$010$: .FCTR *C$$010-$C$003 .NAME C$$015,GBL .PSECT $C$004,GBL,I,RW,CON C$ 015$: . FCTR *C$$ Ol 5-$C$ 004 .NAME C$$020,GBL .PSECT $C$005,GBL,I,RW,CON C$020$: .FCTR *C$$020-$C$005 C$0VR$: .FCTR C$010$,C$015$,C$020$ CBOBJ$: .FCTR TESTl.OBJ CBOVR$: .FCTR C$0VR$ CBOTS$: .FCTR [320,13]COBLIB/LB RMS$: .FCTR [l,l]RMSLIB/LB OBJRT$: .FCTR CBOBJ$-CBOTS$-RMS$ .ROOT OBJRT$-(CBOVR$) .END 10:48:37 Figure 11-1 Merged ODL File Listing To force segment C$$020 into the root, the merged ODL file must be modified as follows: 1. The .NAME directive referencing C$$020 must be removed. 2. The .FCTR directive containing *C$$020 must be removed. 3. All references to the PSECTs in the removed .FCTR directive must be removed. 11-7 HAND-TAILORING ODL FILES Figure 11-2 contains the ODL listing after the modifications have been made. ;MERGED ODL FILE CREATED ON 26-JAN-77 AT 10:55:22 ;COBOL STANDARD ODL FILE GENERATED ON: 26-JAN-77 ;COBOBJ=TESTl.OBJ ;COBKER=C$ ;COBMAIN .NAME C$$010,GBL .PSECT $C$003,GBL,I,RW,CON C$010$: .FCTR *C$$010-$C$003 .NAME C$$0i5,GBL .PSECT $C$004,GBL,I,RW,CON C$015$: .FCTR *C$$015-$C$004 C$0VR$: .FCTR C$010$,C$015$ CBOBJ$: .FCTR TESTl.OBJ CBOVR$: .FCTR C$0VR$ CBOTS$: .FCTR [l,l]COBLIB/LB RMS$: .FCTR [l,l]RMSLIB/LB OBJRT$: .FCTR CBOBJ$-CBOTS$-RMS$ .ROOT OBJRT$-(CBOVR$) .END 10:48:37 Figure 11-2 Modified ODL File 11.7.2 Specifying Task Builder Options For each overlayable segment made non-overlayable, a GBLDEF Task Builder option must be specified at task-build time. The format of the option is: GBLDEF=KK$MMM:O Where: KK$MMM is the name of the segment that is being made non-overlayable. (This is the name in the .NAME ODL directive that was deleted when the ODL file was modified) . Consider the following example. Example To make the overlayable segment (C$$020) described in the example in Section 11.7 non-overlayable, enter the following in response to the Task Builder ENTER OPTIONS prompt: GBLDEF=C$$020:0 ( REt) Figure 11-3 shows the overlay description of the task image before and after segment C$$020 was made non-overlayable. 11-8 HAND-TAILORING ODL FILES BEFORE TESTl.TSK;l MEMORY ALLOCATION MAP TKB M27 26-JAN-77 10:51 PARTITION NAME : GEN IDENTIFICATION : 026108 TASK UIC [320,4] STACK LIMITS: 000176 001175 001000 00512. PRG XFR ADDRESS: 022514 TOTAL ADDRESS WINDOWS: 1. TASK IMAGE SIZE 6880. WORDS TASK ADDRESS LIMITS: 000000 032657 TESTl.TSK;l OVERLAY DESCRIPTION: BASE TOP LENGTH 000000 032510 032510 032510 032507 032607 032657 032617 032510 000100 000150 000110 13640. 00064. 00104. 00072. TEST! C$$010 C$$015 C$$020 3 overlayable segments AFTER TEST2.TSK;2 MEMORY ALLOCATION MAP TKB M27 26-JAN-77 10:57 PARTITION NAME : GEN IDENTIFICATION : 026108 TASK UIC [320,4] STACK LIMITS: 000176 001175 001000 00512. PRG XFR ADDRESS: 022514 TOTAL ADDRESS WINDOWS: 1. TASK IMAGE SIZE 6912. WORDS TASK ADDRESS LIMITS: 000000 032743 TEST2.TSK;2 OVERLAY DESCRIPTION: BASE TOP LENGTH 000000 032574 032574 032573 032673 032743 032574 13692. 000100 00064. 000150 00104. TES Tl C$$010 C$$015 2 overlayable segments Figure 11-3 Overlay Description Map Before and After Modification 11-9 CHAPTER 12 ERROR MESSAGES 12.1 COMPILER SYSTEM ERRORS The PDP-11 COBOL compiler is a complex system program consisting of many program overlays that manipulate numerous data structures. Throughout the compiler, consistency checks are performed on program flow and the contents of data fields. If the compiler detects an inconsistency, it types a message on the console and terminates the compilation. A system error message has the foiiowing format: SYSTEM ERROR NNNNN where NNNNN is a number used by the DEC COBOL developers to determine the probable cause of the error. When a system error occurs, the compiler's input file is closed and all output files (object, list, and ODL) are closed and deleted. In the event of a PDP-11 COBOL compiler system error, contact your DEC Software Support Specialist immediately. 12.2 DIAGNOSTIC ERROR MESSAGES Appendix H contains a numerical listing of the diagnostic messages generated by the PDP-11 COBOL compiler. The compiler generates these messages whenever it detects an error in the source program. In general, a source error detected by the compiler results in the associated diagnostic message being embedded in the source program listing. That is, when an error is detected in the source program, the compiler prints the diagnostic message either before or after the erroneous source program line. There are two exceptions to the general concept of "embedded diagnostics": 1. There may be diagnostic messages listed after the last entry in the Data Division and before the Procedure Division header. These are diagnostics which logically cannot be issued until the entire Data Division text is processed. 2. There may be diagnostic messages listed after the last line of the Procedure Division. These are diagnostics which logically cannot be issued until the entire Procedure Division text is processed. 12-1 ERROR MESSAGES In addition to the error message number and message text, the display contains a source line number, which identifies the error line, and an alphabetic code (discussed below) which informs you of the seriousness of the error. The information in a diagnostic message line is displayed (from left to right) in the following order: 1. Alphabetic code, 2. Source line number, 3. Numerical error number, 4. Text of the diagnostic message. For convenience, the alphabetic code is left-justified in the listing so you merely scan the listing to identify any diagnostic message issued during compilation. Again, for your convenience, a summary of the number of errors detected during the compilation is given at the end of the source listings. If no errors are detected during the compilation, the compiler prints "NO ERRORS" at the end of the source listing. The following illustration shows a typical diagnostic message and the manner in which it appears on the source listing: COBOL 4.00 SRC:MAP.CBL;j jS-NOV-78 18:49:10 PAGE 003 0'0096 0jj97 00j98 00099 MOVE TMP-AMT TO HIGH-AMOUNT. IF HIGH-AMOUNT NOT = HIGHEST-AMT DISPLAY "ERR 10". * MOVE TMP-AMT TO NEW-AMT. I 000'99 372 POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION. jjl00 jjljl jjlj2 0jlj3 0010'4 IF NEW-AMT NOT = OLD-AMT DISPLAY "ERR 11". * MOVE NEW-AMT TO NEXT-AMT. IF NEXT-AMT NOT = MIN-AMT DISPLAY "ERR 12". * In the example, the diagnostic message is immediately identified by the appearance of the left-justified alphabetic code I. The alphabetic code indicates that the message is an I-type (informational) diagnostic; the diagnostic is issued for source line number 99; the error number is 372; and the text of the message is POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION. Note that the diagnostic message line, in this example, appears after the source line for which it was issued. The error messages, used in conjunction with this chapter, provide you with an important debugging tool. This chapter contains information necessary for interpreting tne messages. i~ explains what caused the error and how the compiler handled the error. 12-2 ERROR MESSAGES Since different errors cause varying degrees of problems for the compiler (some do not affect the compilation at all, while others may be so critical that they cause an abort of the compilation), the PDP-11 COBOL compiler provides four general types (or severity levels) of diagnostic messages. Alphabetic codes (I, W, F, and A) identify these error levels. When it detects an error in the source program, the compiler attempts to recover from the error and continue to compile the program. This recovery action may force the compiler to make an assumption about the source program. The four levels of diagnostic messages are categorized according to the likelihood that the result of the compiler's assumption will be an object program that runs as originally intended by the programmer. The following list explains the purpose of and the compiler's action for each of the four message levels: I (Informational) Informative diagnostic. The purpose of such a diagnostic is to convey information to you in an observational or advisory capacity. The compiler's error recovery (if any is required) is almost certain to follow your intent. W (Warning) Warning diagnostic. The purpose of this type of message is to warn you that something is wrong with the associated source statement, but that the compiler can take corrective action on the source element in error. The compiler's recovery action may not agree with your intent, but the statement, as corrected by the compiler, will be executable. F (Fatal) Fatal diagnostic. The purpose of such a diagnostic is to indicate to you that something is rataiiy wrong with the indicated source statement. By fatal, the compiler means it cannot generate the object code required for the functionality the programmer coded in the erroneous source statement. The compiler's error recovery action will probably leave out a portion of the source program. In general, the compiler will not produce an object program for COBOL source programs that have F-type errors in them. However, you can force the compiler to generate an object program by specifying the /ACC:2 switch in the command string input to the compiler prior to compilation (See Section 2.3.2, Compiler Switches, for a detailed explanation of the /ACC:n switch.) The /ACC:2 switch causes the compiler to generate an object program, even if the source program contains F-type errors. When the object program is executed, it can fail when it attempts to execute code generated as a result of the fatal, but accepted, error. 12-3 ERROR MESSAGES WARNING When you specify the /ACC:2 switch, you formally acknowledge that you are willing to let the program go into execution even though it may have fatal errors in it. Because the source program has very severe errors in it, the behavior of the associated object program is, in general, unpredictable. In certain cases, such as a COBOL program with files opened in I-0 mode, ietting the program with F-type errors go into execution could cause undetected serious errors, such as damage to files. Therefore, the /ACC:2 switch should be used with caution. The facility is provided as an extra debugging option. It can be useful in shortening the compile-debug cycle, particularly if applied to large COBOL programs which take considerable compilation time. A (Abortive) Abortive diagnostic. The purpose of this type of diagnostic is to inform you that the compiler must abort compilation. The compiler's error recovery is not possible: it can make no valid assumptions and has no choice but to abort the compilation. 12.3 RUN-TIME FILE I/O ERROR PROCEDURES When an error condition occurs during I/O operations, the following procedure is used: 1. If the file status key for the file is present, it is set to the appropriate code for the error condition. Appendix C of the PDP-11 COBOL Reference Manual lists file status key values. 2. If an AT END or INVALID KEY imperative condition is specified for the I/O operation, the path indicated by the imperative statement is taken. The file system performs no other processing in the file for the current statement. The USE procedure, if one is declared for the file, is not performed. 3. If no AT END or INVALID KEY imperative condition is ~pecified for the I/O operation and a USE procedure is declared for the file, the USE procedure section is performed, and then control is returned to the program. The file system performs no further processing for this file. If no USE procedure is declared for the file, a fatal error condition exists; the OTS aborts the program and displays an I/O error message. In the following example, RMS failed to find the specified r1~e. Having no USE procedure to execute, the OTS displays the message: CBL -- 17: OPEN ERROR USING FILE (ACCTG.DAT) ASSOCIATED RECORD SERVICES ERROR: -736 (-26) 12-4 ERROR MESSAGES NOTE The OTS does not display an I/O error message if it executes a USE procedure. However, if the program executes a STOP RUN statement in the USE procedure, the OTS displays the error message as if no USE procedure existed. The OTS error messages are listed and described in Appendix J; Appendix I describes the Record Management Services error messages. 12.4 RUN-TIME ERROR MESSAGES Wherever it can, the COBOL OTS will list auxiliary information along with the error message: · PROGRAM-ID. The OTS displays the first six characters of the program-name in the PROGRAM-ID paragraph. e IDENT. Refers to the identification number that the compiler assigned to the program compilation. IDENT appears at the beginning of the compiler listing. · PSECT. Refers to the PSECT that was being executed when the OTS detected the error. PSECT names are found in the Procedure Map on the compiler listing. OFFSET. Specifies the octal byte offset from ~ne beginning of the PSECT. Offset locations appear on the compiler listing if the /OBJ switch is used when the program is compiled. e NESTED PERFORM SOURCE LINE NUMBERS. If the program was executing one or more PERFORM statements when the error occurred, the OTS lists the source listing line numbers of each PERFORM statement to help you locate the error. 12-5 CHAPTER 13 COBOL INTERACTIVE DEBUGGER (CID) This chapter describes the use of the COBOL Interactive Debugger (CID), which is an interactive aid that you can include in your program during the merge or task-build process. The chapter concludes with a sample CID debugging session and a COBOL programming example. By using CID, you can: · Examine and change data in your program · Set, show, and cancel breakpoints · Control program flow CID allows you to find program errors without recompiling or changing your program. To use CID, you need only task-build the program with the CID module, then run it. NOTE In this chapter's examples, responses are underlined. system 13.1 HOW TO INCLUDE CID All CID references to your program are in terms of program name, segment, and offset. A simple way of getting this information is to specify the /MAP and /OBJ switches when you compile your program. Follow this procedure to generate programs with CID: 1. Produce a listing and specify the /MAP and /OBJ switches when you compile your COBOL program. 2. Print the listing and keep it for the debugging session. 13-1 COBOL INTERACTIVE DEBUGGER (CID) 3. Task-build your program. Place the CID module specifier before the COBLIB specification in the command line. If you use the MERGE utility, you can include CID ~hen. For example: RSTS/E: TKB> PROG:PROG,LB:CID,COBLIB/LB RSX-11M: TKB> PROG=PROG,[1,1]CID,COBLIB/LB IAS: LINK PROG,LB:[1,1]CID,LB:[1,1]COBLIB/LIBRARY, RMSLIB/LIBRARY If you use the MERGE utility, respond to the following question as shown: DO YOU WANT TO INCLUDE THE COBOL DEBUGGER (CID)? PLEASE ANSWER Y(ES) OR NCO): YES 4. Execute the program. CID takes control and prompts you for input with: CID> NOTE Including CID adds about 1000 (decimal) words to your program's memory address space requirement. If the increase exceeds the program's size limit, recompile it (for debugging purposes only) with the /OV switch. 13.2 COMMAND MODE AND THE CID ENVIRONMENT CID is in command mode when the debugger is waiting for your input (displaying the prompt CID>). When your program is in CID command mode, the current location (segment) is called the CID environment. The environment consists of the program name and segment number, where: 1. Program name refers to the name in the PROGRAM-ID paragraph in the main program or called program. 2. Segment number refers to the segment within the named program. Except for SET BREAKPOINT and CANCEL BREAKPOINT, commands affect only the current environment. You can examine and change data only in the current program (with the exception of linkage parameters). When you run a program that includes CID, the initial environment is segment 01 of the main program, and CID is in command mode. The environment changes only as the program executes. Therefore, to gain control of CID in a different environment, you can set breakpoints and continue execution; CID returns to command mode when it reaches the breakpoint. 13-2 COBOL INTERACTIVE DEBUGGER (CID) 13.3 ADDRESSING Several CID commands refer to data or code locations in your program. The following sections describe the different methods of addressing data and code. 13. 3. 1 Addressing Data The compiler generates data descriptors for all Data Division items that you reference in Procedure Division statements. The OTS accesses data items by using information in the descriptors. A DATA address is an octal number that specifies the relative location of the data descriptor. You find these addresses in the "DIR LOC" column on the data map listing. Linkage Section items are addresses prefixed with the letter "L" on the data map listing. Because the compiler assigns addresses for the Linkage Section differently than it does for other Data Division sections, you must use the /LINKAGE option to reference them. You cannot reference items marked on the data map with "*****" in place of an address. Asterisks indicate that you did not reference the item in the Procedure Division and that the compiler, therefore, did not generate a data descriptor. Reference table items by following the address with a list of subscripts enclosed in parentheses. Specify subscripts as unsigned decimal integers, and separate multiple subscripts with commas, as you would in a COBOL statement. Examples: 0 56 14(9) 20(23,12) The first two examples reference data items whose data descriptors are located at octal 0 and 56. The third reference specifies the ninth occurrence of the table item whose data descriptor is located at octal address 14. The last example specifies a multiply-subscripted data item whose data descriptor is at octal address 20; the subscripts are written exactly as they would be in a COBOL statement. 13. 3. 2 Addressing Procedure Division Code Procedure Division code addresses have three parts: 1. Program name 2. Segment number 3. Octal offset in the segment For example, the address PROGA:2,6 refers to offset location 6 in segment 2 of the program named PROGA in its PROGRAM-ID paragraph. 13-3 COBOL INTERACTIVE DEBUGGER (CID) In some commands, the program name and the segment number are optional. However, if you specify the program name, you must also specify the segment number. If you omit the program name, but specify the segment number, the colon (:) is required. Examples: PROGA: 2, 16 refers to program PROGA, segment 2, offset 16 :3,32 refers to segment 3, offset 32 in the current program 6 refers to offset 6 in the current environment The program listing contains the address for each verb in the Procedure Division on the program listing if the /OBJ switch was used. In the following extract from a listing for program PROGA, the full address of the MOVE statement is PROGA:5,70. IF MOVE 05 000054 05 000070 00395 IF A = B MOVE B TO C. 13.4 COMMANDS CID commands consist of words, numbers, alphanumeric strings and the special characters: left parenthesis right parenthesis period (decimal point) comma minus sign = equal sign colon I slash or stroke Use upper-case letters to enter command and option words; and separate the items of each command by one or more spaces or tab characters. You can abbreviate command and option words to a single letter. Because CID interprets only the first letter of each word, it accepts misspellings. 13-4 COBOL INTERACTIVE DEBUGGER (CID) These CID commands are discussed in the following sections: CANCEL BREAKPOINT Unmark a stop location DEPOSIT Change the value of a data item EXAMINE Display the value of a data item GO Control execution path SET BREAKPOINT Mark a location to stop execution SHOW BREAKPOINTS Display active breakpoints XIT Terminate debugging session 13.4.1 CANCEL BREAKPOINT Command Format: CANCEL BREAKPOINT <code address> Use this command to cancel or remove a breakpoint that was set at the specified <code address>. CID displays the following message after it cancels the breakpoint: CAN <program name> : <segment number> <offset> Examples~ CID> CANCEL BR 6 Cancels the breakpoint at location 6 in the current segment of the current program. CAN PROGA : 01 000006 CID> C B PROGB :3,42 Cancels the breakpoint at location 42 in segment 03 of program PROGB. CAN PROGA 03 000042 CID> 13.4.2 DEPOSIT Command Format: DEPOSIT [/LINKAGE] <data address> = <value> Use this command to replace the value of the addressed data item with a new value. For numeric items, enter <value> as a 'decimal number. You can include a decimal point and leading minus sign. The OTS moves the value according to the COBOL rules for the MOVE statement. Therefore, decimal alignment, truncation, and other formatting occur as specified by the data description. 13-5 COBOL INTERACTIVE DEBUGGER (CID) For alphanumeric, alphabetic, group, and all edited items, enter <value> as an alphanumeric literal (enclosed in quotes). The OTS moves the literal according to the COBOL rules for a group move. Use the /LINKAGE option to deposit values into data items in the Linkage Section of your program. You cannot DEPOSIT values into inde~ data items. Examples: CID> DEPOSIT 6:1.34 1. 34 CID> D 12(3) =-15 -15 CID> DE 126="HELL0" HELLO -CI0D>- D0=0 CID> CID displays the new value of the data item after a DEPOSIT operation. You can then confirm that the change is correct without using an additional EXAMINE command. For example, if the picture of the item is X(5) and you enter: CID> DEPOSIT 42="SYSTEM" CID displays: and you -see immediately that truncation occurred. 13.4.3 EXAMINE Command Format: EXAMINE [/LINKAGE] <data address> Use the EXAMINE command to display the value of the addressed data item. CID displays numeric items as numeric values with decimal points and (for negative values) leading minus signs. It displays alphanumeric items, such as alphabetic or edited, as strings of ASCII characters, with non-printable characters disp1ayed as "?". Use the /LINKAGE option to display data items located in the Linkage Section of your program. Examples: CID> EXAMINE 104 105.6 C115>EX 142 NEWHAMPSHIRE CID> E 12(3,5) =-16 CID> EX/L 220 0-- CID> 13-6 COBOL INTERACTIVE DEBUGGER (CID) 13.4.4 GO Command Format: GO [<offset>] Use the GO command to resume execution of your program. Specify <offset> to continue execution at a different location in the current segment. Otherwise, execution continues at the next instruction. Remember that you can continue execution only in the current environment. CID does not confirm that a valid instruction exists at the specified offset; therefore, the result of specifying an incorrect offset is unpredictable. CID also does not reset PERFORM exits; therefore, using the GO command to le~ve an active PERFORM can result in a later error. 13.4.5 SET BREAKPOINT Command Format: SET BREAKPOINT <code address> Use this command to set a breakpoint at <code address>. Up to ten breakpoints can be active at one tim.e. If all ten breakpoints are active, CID displays an error prompt when you type this command. To set a new breakpoint when ten are active: 1. Use the SHOW BREAKPOINTS command to display the active breakpoints. 2. Use the CANCEL BREAKPOINT command to remove breakpoints that you no longer need. 3. Set the new breakpoint. CID displays the following message when the breakpoint is set: SET <program name> <segment number> <offset> If your program later reaches the breakpoint, CID displays: AT: <program name> : <segment number> <offset> It then waits in command mode for a new entry. Examples: CID> SET BREAKPOINT 26 Sets a breakpoint at location 26 in the current segment of the current program. SET PROGA : 02 000026 CID> SB PROGA:3,1422 Sets a breakpoint at location 1422 in segment 3 of program PROGA. SET PROGA 03 001422 13-7 COBOL INTERACTIVE DEBUGGER (CID\ 13.4.6 SHOW BREAKPOINTS Command Format: SHOW BREAKPOINTS Use SHOW BREAKPOINTS to display the list of active breakpoints and the location of the current breakpoint. Notice that this command looks the same to CID as SET BREAKPOINT without a code address: since CID interprets only the first character of each word. Examples: CID> SHOW BREAKPOINTS BP: PROGA 01 000026 BP: PROGA 03 001422 BP: SUBR 07 000104 AT: SUBC 02 000062 CID> S B (same as above) CID> 13.4.7 XIT Command Format: XIT Use this command to end the execution of your program and the debugging session as if your program executed a STOP RUN statement. 13.5 PROGRAM INITIATION When your program begins, it automatically enters CID command mode as if you had set a breakpoint before the first instruction. However, CID cancels this breakpoint automatically when you enter any valid command. Use this automatic breakpoint to: 1. Examine or change data before your program begins. 2. Set breakpoints for use later in the debugging session. 3. Begin execution at a different location. 13-8 COBOL INTERACTIVE DEBUGGER (CID) 13.6 USING BREAKPOINTS CID suspends execution of your program and returns to command mode when your program reaches a breakpoint. Set breakpoints at significant locations so you can: 1. Examine data to verify correctness. 2. Change data to correct values. 3. Change data or continue execution at another location to test a theory that explains incorrect results. Before you transfer control, analyze your program's current status to be sure that the transfer will not leave an active PERFORM. Otherwise, the OTS will terminate your program's execution if it detects an improperly nested PERFORM because the old PERFORM is still active. 13.7 PROGRAM TERMINATION AND SUSPENSION Program execution can be terminated in three ways: 1. You can terminate both your program and the debugging session by: · Using the XIT command during command mode · Typing a termination control character, such as ~c 2. The OTS suspends execution of your program when it detects an error. It displays an error message and returns control to CID. CID then displays the following message and enters command mode: AT: <program name> <segment number> 177777 CID> Although the CID message does not indicate the location of the error, you can find it in the OTS error message. You can continue execution by using the GO command with a new location, provided it is in the same environment in which the error occurred. Before transferring control, you may want to use other CID commands to examine or change data, or to set breakpoints. CID terminates the debugging session if you enter·a GO command without a location. 3. The OTS suspends program execution when it executes a STOP RUN statement. It returns control to CID, as described earlier; the OTS error message does not appear since no error condition exists. You can terminate the session or continue execution as just described. 13-9 COBOL INTERACTIVE DEBUGGER (CID) 13.8 CID Command Errors When CID detects an error in a command entry, it sounds an alarm (using the BELL character) and displays the prompt: Although more specific error reporting would be useful, it was omitted to mini~ize your program;s memory requirement when you request the CID module. Some errors that frequently occur are: 1. Typing a non-existent command, such as a "2". 2. Typing a command in lower case, such as "go". (You must use upper case.) 3. Forgetting to enter the colon when you intend to specify the current program name in a code address, such as "S B 5,6". The correct command would be "S B :5,6". 4. Forgetting to leave a space between multiple-word command words, such as typing "CB" instead of "C B" to abbreviate "CANCEL BREAKPOINT". 5. Omitting the second word in two-word commands, such as entering "CANCEL" instead of "CANCEL BREAKPOINT". 6. Omitting the equal sign in a DEPOSIT command. 7. Omitting quotes in a DEPOSIT -command that refers to a non-numeric data item. 8. Trying to DEPOSIT a non-numeric value into a numeric data item. 9. Trying to DEPOSIT a value into an index data item. 10. Trying to set more than ten breakpoints. 11. Specifying an invalid offset. 12. Trying to continue execution in a non-current environment. 13. Forgetting to use the /LINKAGE option in the EXAMINE and DEPOSIT commands when trying to reference data items located in the Linkage Section. 13-10 COBOL INTERACTIVE DEBUGGER (CID) 13.9 EXAMPLES This section contains an annotated debugging session that demonstrates the use of many CID features. Following it are sample listings of a COBOL program (TESTA) and a subprogram (TESTB); the debugging session references these listings. Program TESTA accepts a character string from the terminal and passes it to TESTB. TESTB reverses the character string and returns it (and its length) to TESTA. 13. 9. 1 Sample Debugging Session The following debugging session does not demonstrate the location of actual program errors; it is designed to show the use of CID features. The session begins immediately after the RUN command is entered: 1) We get control before execution of the first COBOL statement in the program. ll'T'. l'l.J.. TESTA 01 000006 2) Now, we set a breakpoint in program TESTB just after it determines the length of the string. CID confirms that the breakpoint was set. CID> SET BREAKPOINT TESTB:1,164 ~TESTB : 01 000164 3) We also set a breakpoint in TESTA just before it calls TESTB. Note that the abbreviation "S B" is sufficient, as is "SET B" in a later command. CID> S B 46 ~ESTA : 01 000046 4) We set a third breakpoint just before TES TB displays the string length (DISP-COUNT). Note that the colon is required before the segment number. CID>SET B :2,34 ~TESTA 02 000034 5) We change the value of LETTER-COUNT. CID displays the value it stored; note that the value was truncated because the PICTURE of LETTER-COUNT specifies only two digits following the assumed decimal CID> DEPOSIT 0 = 1.836 1. 83 point. 6) We attempt to DEPOSIT a numeric value into INPUT-WORD (an invalid operation). CID responds by sounding an alarm (using the BELL character) and displaying a question mark. -CI?D-> DEP 6 = 55 13-11 COBOL INTERACTIVE DEBUGGER (CID) 7) We attempt to continue execution at location 6 in segment 01 of TESTB. CID rejects the command; we can transfer control only to a point in the current environment (program and segment). CID> GO TESTB:1,6 1._ 8) Having set breakpoints for later in the session, we continue execution with the next statement. The program continues: displays a prompt, and waits for input. CID> GO ENTER WORD 9) We enter the string "NOW IS THE TIME". The program continues execution until it reaches the breakpoint we set in Step 3. NOW IS THE TIME AT: TESTA 01 000046 10) We EXAMINE the contents of INPUT-WORD to confirm that it matches the actual entry. CID> EXAMINE 6 ~IS THE TIME 11) This command replaces the content~ of INPUT-WORD with the string "FOR ALL". CID> D 6 = "FOR ALL" CID echoes the stored value. FOR ALL 12) We continue execution. The program re-enters CID command mode when it reaches the breakpoint in TESTB that we set in Step 2. CID> GO AT: TESTB 01 000164 13) Now that TESTB has determined the length of the string, we examine the contents of SUB1 to see the character count. Note that the command is misspelled; CID looks only at the first character of the word. -CI7D-> EXAMNIE 0 14) We set another breakpoint one statement later. CID> S B 174 ~TESTB : 01 000174 15) Then we continue. CID regains control after the execution of a single COBOL statement. CID> GO AT: TESTB 01 000174 16) We examine the contents of CHARACTER-COUNT. Note that the "/LINKAGE" option is necessary because the data item is in the LINKAGE SECTION. CID> EX/L 26 7.00 13-12 COBOL INTERACTIVE DEBUGGER (CID) 17) We request a list of all active breakpoints. CID also reports the current location. CID> S B BP: TES TB 01 00~164 BP: TESTA 01 000046 BP: TESTA 02 000034 BP: TES TB 01 000174 AT: TES TB 01 000114 18) We cancel the breakpoint at location 174. Note that the "B" is required, since this is a two-word command. CID> CANCEL B 174 ~TESTB : 01 000174 19) We continue execution. The program (TESTA) displays the result string that was returned by TESTB; it then enters CID command mode when it reaches the breakpoint we set in Step 4. CID> GO ITAROF AT: TESTA 02 000034 20) We examine the contents of LETTER-COUNT. Note that a space is not required between a CID command and a numeric argument. CID> E0 7.00 21) We alter the flow of the program by specifying an offset in the GO command. CID transfers control to offset location 6 in the current environment (segment 02 of TESTA). The next COBOL statement executed is the DISPLAY at source line number 25; once again, CID regains control at the breakpoint set in step 4. CID> GO 6 LIAR OF AT: TESTA 02 000034 22) We continue execution. When the program executes the STOP RUN statement, CID gains control and displays the pseudo-location 177777, which indicates program suspension (termination). Note that this is not an actual program location. CID> GO AT: TESTA 02 177777 23) We terminate the session (and the program, of course) by entering an XIT command. Since a STOP RUN has been executed, the program would also terminate if we entered a GO command with no location. We also could have continued program execution at another place by entering a GO command with a location. CID> X 13-13 COBOL INTERACTIVE DEBUGGER (CID) 13.9.2 Sample Program Listings DISPLAY MOVE ACCEPT CALL DISPLAY MOVE 01 000006 01 000024 01 000034 0 1 000046 02 000006 02 000024 00001 00002 00003 00004 00005 00006 00007 00008 00009 00010 00011 00012 00013 00014 00015 00016 00017 00018 00019 00020 00021 00022 0002 3 000 24 00025 00026 IDENTIFICATION.DIVISION. PROGRAM-ID. TESTA. DATE-WRITTEN. SEPTEMBER 1978. DATE-COMPILED. 13-SEP-78 . ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. PDP-11. OBJECT-COMPUTER. PDP-11. DATA DIVISION. WORKING-STORAGE SECTION. 01 LETTER-COUNT PIC 9(2)V9(2). 01 INPUT-WORD PIC X(20). 01 DISP-COUNT PIC 9 ('2). PROCEDURE DIVISION. GETIT SECTION. BEGINIT. DISPLAY "ENTER WORD". MOVE SPACES TO INPUT-WORD. ACCEPT INPUT-WORD. CALL "TESTB" USING INPUT-WORD LETTER-COUNT DISPLAYIT SECTION. SHOW-IT. DISPLAY INPUT-WORD. MOVE LETTER-COUNT TO DISP-COUNT. I 00026 0)72 POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION. DISPLAY STOP 02 000034 02 000054 00027 000 28 DISPLAY DISP-COUNT " CHARACTERS". STOP RUN. LEVEL NAME QJ 1 LETTER-COUNT rt .. \0 I INPUT-WORD 01 DISP-COUNT DATA MAP SOURCE DDIV DIR USAGE CLASS occ LEN LINE LOCN LOC 00013 000224 00 QJ 000 DISP NUM 0Grn 14 000230 000006 DISP AN 00015 000254 000014 DISP NUM QJ 0 000 4 00 0020 00 000 2 13-14 COBOL INTERACTIVE DEBUGGER (CID) F OVE 10 1ERFORM 0i 000022 01 000042 01 000052 OVE :OVE 1ERFORM 01 000164 01 000174 01 000204 IOVE 01 000304 :XIT 01 000322 !OVE 01 000334 :UBTRACT 01 000370 00001 00002 00003 00004 00005 00006 00007 00008 00009 00010 00011 00012 00013 00014 00015 00016 00017 00018 00019 00020 00021 00022 00023 00024 00025 00026 00027 VJVJVJ2 8 00029 00030 00031 00032 00033 00034 00035 00036 00037 00038 00039 00040 00041 00042 IDENTIFICATION DIVISION. PROGRAM--ID. TESTB. DATE-WRITTEN. SEPTEMBER 1978. DATE-COMPILED. 13-SEP-78 . ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. PDP-11. OBJECT-COMPUTER. PDP-11. DATA DIVISION. WORKING-STORAGE SECTION. 01 SUB1 PIC 9(2). 01 SUB2 PIC 9(2). 01 HOLD-WORD. 03 HOLD-CHAR PIC X OCCURS 20 TIMES. LINKAGE SECTION. 01 THE-WORD. 03 THE-WORD-CHAR PIC X OCCURS 20 TIMES. 01 CHARACTER-COUNT PIC 99V99. PROCEDURE DIVISION USING THE-WORD, CHARACTER-COUNT. CONVERT-IT SECTION. STARTUP. IF THE-WORD = SPACES MOVE 0 TO CHARACTER-COUNT GO TO GET-OUT. PERFORM LOOK-BACK VARYING SUB1 FROM 20 BY -1 UNTIL THE-WORD-CHAR (SUB1) NOT =SPACE. MOVE SUB1 TO CHARACTER-COUNT. MOVE SPACES TO HOLD-WORD. PERFORM MOVE-IT VARYING SUB2 FROM 1 BY 1 UNTIL SUB 1 = 0. MOVE HOLD-WORD TO THE-WORD. GET-OUT. EXIT PROGRAM. MOVE-IT. MOVE THE-WORD-CHAR (SUB1) TO HOLD-CHAR (SUB2). SUBTRACT 1 FROM SUB1. LOOK-BACK. 13-15 COBOL INTERACTIVE DEBUGGER (CID) EXIT 01 000406 00043 EXIT. LEVEL NAME 01 01 01 03 L 01 L 03 L 01 SUB1 SUB2 HOLD-WORD HOLD-CHAR THE-WORD THE-WORD-CHAR CHARACTER-COUNT DATA MAP SOURCE DDIV DIR USAGE CLASS occ LI LINE LOCN LOC 00013 000224 000000 DISP NUM 00014 000226 000006 DISP NUM 00015 000230 000014 DISP AN 00016 000230 000022 DISP AN 00018 000000 000000 DISP AN 00019 000000 000006 DISP AN 00020 000000 000026 DISP NUM 00 0( 00 0( 00 0( 01 0( <10 0( 01 0( 00 0( 13-16 CHAPTER 14 OPTIMIZATION Optimization is the process of designing or altering a program to min1m1ze space allocation or execution time, or to achieve an effective trade-off between the two. This chapter provides guidelines for optimizing performance of COBOL programs. It is oriented toward optimization techniques that are controllable at the COBOL source language level. For more information on optimization techniques you can use through Record Management Services (RMS) facilities, refer to appropriate RMS documentation. Before attempting to optimize a program, you should know the space and time constraints imposed by your equipment. Estimate how often the program will be run, and its importance in the system. Some other points to consider are: 1. What other routines are dependent on the results of your routine? 2. What system resources are currently available? Will additional resources be added to your system in the near future? If program run times seem excessive, is the problem attributable to slow I/O, and is slow I/O due to a scarcity of disk space? 14.1 OPTIMIZING MASS STORAGE I/0 The COBOL source language is oriented toward commercial data processing applications, which tend to be heavily involved with file activity. Therefore, you can either enhance or undermine system performance, depending on how you design, populate, and handle files. 14-1 OPTIMIZATION When writing or revising COBOL programs with optimization in mind, your funda~ental goal should be to minimize I/O activity. Your answers to the following questions should influence your choice of file organization, record type, buffer size and number, and your program organization: 1. What kinds of I/O operations are necessary to process the data? 2. How can you best place I/O operations in the program? 3. How should you structure the file? Are multiple access keys necessary or desirable? 4. For each file, are frequent record updates and insertions likely, or will file contents remain relatively (or absolutely) stable? 5. How much task address space is available? 14.2 PROGRAM DEVELOPMENT You can influence performance greatly by the way you organize your program. This section offers several guidelines toward an efficient program structure. 14.2.1 Overlay Structure Reading overlays into memory requires considerable I/O activity. Therefore, you should plan overlay structure before writing the program. It is difficult to give specific suggestions that apply in all cases. However, if you cluster all file openings at the beginning of the program, and a~l file closings at the end, you can obviously plac~ all record operations (READ, WRITE, REWRITE) between these portions. Then, by overriding the default RMS overlay structure, you can in some cases reduce the number of RMS-induced overlays during program execution. When you use a default RMS overlay structure, every RMS record operation requires at least one overlay, and frequently more. By minimizing overlays: you can reduce task-build time as well as program run time. Be alert for situations in which read-write thrashing can occur, and try to coordinate I/O activity to eliminate them. You can avoid the I/O overhead penalty of an overlayed task structure by task-building without an ODL file and creating a non-overlayed task, although this is feasible only in rare cases. In any case, organize your program to obtain the maximum benefit from each overlay. The Task Builder Reference Manual describes ODL files in detail. 14-2 OPTIMIZATION 14.2.2 Sequentially Reading Indexed Files If you access an indexed file sequentially, and the file is write-shared, performance improves if you use OPEN I-0 instead of OPEN INPUT. Using OPEN I-0 implies a possibility that you will write to the file--even though you have no intention of doing so. Reading from a file that is open for input-output improves performance by locking the bucket, allowing you to obtain subsequent records from the same bucket without rereading it. 14.2.3 Caching Index Roots RMS requires at least two buffers to process an indexed file. Each buffer is large enough to contain a single bucket. If your COBOL program does not contain a RESERVE n AREAS clause, the compiler includes these two required buffers in your task by default. By including a RESERVE n AREAS in the SELECT statement for a file, you can cause additional (but not fewer) buffers for the processing of an indexed file. At run time, RMS will retain (cache) the roots of one or more indexes of the file in memory. The random access of any record through that index will then require one less I/O operation. The following rules apply for caching index roots: 1. The file must not be shared at run time. 2. Allocate one buffer for each key that your program uses to access file records, in addition to the two required buffers. For example, if the file contains a primary key and two alternate keys, and you use all of these keys to access records, you should allocate five buffers total. If you use only one key to access this file in a program, you need only one additional buffer area, or three in all. 3. Use the RESERVE n AREAS clause to obtain this allocation, where n is two more than the number of distinct keys used for access. For example, the clause RESERVE 5 AREAS causes allocation of the two required buffers, plus three buffer areas for caching the roots of three distinct file access keys. 14.2.4 Multi-block Reading and Writing The multi-block read and write facility applies only to sequential files on disk devices. It allows reading or writing of more than one 512-byte block at a time during a single I/O operation, reducing the number of I/O operations needed to process a file. However, the single buffer used to process the file must be correspondingly longer. 14-3 OPTIMIZATION To use this facility, be sure the file has SEQUENTIAL organization and resides on disk. Then, in the FD entry for the file, specify: BLOCK CONTAINS n CHARACTERS where n is a multiple of 512. Each such multiple represents the number of virtual blocks to be read or written during each access of the file. If n is not a multiple of 512, the compiler rounds the size to the next multiple of 512. 14.3 FILE DESIGN This section describes the effect of file design on performance. The following suggestions apply to any type of file organization. 1. Preallocate the entire file, contiguously if possible, using the /CO:n or /AL:n file switch (described in Table 14-1) or the RMS DEFINE utility. 2. Select a suitable default extend quantity when you create the file, using the /EX:n file switch or the RMS DEFINE utility. (Refer to RMS documentation for a description of default extend quantities and the RMS DEFINE utility.) 3. Know the relationships between record size and file storage, and try to define a record size suited for efficient storage and retrieval. 4. Use the SAME RECORD AREA clause to save compute time and conserve address space. If records are being copied from one file to another, and both files share the same record area, no MOVE statement is needed to move record images between two record areas. The disadvantage is that records from both files cannot be available simultaneously unless one is moved to a work area. Note the distinction between the SAME RECORD AREA and SAME AREA clauses. 5. The SAME AREA clause saves even more address space than the SAME RECORD AREA clause by causing two or more files to share the same buffer area. However, not more than one of the fiies can be open at any one time. 14.3.l Sequential Files Sequential files have the simplest structure and the fewest options for definition, popuiation, and handiing. Reduce the number of disk accesses by keeping record length to a minimum. With a sequential disk file, you can use the multi-block read and writ~ facility described previously (that is, using the BLOCK CONTAINS n CHARACTERS clause in combination with ORGANIZATION IS SEQUENTIAL). Also, you can reduce overlay activity by grouping all sequential file record operations into one overlay. 14-4 OPTIMIZATION 14.3.2 Relative Files For relative files: 1. Select a record format and size that minimizes the empty space remaining in each record position and each bucket. 2. If you create the file by means of the RMS DEFINE utility, select a realistic maximum record number. An attempt to insert a record with a number higher than the maximum will fail. Before inserting such a record, a redefinition and repopulation of the file is required. 3. Group relative file operations into one overlay. reduces task-build time and run time. This 4. Be aware that, before writing a record into a relative file, all buckets up to and including the bucket into which the record insertion will occur must be formatted. Thus, write operations have variable response times, depending on whether preliminary formatting is required, and how much. You might ------ ----- -- ----- ---- -----·----- --------- ---:;,----- ~ n n c::: i rl A r w··r--i--t---i ;n:;o, t- h A h i o h A c::: t- - n nm h A r A rl r A l"' ri r ii F i r c::: t- t- ri Fri r l"' ~ formatting of the entire file only once. 14.3.3 Indexed Files Indexed files have by far the greatest potential for inefficient usage. When using this file organization! be especially attentive to the issue of how well the design and use of the files map into the application. To use indexed files efficiently, you must first understand how they are organized and processed. As the name suggests, an indexed file contains not only a set of data records, but also information to facilitate access to the records. A bucket is an integral number of contiguous 512-byte virtual blocks, and the number of virtual blocks is known as the bucket size. The bucket is the basic retrievable element of an indexed file. Every indexed file must have a primary key: a field in the record that contains a unique value for each individual record. When RMS writes records into the indexed file, it arranges them in collated sequence, according to increasing primary key value, in a series of chained buckets. Thus, you can access the records sequentially by specifying ACCESS SEQUENTIAL. In fact, one advantage of the indexed file is that you can access it either sequentially or randomly. As RMS writes the records, it also constructs and maintains a tree-like structure of key-value and location pointers. Figure 14-1 shows conceptually the overall structure of a primary key index. Each element of the index structure is a bucket. The buckets of the index are structured into a hierarchy of levels. The highest level of the index consists of a single bucket, called the root bucket. The root bucket contains location pointers to buckets at the next lower level. 14-5 OPTIMIZATION _____.... --~ /~ 111 I; ~ I/ Q) I 'ts::I: t H ~ I I Q) ~ I ~ slmo-I ·r-1 lo-I 111 r-1 Q) :> Q) ...:l I Q) Q) ..1c--1: E-1 r-1 I oqo r-1 Q) 1--1 ;:::; ..t..r. i ~ ~:wx:: (.) ::::> M CD N >ww._... .o0I_a-: .... w >.w... I w > >.ww....... Cl ~ _._ .... <( w I> <( w Cl 14-6 OPTIMIZATION Thus RMS scans one bucket at each level of the index for a pointer to a bucket at the next level, until it reaches the bottom level of the index; the bottom level is called the data level. In a primary key index, this level contains the actual data records of the indexed file. The buckets in each level above the data level are called index buckets. RMS also constructs an index for each alternate key that you define for the file. Like the primary index, alternate key indexes are contained in the file. However, alternate key indexes do not contain actual data records at the data level; instead, they contain pointers to data records in the data level of the primary index. For discussion purposes, the successive levels of an index are numbered. The data level of the index is level zero, and the number of levels above level zero is considered the depth of the index. Thus the level number of the root bucket is equal to the depth of the index. Each random· access request begins by comparing a specific key value against the entries in the root bucket, seeking the first entry in the root bucket whose key value is equal to or greater than the access request key. (This search is always successful, because the root bucket=s highest key value is the highest possible value that the key field can contain.) Having located the proper key value, RMS takes the bucket pointer associated with that value and uses it to bring the target bucket on the next lower level into memory. This process is repeated for each level of the index. RMS thus searches one bucket at each level of the index until it reaches a target bucket at the data level. At this point the desired data record location is determined, and a data record can be retrieved or deleted, if present, or written if such writing will not produce a duplicate primary key value. At times there may be insufficient room in a data level bucket to accommodate a new record. When this occurs, RMS includes a new bucket in the chain, moving enough records from the old bucket to preserve the key value sequence while making room to write the new record. This action is known as a bucket split. In summary, each index of an indexed file provides the mechanism for random access to records. Sequential access to records is also possible, because the records themselves (in the primary index) or pointers to the records (in each alternate index) are collated in ascending key value order throughout a series of linked buckets. 14.3.3.1 General Rules for Indexed Files - You can apply the following general rules for indexed files by direct alteration of COBOL source code. 1. While alternate keys are often useful, the more keys you define for an indexed file, the longer each WRITE , REWRITE, or DELETE operation takes. However, multiple keys have little effect on READ timing and provide multiple access paths. Thus, they are most useful for files that are not subject to frequent additions and updates and are accessed in many different programs. 14-7 OPTIMIZATION 2. Select bucket sizes that reflect file activity and provide a suitable depth of index structure. (See Section 14.3.3.3, Index Depth.) 3. Avoid excessive duplication of key values. COBOL does not allow duplicates on the primary key, but permits them on alternate keys. The following subsections deal with the specifics of indexed file design and creation. 14.3.3.2 Bucket Size - Bucket size selection can influence indexed file performance markedly. To RMS, bucket size is expressed as an integral number of virtual blocks, each 512 bytes long. Thus, a bucket size of l specifies a 512-byte bucket, while a bucket size of 2 ·specifies a HJ24-byte bucket, and so on. However, in COBOL you do not express bucket size in exactly those terms. The compiler passes bucket size values to RMS based on what you specify in the BLOCK CONTAINS clause. There, you indicate bucket size in terms of records or characters. If you express BLOCK SIZE in records, the bucket can in some cases contain more records than you specify, but never fewer. For example, assume that your file contains fixed-size 111-byte records, and you call for each bucket to contain five records, as follows: BLOCK CONTAINS 5 RECORDS This might seem to define a bucket as a 512-byte block containing five records of l1i bytes each. However, the compiler adds RMS record and bucket overhead to each bucket for control purposes, as follows: Bucket Overhead 15 bytes per bucket Record Overhead 7 bytes per record (fixed-length) 9 bytes per record (variable-length) Thus, in the example, bucket size is calculated as follows: Bucket Overhead Record Size is iii bytes + 7 bytes Record Overhead for each of 5 records ± Total Record Space is (lJJ 7)*5, or Total Block specified by user 15 bytes 535 bytes 55j bytes Because virtual blocks are 512 bytes long and buckets are always some integral number of virtual blocksr the smallest buffer that the compiler can specify in this case is two virtual blocks (1i24 bytes) , not one. RMS, however, is not keyetl to the BLOCK CONTAINS clause from which this bucket specification was derived, and puts as many records as will fit into each bucket. The bucket actually will contain nine records, not five. 14-8 OPTIMIZATION This ettect may be desirable or undesirable, and no judgement is intended here. Nevertheless, as a COBOL user concerned with file optimization, you should be aware of the mechanism by which COBOL record and file descriptions are used to derive bucket sizes. The CHARACTERS option of the BLOCK CONTAINS clause allows you to specify bucket size more directly. For example: BLOCK CONTAINS 2i4s CHARACTERS This calls for a bucket size of four 512-byte virtual blocks. The number of characters in a bucket is always a multiple of 512. 14.3.3.3 Index Depth - The size of data records, key fields, and buckets in-the file determines the depth of the index. Index depth, in turn, determines the number of disk accesses required to retrieve a particular record. In general, performance is best with an index depth of 3 or 4. A shallower index will require fewer accesses, but will reduce available address space because of the larger buffers required. 14.3.3.4 File Activity - After the initial population of an indexed file, much of its activity is limited to record retrieval. In selecting a bucket size, also consider the likely frequency of random insert and delete operations. When a record is inserted, there must be sufficient room in the bucket to contain it. Otherwise, a bucket split occurs. Bucket splits can cause accumulation of storage overhead, and a consequent reduction of usable space. The new bucket contains records moved from the original bucket to make room for the new record. For each record moved out of the original bucket, seven bytes remain. Therefore, a bucket could accumulate overhead from bucket splits, possibly reducing usable space so much that it can no longer receive record insertions. Record deletions also can accumulate storage overhead. Under most circumstances, however, most of the space that was occupied by the original record becomes available for reuse. When duplicate primary keys are not allowed (as is always true with COBOL file operations), RMS can reclaim all but two bytes of the deleted record space. Several ways of avoiding overhead accumulation are available. First, determine or estimate the frequency with which certain operations will occur. If, for example, you expect only ii~ records of a i~i,~~~ record file to be added or deleted in an average month, your data base is stable enough that you might decide to allow some wasted space from record additions and deletions. 14-9 OPTIMIZATION However, if you expect more frequent additions and deletions, try the following: 1. Choose a bucket size that allows for overhead accumulation, if possible. Avoid bucket sizes that are an exact or near multiple of your record size. 2. To optimize for record insertion performance (as opposed to space optimization), first define the file with a fill number (using the RMS DEFINE utility or a MACRO program)~ A fill number specifies the number of bytes in the buckets of the file that you want to contain record information when the file is populated. Then, populate the file specifying the /LO switch (see Table 14-1 or RMS utilities documentation). Thereafter, the unused space is available for record insertions, with minimum bucket splitting. Make certain that programs that perform such record insertions do not specify the /LO switch. 14.4 OPTIMIZING COMPUTATION You can improve computational efficiency by choosing data types carefully and avoiding coding techniques that produce inefficient object code. For example: 1. Choose USAGE COMPUTATIONAL to maximize efficiency in arithmetic operations. Other data types, in decreasing order of efficiency, are: DISPLAY, COMPUTATIONAL-6, and COMPUTATIONAL-3. 2. Avoid arithmetic operations that use more than one data type. 3. When using COMPUTATIONAL data, minimize the size of the data items; this data type becomes exponentially less efficient as the size of elementary data items increases. 4. Define subscripts as COMPUTATIONAL whenever possible. 5. Indexing is slightly less efficient than subscripting with single-word COMPUTATIONAL data items, but significantly more efficient than using subscripts of any other type. 6. If you can ensure that subscripts are always valid, you can use the switch, /-BOU, to suppress boundary checking. However, you risk unpredictable results if a subscript or index contains an out-of-range value. 7. Avoid COMPUTE statements and expressions with many factors and operators to improve execution time. 8. Avoid COMPUTATIONAL-6 to increase efficiency and compatibility. NOTE COMPUTATIONAL-6 is a temporary data format intended only for program conversion from releases of PDP-11 COBOL prior to Version 4.~. 14-10 OPTIMIZATION 14 .. 5 FILE SPECIFICATION SWITCHES In PDP-11 COBOL, you can identify a file by its file specification in either the Environment Division SELECT statement (using the ASSIGN clause} or the VALUE OF ID clause in the Data Division file-description-entry. These are the only places in a COBOL program where you can refer to a file in terms of its system-specific identification. When you specify a file, you can qualify it with various switches, which are described in Table 14-1. These switches influence the storage and handling of files and are an aid in applying some of the optimization techniques described earlier in this chapter. ISWITCH j /AL:n I I i ! /CL:n Table 14-1 FILE SPECIFICATION SWITCHES MEANING Allocate n disk blocks to the file when it is created. This ensures that n blocks are available before processing begins. The switch can also be used to ensure that the volume can hold the entire file. If the output medium is an RK-type disk, the maximum value of n is 4jjj (decimal}. If n includes a decimal point as its rightmost character, it is considered decimal; if it includes no decimal point, it is considered octal. The blocks allocated need not be contiguous. NOTE The /AL switch is not supported by RSTS/E. Allocate disk space in clusters of n blocks. switch applies only to RSTS/E. This Specify n as a power of 2 in the range 1 to 256 (decimal} , or 1 to 4jj (octal} . If n has no decimal point, it is considered octal. This switch is used only when creating very large files on an output device that can hold the entire file (such as an RP~3 disk}. It speeds file access when the file is being processed sequentially. 14-11 OPTIMIZATION /CO:n /EX:n ! j /LO I /SH Table 14-1 (continued) FILE SPECIFICATION SWITCHES This switch is similar to /AL:n, except that it further I specifies that all blocks be contiguous. I l J Specifies at file creation time an extension quantity of n blocks. A reasonably large extension quantity i minimizes the overhead of dynamic extend operations. Instructs RMS to observe the fill numbers specified at file creation time. If you specify /LO, the buckets of the file will contain free space to allow later record insertions. I Specifies sharing of the file for output or I/O mode, making it available for writing or altering by other tasks running concurrently with the COBOL program. This switch is not allowed for sequential files. For other I types of files, the following rules apply. 1. If the /SH is specified for one task sharing the file, it must be specified for all tasks sharing the file. 2. If a file is being opened for OUTPUT or I/O with the /SH switch specified, all other tasks currently using the file must also have the /SH switch specified. 3. If a file is opened for input without the /SH switch set, no other task can use the file for output or I/O. 4. If a file is opened for input without the /SH switch set, no other task currently using the file can have the /SH switch set. /WI:n If access is denied because one of the above rules has been violated, a file status code of 91 is stored in the FILE-STATUS data-item associated with the file, assuming that the SELECT statement for the file contains a FILE-STATUS clause. (RSX-llM systems only) Allows you to set the number of retrieval pointers in the window used to map virtual block numbers to logical block numbers. The acceptable values are 1 to 1~2 if you know exactly how many pointers are present on disk for the file, or 255, which requests assignment of pointers as needed. If /WI:n is not present, the default is 7. APPENDIX A THE COBOL FORMAT COBOL NOTATION USED IN FORMATS · Underlined upper-case words (key words) - required words; = Upper-case words {not underlined) - optional words; · Lower-case words - generic terms, must be supplied by the user; · Brackets [] - enclosed portion is optional; if several enclosed words are vertically stacked, only one of them may be used; · Braces {} - a selection must be made from the vertical stack of enclosed words; e Ellipsis eee - the position at which repetition may occur; · Comma and semicolon - optional punctuation; · Period - required where shown in the formats. NOTE: Shaded items represent PDP-11 COBOL extensions to the ANS-74 list of COBOL formats. IDENTIFICATION DIVISION. PROGRAM-ID. program-name. [AUTHOR. [comment-entry] ··· ] [INSTALLATION. [comment-entry] ··· ] [DATE-WRITTEN. [comment-entry] ··· ] [DATE-COMPILED. [comment-entry] ··· ] [SECURITY. [comment-entry] ··· ] ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. OBJECT-COMPUTER. PDP-11. PDP-11 [MEMORY SIZE integer { w~s ~ CHARACTERS MODULES [PROGRAM COLLATING SEQUENCE IS alphabet-name] [SEGME~T-LIMIT IS segment-number]. A-1 THE COBOL FORMAT [SPECIAL-NAMES. [CARD-READER IS mnemonic-name-1] [CONSOLE IS mnemonic-name-2] [LINE-PRINTER IS mnemonic-name-3] [PAPER-TAPE-PuNCH IS mnemonic-name-4] [PAPER-TAPE-READER IS mnemonic-name-5] [SWITCH integer-1 ON STATUS IS condition-name-1 { OFF STATUS IS condition-name-2 [Alphabet-name IS { NATIVE STANDARD-1 }] [CURRENCY SIGN IS literal-1] [DECIMAL-~ IS ~ 1·T [INPUT-OUTPUT SECTION. FILE-CONTROL. {file-control-entry} ··· [OFF STATUS ~ condition-name-2]}] [ON STATUS IS condition-name-!] Format 1: SELECT [OPTIONAL] file-name ASSIGN TO literal-1 l RESERVE integer-1 [::SJ] [; ORGANIZATION IS SEQUENTIAL] [; ACCESS MODE IS SEQUENTIAL] [; FILE STATUS IS data-name-1] · Format 2: SELECT file-name ASSIGN TO literal-1 [· RESERVE integer-1 ORGANIZATION IS RELATIVE ~ ACCESS MODE IS SEQUENTIAL { { RANDOM DYNAMIC } [; FILE STATUS IS data-name-2] · }un [, RELATIVE KEY IS data-name-1] RELATIVE KEY IS data-name-1 Format 3: SELECT file-name ASSIGN TO literal-! l RESERVE integer-1 ORGANIZATION IS INDEXED A-2 THE COBOL FORMAT [ ACCESS MODE IS RECORD KEY IS data-name-1 [; ALTERNATE RECORD KEY IS data-name-2 [WITH DUPLICATES]] ··· [; FILE STATUS IS data-name-3] · [I-0-CONTROL. [SAME [RECORD] AREA FOR file-name-1 {file-name-2} ··· ] ··· [MULTIPLE FILE TAPE CONTAINS file-name-3 [POSITION integer-!] [file-name-4 [POSITION integer-2] ··· ] ··· [APPLY PRINT-CONTROL JJ J ··· ON file-name-5 [file-name-6] ··· DATA DIVISION. [FILE SECTION. [FD file-name r 1~ CONTAINS [integer-1 TO] integer-2 L.. [RECORD CONTAINS [integer-3 TO] integer-4 , _______ J .ru:iL:VKl.J::> \l 1 I l CHARACTERSC CHARACTERS] L { RECORD IS Jl LABE RECORDS ARE { STJl..NDA..'R.D } OMITTED lrV:A-L-UE- -OF -ID IS {d~ta-name-l}] literal-1 lft:°ATA {RREECCOORRDDSISARE } data-name-3 rLl!iINAGE IS ln~r~-n~mo-~l {-:---- ··-··- - ~ t integer-5 J LINES ···r ... [data-name-4] rWITH FOOTING AT ~ata-name-6 l1J L integer-6 J [ LINES AT -TO-P {~ata-name-7 }] integer-7 [CODE-SET IS alphabet-name]. [record-description-entry] ··· ] ··· ] [WORKING-STORAGE SECTION. 77-level-description-entry] [ record-description-entry [LINES AT BOTTOM ... ] ~ata-name-8 { integer-8 }]] A-3 THE COBOL FORMAT [LINKAGE SECTION. 77-level-description-entry] [ record-description-entry ··· ] Data description entry: Format 1: data-name-1} level-number { FILLER [REDEFINES data-name-2] [{ ~TURE} IS character=string] COMPUTATIONAL COMP COMPUTATIONAL-6 COMP-6 [~ISl COM?UTATIONAL-3 COMP-3 DISPLAY DISPLAY-6 DISPLAY-7 INDEX [ [~ IS] { ~~~~~G } [SEPARATE CHARACTER] ~ {~~~HRONIZED } JUSTIFIED } {JUST [ ~~~ jJ --RIGHT ----cBLANK WHEN ZERO] ['VALUE IS literal] ---{integer-1 TO integer-2 TIMES DEPENDING ON data-name-3} OCCURS [ i.nteger-2 -TIMES [{ ASCENDING DESCENDING } KEY IS data-name-4 J [data-name-5] ··· [INDEXED BY index-name-1 [index-name-2] ··· ]]. Format 2: 66 data-name-1 RENAMES data-name-2 [I ~:~GH) data-name-3]. Format 3: "" l -AREJ 88 condition-name 1 ~ vALLS W. TS l literal-1 Lrl' =UGH Jl [literal-3 [\~UGH) literal-4]] ··· 1 literal-2J PROCEDURE DIVISION [USING [data-name-1] [,data-name-2] ··· ]. Format 1: [DECLARATIVES. {section-name SECTION [segment-number] · declarative-sentence [paragraph-name .. [sentence] ··· ].'· .. }.... END DECLARATIVES.] {section-name SECTION [segment-number]. [paragraph-name. [sentence] ··· ] ··· }··· Format 2: {paragraph-name. [sentence] ··· }··· A-4 THE COBOL FORMAT STATEMENTS ;::M ACCEPT identifier mn{:?c}-name] ACCEPT identifier - -TIME identifier-!} [identifier-2] ADD {literal-! literal-2 TO identifier-m [ROUNDED] [identifier-n[ROUNDED]] ··· [ON SIZE ERROR imperative-statement] ADD { identifier-l}~ntifier-2-Y----[identifier-3] literal-1 lliteral-2 f literal-3 ··· GIVING identifier-m [ROUNDED] [identifier-n [ROUNDED]] ··· [ON ~ ERROR imperative-statement] ADD CORRESPONDING } { CORR identifier-1 TO identifier-2 [ROUNDED] [ON SIZE ERROR imperative-statement] PJ.TER procedure-na.~e-1 TO [PROCEED TO] procedure-na.~e-2 ----rprocedure-name-3 TO-CPROCEED TO~procedure-name-4] ··· CALL literal-1 --[USING data-name-1 [ ,data-name-2] ··· ] CLOS;E file-name-1 ~r{ :~~ } [ :~~H~~o~~IND]~ -- WITH { NO REWIND } LOCK file-name-2 [ nl :~~) l ~11 WITH -WITH NO REWIND] ~ FOR REMOVAL NO REWIND } ·· · { LOCK COMPUTE identifier-1 [ROUNDED] [identifier-2 [ROUNDED]] ··· = arithmetic-expression [ON SIZE ERROR imperative-statement] DELETE file-name RECORD [INVALID KEY imperative-statement] identifier-1} [identifier-2] DISPLAY { literal-1 literal-2 [UPON mnemonic-name] [WITH NO ADVANCING] DIVIDE identifier-1} { literal-1 INTO identifier-2 [ROUNDED] [identifier-3[ROUNDED]] ··· [ON SIZE ERROR imperative-statement] DIVIDE identifier-1} { literal-l {identifier-2} INTO literal- 2 GIVING identifier-3[ROUNDED] [identifier-4[ROUNDED]] ··· [ON SIZE ERROR imperative-statement] DIVIDE identifier-1} {identifier-2} { literal-l BY literal-2 GIVING identifier-3[ROUNDED] [identifier-4[ROUNDED]] ··· [ON SIZE ERROR imperative-statement] DIVIDE identifier-1} { literal-l {identifier-2} INTO literal- 2 GIVING identifier-3[ROUNDED] REMAINDER identifier-4[0N SIZE ERROR imperative-statement] DIVIDE identifier-!} {identifier-2} { literal-! BY literal-2 GIVING identifier-3[ROUNDED] REMAINDER identifier-4[0N SIZE ERROR imperative-statement] EXIT [PROGRAM] GO TO [procedure-name-!] GO TO procedure-name-1 [procedure-name-2] ··· procedure-name-n DEPENDING ON identifier A-5 THE COBOL FORMAT IF condition statement-1 } { NEXT SENTENCE ELSE statement-2 ] [ ELSE NEXT SENTENCE - I ~ {~~ING INSPECT identifier-1 TALLYING identifier-2 { { } CHARACTERS { i~entifier-4 literal-2 }] ) ··· ) INSPECT identifier-1 REPLACING { ~ING) I{i~entifier-5} i~entifier-7}]) - { CHARACTERS BY ----- - { i~entifier-6} ll.teral-4 [{ BEFORE } AFTER INITIAL { identifier-7 }] literal-5 { FIRST ll.teral-3 BY {identifier-6} [{BEFORE} literal-4 ~ INITIAL { literal-5 ·· ·) INSPECT identifier-1 TALLYING {If ~~ING} -lidentifier-2 FOR CHARACTERS INITIAL i~entifier-4}]} {literal-2 ··· ) REPLACING CHARACTERS BY {~~~::~~~:r-6} [{::~} INITIAL identifier-7 }] {literal-5 I{ ~~ING} i~entifier-5} 11{ ~ literal-3 BY ::~ { i d e n t i f i e r - 6 } literal-4 [ { } INITIAL { i~entifier-7}]) literal-5 ···) MOVE MOVE identifier-!} { literal TO identifier-2 [identifier-3] ··· { ~~~SPONDING} identifier-! TO identifier-2 ·MULTIPLY identifier-!} {literal-1 BY identifier-2[ROUNDED] [identifier-3 [ROUNDED]] ··· [ON SIZE ERROR imperative-statement] identifier-!} MULTIPLY { literal-! BY identifier- 2 } GIVING identifier-3 [ROUNDED] {literal-2 [identifier-4 [ROUNDED]] ··· [ON ~ ERROR imperative-statement] OPEN !INPUT file-name-l[WITH NO REWIND] [file-name-2 [WITH NO REWIND]] ··· } OU'Ti?UT file-name-3[WITH NO REWIND] [file-name-4 [WITH NO REWIND]] ··· I-0 file-name-5 [file-name-6] ··· lEXT°END file-name-7 [file-name-8] ··· PERFORM procedure-name-! [I J =~UGH) procedure-name-2 PERFORM procedure-name-1 PERFORM procedure=na..ue=l PERFORM procedure-name-! [I J ~::~UGH ) procedure-name-2 rJ THROUGH \ Ll THRU I r{ THROUGH} L THRU l procedure=name=2J l procedure-name-2J fi.dentifier-1 }. linteger-1 TIMES TUJn."14'.Lm.TLJT..I "--"-V..U.:U3...:L'..-.....:L-V.-U.--..,L VARYING identifier-2 l { index-name-1 J FROM identifier-31 { index-name-2 ,literal-1 , BY identifier-4} { literal-2 UNTIL condition-1 A-6 THE COBOL FORMAT r l~ BY [~ BY { identifier-5} index-name-3 { identifier-7} literal-4 {identifier-a} index-name-5 { identifier-lo} literal-6 { identifier-6} FROM index-name-4 literal-3 UNTIL condition-2 {identifier-9} FROM index-name-6 literal-5 UNTIL condition-~J READ file-name [NEXT]RECORD[INTO identifier] [AT END imperative-statement] READ file-name RECORD[INTO identifier] [INVALID KEY imperative-statement] READ file-name RECORD[INTO identifier] [;KEY IS data-name] [;INVALID KEY imperative-statement] REWRITE record-name[FROM identifier] [INVALID KEY imperative-statement] r ~EARCH identifier-! lVARYING '~dentifier-2 J\Jl l1ndex-name-l [AT ~ imperative-statement-!] WHEN condition-1 J imperative-statement-2l l ~ SENTENCE I [WHEN condition-2 imperative-statement-3}] { NEXT SENTENCE SEARCH ALL identifier-l[AT ~ imperative-statement-1] {data-name-1 lcondition-name-1 [- data-name-2 { condition-name-2 ( identifier-3 ) } literal-1 larithmetic-expression-1f IS EQUAL TO } { IS = identifier-4 l} { literal-2 arithmetic-express ion-2 imperative-statement-2} { NEXT SENTENCE SET identifier-1 {index-name-1 [identifier-2] ··· } [index-name-2] ··· identifier-3} TO index-name-3 { integer-1 SET index-name-4 [index-name-5] ··· { UP BY } { ~BY ~dentifier-4} integer-2 ~KEY { START file-name ~~=~THAN} IS > - - - - - IS NOT LESS THAN IS NOT < [INVALID KEY imperative-statement] data-namj STOP { ~~eral} ]... A-7 THE COBOL FORMAT STRING identifier-1} {literal-1 ui~~:~!i::r-4 1 identifier-2] [ literal-2 [i~~:~!i:~r-SJ··· DELIMITED BY identifier-3} literal-3 { SIZE { DELIMITED BY identifier-6~ literal-6 SIZE INTO identifier-7 [WITH POINTER identifier-8] [ON OVERFLOW imperative-statement] SUBTRACT { ilditeenrtaifli-elr-1} [ ildi teenrtai fli-e2r - 2 ] FROM identifier-m[ROUNDED] [identifier-n[ROUNDED]] ··· [ON SIZE ERROR imperative-statement] SUBTRACT identifier-1} { literal-1 [identifier-2] literal-2 FROM identifier-m} {literal-m GIVING identifier-n[ROUNDED] [identifier-o[ROUNDED]] ··· [ON SIZE ERROR imperative-statement] SUBTRACT- - { CCOORRRRESPONDING} identifier-1 FROM identifier-2 [ROUNDED] [ON SIZE ERROR imperative-statement] UNSTRING identifier-1 [ DELIMITED BY [ALL] { liditeenrtaifl-ie1r-2} [ OR [ALL] {liidteenratilf-i2er-3}] ···] INTO identifier-4[DELIMITER IN identifier-SJ [COUNT IN identifier-6] [identifier-7 [DELIMITER IN identifier-8] [COUNT IN identifier-9]] ··· [WITH POINTER identifier-10] [TALLYING IN identifier-11] [ON OVERFLOW imperative-statement] -US-E -AF-TE-R STANDARD EXCEPTION } { ERROR PROCEDURE ON ·1 file-narne-1 [file-name-2] ·· INPUT OUTPUT II-0 EXTEND ~record-name[~ identifier-1] Ii;) L ADVANCING {[w~~~]:~!;ier- 2 1 [~~SJ}}~ ~ l I [AT I END-OF-PAGE ) EOP imperative-statementj WRITE record-name [FROM identifier] [INVALID KEY imperative-statement] ,...,....nv ~vv~ .c-r ... l f tlei'xtet-rnaalm-3e \ J I REPLACING L (I literal-1} \ \word-1 J BY l litera1-2 l l \ word-2 J J NOTE: A COPY statement may appear anywhere that a word appears in the COBOL source program. A-8 APPENDIX B LOGICAL UNIT NUMBER (LUN) ASSIGNMENTS LON ASSIGNMENT 1 Console, input 2 Console, output 3 Source input file 4 Source listing output file 5 Object output file 6 ODL output file 7 CREF scratch file 8 COPY library input file 9 Work file 10 work file 11 Intermediate file 12 Sort work file 13 Sort work file 14 Sort work file B-1 APPENDIX C PDP-11 COBOL COMPILER IMPLEMENTATION LIMITATIONS This appendix describes the implementation limitations for the PDP-11 COBOL compiler system (compiler and OTS) . You should not confuse the term "limitation" with "restriction". A restriction is a language facility that is not implemented or should not be used due to known errors in its implementation. An implementation limitation quantifies the limits of a language facility that is supported by the system. Practical implementation limitations exist in every compiler; They result from the finite size of compiler tables, compiler data structure representations, and so on. Since the PDP-11 COBOL compiler employs a vir~ual Memory System to support many compiler data structures, the quantities specified for some implementatiqn limitations are approximations. However, as a general rule, the following guidelines should not be exceeded in the development of a COBOL program. IMPLEMENTATION LIMITATIONS 1. The default depth of dynamic PERFORM statement nesting is l~. The default depth can be modified by using the /PFM switch at compile time. 2. The maximum number of sending operands in a DISPLAY statement is 16. 3. The maximum number of data-name definitions in a COBOL program is approximately 2~~~4. The maximum number of procedure name definitions in a COBOL program is approximately 2~~~5. The maximum nesting depth of matching parentheses in a COBOL expression is l~. 6. The maximum number of qualifiers in a qualified data-name reference is 48. 7. The maximum number of procedure names in a GO TO DEPENDING statement is 16. C-1 APPENDIX D COMPILER GENERATED PSECTS An object program generated by the PDP-11 COBOL compiler is composed of program sections called PSECTs. Three types of PSECTs are generated: · Data Psects Contain the memory for the Data Division of a COBOL program. e Control PSECTS Contain the data that is required Av.im...e., U ;:3.,U......L.. ..l;.l"l"'":':~j -t-"....L.. - V'~ ::j..L... Q-fUt"Ll C - A ...·C-\,- ...U.. "~.'-..:l.- V- Ue by the · Procedural PSECTS Contain the object code generated for the Procedure Division. Data and Control PSECTs are always non-overlayable. Procedural PSECTs, however, can be optionally overlayable or non-overlayable. D.l PSECT NAMING CONVENTIONS The PSECTs generated by the PDP-11 COBOL compiler are named entities. Each PSECT name is composed of a three character pref ix followed by a three character suffix. There are two different forms of the prefix: · $KK Where: $ Is a sentinel character and is always present. KK Is a two character kernel that identifies the PSECT. It is this kernel character that is specified by the /KER:kk switch. The /KER:kk switch is appended to the compiler command line to assign a unique kernel value to the PSECTs generated during the compilation. The default kernel assignment is C$. · $CB Where: $ Is a sentinel character, and is always present. CB Is a two character code that identifies the PSECT as a COBOL compiler generated PSECT. D-1 COMPILER GENERATED PSECTS PSECTs with the pref ix $CB are generated to provide the control and work space required for I/O operations. PSECTs with these same names are generated for each COBOL compilation. They are either overlayed or concatenated at task-build time. Those that are overlayed, have a known fixed length at task-build time. Those that are concatenated, have a known length at compile-time and contribute their size to the total size of the PSECT that is built by the Task Builder. The three character suffix identifies the type of code or data the PSECT contains. Table D-1 describes the suffixes assigned to $KK type PSECTs, and Table D-2 describes the suffixes assigned to $CB type PSECTs. r I Type Table D-1 $KK PSECT Name Suffixes Suffix Content Data Control i i ! I DAT ODD ARG LIT LTD !OB I I WRK I I PDT SDT LST PFM ADT Data Division data storage areas. Data Division directories - contains descriptions of referenced Data Division items. Directories of referenced Linkage Section items. Literal Pool - contains all of the literals I referenced in the program. Literal Directory. Input/Output buffers. COBOL compile unit work space - contains a description of the compile unit environment. PSECT dispatch table - used for intra-p rog ram control of segmented COBOL programs. Subprogram dispatch table used for inter-program control (i.e., calling subprograms). Argument list work space - used to contain the argument list passed to the called subprogram. Perform work space used to provide control and checking of nested PERFORM state·ments. ALTER Dispatch Table - used to contain the destination of alterable GO TO statements. D-2 COMPILER GENERATED PSECTS Table D-1 (Cont.) $KK PSECT Name Suffixes Type Su ff ix Content USE Procedural ENT nnn Default USE procedure table - used to I I access the default OPEN mode (INPUT, OUTPUT, I-0, or EXTEND) USE procedures, if I I present. Code generated by the compiler for the program entry point. Numbered suffixes beginning with 001. These numbered PSECTs contain the object code generated for the Procedure Division of a COBOL program. Table D-2 PSECT Name Suffixes Allocation Suffix Content OVR IOT OVR FAl OVR XAl OVR SW~ CON I Fl CON !RI CON KDl CON BDl Input/Output Table - contains a reference to each COBOL Input/Output OTS routine required by the COBOL compilation. File Access Block (FAB) - used to transmit information to RMS at open and close time. Auxiliary Access Blocks (XABs) used to transmit information on the keys for indexed files to RMS at open time. COBOL switches flag PSECT. Indicates whether COBOL switches are referenced in the COBOL program. Internal File Access Blocks (IFABs) - used internally by RMS to store information. Internal Record Access Blocks (IRABs) used internally by RMS to store information. Internal Key Descriptors - used internally by RMS to store information on the keys for indexed files. Buff~r Descriptor Blocks (BDBs) used internally by RMS to store information on the buffers. D-3 COMPILER GENERATED PSECTS Table D-2 (Cont.) PSECT Names Suffixes Allocation Suffix Content CON KBl CON FDl Key Buffers - used internally by RMS to store keys for indexed files. FDA Index Vector - contains address of first FDA in program. Note: OVR indicates overlayable PSECT. CON indicates concatenatable PSECT. D-4 APPENDIX E SORTING FILES IN A COBOL PROGRAM Files prepared for or.by COBOL programs may be sorted using the SORT utility, which is discussed in the PDP-11 SORT Reference Manual. A major portion of that facility is available to the COBOL programmer through usage of a set of subroutine linkages, described in detail in this chapter. All such linkages involve use of a CALL statement with an appropriate parameter list. E.l CALL STATEMENTS REQUIRED A set of five CALL statements, each calling a particular SORT subroutine, is required within a COBOL program in order to produce a sorted output file. Each of these subroutines (RSORT, RELES, MERGE, RETRN, ENDS) performs a specialized function in the SORT procedural sequence and lets the COBOL programmer both specify sorting parameters and perform special operations on individual records as they pass through the initial and final phases. E.1.1 Initializing the SORT - CALL RSORT The following statement is needed to initialize the sorting operation: CALL "RSORT" USING IERROR, KEYSIZ, MAXREC, KEYLOC, SRTBUF, BUFSIZ, SCRNUM. Parameter usage is as follows: IERROR - location in which a SORT subroutine may place a non-zero error code, if necessary, in COMP form, value less than 100. KEYSIZ - location containing byte count of total key size in COMP form, a positive even integer. MAXREC - location containing byte count of maximum data record size in COMP form, a positive even integer. The sum of KEYSIZ and MAXREC cannot exceed 16,383 (decimal) . KEYLOC - address of most major word in key. See Section E.2 for details on setting up sort key. SRTBUF - address of first word in sort work area. BUFSIZ - location containing byte count of sort work area size in COMP form. E-1 SCRNUM - SORTING FILES IN A COBOL PROGRAM location containing number of scratch files available to the SORT (not less than 3, not more than 8), in COMP form. E.1.2 Passing a Record to the Sort - CALL RELES The following statement is needed to pass a record to the sort: CALL "RELES" USING RECS I Z, INREC. Parameter usage is as follows: IERROR - usage is as described above. RECSIZ - location containing byte count of data record size in COMP form, a positive even integer not greater than value in MAXREC. INREC - address of record to be passed to the sort. E.1.3 Merging the Scratch Files - CALL MERGE The following statement is needed to merge the scratch files in the sort after all input records have been passed to the sort: CALL "MERGE" USING IERROR. IERROR usage is as described above. E.1.4 Requesting an OUTPUT Record - CALL RETRN The following statement is needed to request the output records, one at a time, produced in sorted order by the sort: CALL "RETRN" USING !ERROR, RECSIZ, OUTREC. Parameter usage is as follows: IERROR - usage is as described above. RECSIZ - location to receive byte count of returned data record size in COMP form, a positive even integer not greater than value in MAXREC. OUTREC - address of area to receive returned data record. NOTE RETRN indicates "no more records" by placing a negat,ive value in IERROR. E-2 SORTING FILES IN A COBOL PROGRAM E.1.5 Terminating the Sort - CALL ENDS The following statement is needed to terminate the sort after all sorted output records have been returned: CALL "ENDS" USING IERROR. IERROR usage is as described above. E.2 SETTING UP THE KEY Before CALL RELES is executed, the COBOL programmer must first set up the key in an area outside the record itself. Since the key area must begin and end on a word boundary, usage of an 01 level description in the Working - Storage Section is recommended. The most major byte for the key, that byte "on the left", must be stored in the highest memory location of the key area, and the most minor byte, that byte "on the right", must be stored in the lowest memory location. Thus the data must be moved byte by byte, NOT word by word, to the key area, resulting in the key being stored "backwards" by bytes. If the actual key contains an odd number of bytes, the last unused position must be zeroed out, to insure proper results from word compares. Thus for a key of 7 bytes, KEYSIZ - 8; the contents of the lowest byte address should always be zero. The form of the comparison is logical, i.e., all eight bits of a byte are significant; there is no implied sign. The programmer is responsible for organizing the key data passed to the sort in a form which ensures the correct sequence. E.3 WORK AREA SIZE The size of the sort work area, BUFSIZ, must be at least as large as the result of the following calculation: Minimum BUFSIZE = SCRNUM * (1110 + MAXREC + KEYSIZE) If less space is provided, the sort will keep decreasing the number of work files until either the above equation is satisfied or the number of files drop below three; the latter is an error condition (error code 17). Any extra memory will be used to expand the in-core sort area. Thus, in general, the more space supplied, the faster the sort. E.4 TYPICAL USAGE SEQUENCE Sort the file SORT-IN to produce the file SORT-OUT. 1. Open SORT-IN. 2. Call RSORT to initialize the sort. 3. Read the next logical record from SORT-IN. go to step 7. If no more data, ~-3 SORTING FILES IN A COBOL PROGRAM 4. Perform any desired operations upon the input record. If it is not to be submitted to the sort, go to step 3. 5. Set up the keys from the new record. 6. Call RELES to give the record to the sort, then loop back to step 3. 7. Close SORT-IN. 8. Call MERGE to collate the records the 9. Open SORT-OUT. 10. Call RETRN to get the next sorted output record. If no more records, go to step 13. 11. Perform any desired operations upon the sorted output record. If it is not to be included in the SORT-OUT file, go to step 10. 12. Write the record onto SORT-OUT, then loop back to step 10. 13. Close SORT-OUT. 14. Call ENDS to clean up the sort scratch files. E. 5 LINKING SORT ROD.TINES WITH A COBOL PROGRAM The actual sorting subroutines are contained in SORTS.OBJ and SIORMS.OBJ which are included in the COBOL object library (COBLIB). The programmer can link these to his own calling program, by following the usual procedure for using the Task Builder to task-build any COBOL program. Note that the sort subroutines use LUNs 5, 6, ... 12 for the scratch files. Use the task builder device assignment (ASG) command appropriately. The LUN can be overridden by globally patching location $RFIRL. Insure that the LUNs used by the sort subroutines do not conflict with the LUNs assigned to files in the COBOL program that might be open when the sort subroutines are called. E.6 COMPARISON WITH ANS COBOL SORT VERB Readers familiar with the ANS COBOL SORT verb will recognize that a substantial portion of that capability has been described in this chapter. The following points of comparison will be helpful in converting from such usage to the described facility: 1. INPUT PROCEDURES are available thru the CALL RELES usage. 2. OUTPUT PROCEDURES are available thru the CALL RETRN usage. 3. Only ASCENDING keys are supported. The programmer can get the effect of DESCENDING key fields by simply complementing them when he stores them in KEYLOC. Note that the data record itself is unaffected by this procedure, so restoration of such fields after the sort is unnecessary. E-4 SORTING FILES IN A COBOL PROGRAM 4. The COLLATING-SEQUENCE option is not directly available. Again, however, the programmer could transform key fields when storing them in KEYLOC to achieve the desired effect. 5. There is no MERGE feature. 6. Multiple usages of the sort may occur within a given COBOL program provided that "RSORT" and "END" bracket each usage. 7. There is no restriction on the presence of COBOL code in addition to INPUT and OUTPUT PROCEDURES. E.7 ERROR CODES Whenever the sort detects an error, it returns a non-zero code to the location specified by the programmer (!ERROR in discussion above). The error codes (octal representation) and their meanings are: DEC OCTAL 00 No errors 01 Device input error 02 Device output error 03 OPEN INPUT failure 04 OPEN OUTPUT failure 05 Size of current record is greater than maximum size 06 Not enough work area 07 "RETRN" was called after it had exited with a negative error code (end of sort). 8 10 SORT routine called out of order. The order of the calls must be RSORT, RELES, MERGE, RETRN, ENDS. 9 11 Sort already in progress. To do a second sort, ENDS must be called to clean up the first sort. 10 12 Key size is not positive, SORTS detected a zero or negative key size in its calling parameter. 11 13 Record size not positive. 12 14 Key address not even. The keys must start at an even address (SORT uses word moves) . 13 15 Record address not even. E-5 SORTING FILES IN A COBOL PROGRAM DEC OCTAL 14 16 Scratch records will be too large. The size of the keys plus the size of the largest record must be less than 377776 (octal). 15 17 Too few scratch files. A m1n1mum of 3 scratch files must be specified. 1 &:. .1.V 20 Too many scratch files. A maximum of 10 scratch files may be specified. 17 21 End-of-string record was detected where none was expected. 18 22 Like 21, but for End-of-File. 19 23 SORT found a record larger than it expected. 20 24 Record length is non-standard for SORTT, SORTA, SORT I. [COMP items are displayed in DECIMAL!] E-6 APPENDIX F RSTS/E TERMINAL HANDLING SERVICES The PDP-11 COBOL runtime library contains a set of callable subroutines that support multi-terminal access from a single COBOL program. These subroutines run only on RSTS/E. The purpose of this subroutine package is to provide asynchronous terminal I/O support for COBOL programs running on RSTS/E. F.l GENERAL SERVICES The subroutines provide the following services: 1. The ability to assign and deassign available terminal f keyboards} to the running COBOL program. 2. The ability to OPEN or CLOSE a specific I/O channel and logical unit pair for terminal input/output. 3. The ability to WRITE a message to any single terminal assigned to the program. 4. The ability to READ a message from a specific terminal. 5. The ability to READ a message from any terminal in the group assigned to the program and have the subroutine identify the terminal from which the message came. This technique is known as polling. 6. In conjunction with the unsolicited READ capabilities, ability to specify how long to wait for a message from any terminal before returning to the user program. F-1 RSTS/E TERMINAL HANDLING SERVICES F.1.1 Open ~ Logical Unit for Terminal I/O This function must be called to initialize the multi-terminal subroutines to expect terminal I/O on a specified logical unit fLUN). Subsequent terminal I/O subroutines require the LON to function properly. The form of the CALL is: CALL "KBOPEN" USING ERR, LON Where: ERR - is a binary data item [PIC 9(4) COMP] that contains the returned error status code. fSee Section F.2.) LON - a binary data item [PIC 9f4) COMP] that contains the logical unit number to use. Example MOVE 14 TO LON. CALL "KBOPEN" USING ERR, LON. An error code of zero indicates a successful call. The choice of LON number is very important and must comply with the following rules: 1. It must be in the range of-~ to 15. 2. It must not conflict with a LON number assigned by the COBOL compiler to a file in the COBOL program. F.1.2 Close ~Terminal Logical Unit This function disassociates a LON and all keyboards assigned to it from the running COBOL program. The form of the CALL is: CALL "KBCLOS" USING ERR, LON Where: ERR and LON are as specified in KBOPEN F.1.3 Assign~ Terminal In order to use the RSTS/E COBOL multi-terminal functions, each terminal must be assigned to the COBOL program. A CALL is made to the subroutine KBASGN to assign a specific terminal or keyboard (KB) to a logical unit fLUN). This LON must have been the subject of a previously executed CALL to KBOPEN in the COBOL program. F=2 RSTS/E TERMINAL HANDLING SERVICES The form of the CALL is: CALL "KBASGN" USING ERR, KB-UNIT Where: ERR - A 2-byte binary data item [PIC 9(4) COMP] that contains an error code returned by the subroutine (see Section F. 2) · KB-UNIT - A 2-byte binary data item [PIC 9f4) COMP] that contains the keyboard number. F.1.4 Deassign~ Terminal This function removes the specified terminal unit from the list assigned to the specified LON. The form of the CALL is: CALL "KBDEAS" USING ERR, KB-UNIT Where: ERR AND KB-UNIT are as specified for the call to KBASGN. Section F .1. 3.) (See F.1.5 Write to~ Specific Terminal Assuming that the specified terminal has been assigned, this function delivers a message to it. The form of the CALL is: CALL "KBWRIT" USING ERR, COUNT, MESSAGE, LON, KB-UNIT Where: ERR - the 2-byte binary data item as specified earlier. COUNT - a 2-byte binary data item [PIC 9f4) COMP] that contains the length of the message in bytes. MESSAGE - the data item that contains the message to be written. This message must contain all vertical and horizontal formatting characters such as carriage returns, line feeds and tabs. LON - a 2-byte binary item [PIC 9(4) COMP] as previously specified. KB-UNIT - a 2-byte binary data item [PIC 9(4) COMP] identifying the specific terminal to which the message is written ·· F-3 RSTS/E TERMINAL HANDLING SERVICES F.1.6 Read from~ Specific Terminal This function allows a COBOL program to read a message from a specific terminal. If a terminal operator types CONTROL-Z at a terminal, error code 11 (end-of-file on device) is returned. The form of the CALL is: CALL "KBREAD" USING ERR, COUNT, MESSAGE, LON, KB-UNIT Where: ERR is the 2-byte binary data item into which a success/error code will be returned. COUNT - is the 2-byte binary data item which contains the length of the message just read. Before execution of the CALL, this data item must contain the maximum record length. MESSAGE - defines the data item into which the message is read. This data item should be long enough to contain the longest anticipated message to be read. When a message is read from a terminal, the message is prefixed by a 1-byte field which contains the terminal unit number in binary. Therefore, reserve space in the message input data item for this byte. i . e. , ~l MESSAGE ~2 KB-NUM PIC X. ~2 REAL-MESSAGE PIC X(8~) All messages are returned as ASCII strings with no conversions taking place. LON - a 2-byte binary data item containing the LON number. KB-UNIT - a 2-byte binary data item containing the terminal number to be used in the READ. F.1.7 Read Unsolicited from any Terminal Assigned This function allows a COBOL program to read a message from any terminal assigned to the program. The read is called unsolicited because no specific terminal is identified. The program reads a message from the first terminal found to have typed in a message. This function can also wait for input from a terminal for a specified length of time = up to 255 seconds. If no message is available from any assigned terminal within this time, then an error condition is returned. The error code is 13 a user data error on device condition that is generated by the RSTS/E monitor. Using this function, the COBOL program can effectively poll a group of terminals, requesting input. F-4 RSTS/E TERMINAL HANDLING SERVICES The form of this CALL is: CALL "KBREAU" USING ERR, COUNT, MESSAGE, LON, KB-UNIT TIME Where: ERR, COUNT, MESSAGE, and LUN are as specified in the description of KBREAD fSee Section F.1.6.), and KB-UNIT is a 2-byte binary data item that contains (upon return from the call to KBREAD) the unit number (in binary) of the terminal from which the current message was read. TIME - is a 2-byte binary data item containing a value from 1 to 255 which is the amount of time in seconds to wait for input from the terminal(s). If no message is available in this time, an error 13 (user data error on device) is returned. If TIME is given a zero value, then the svstem will wait indefinitely for input from the terminal(s). F.2 ERROR CODES DURING MULTI-TERMINAL HANDLING These values are returned in binary in the 2-byte data item used in every call to the multi-terminal subroutines. CODE MEANING Successful. 6 NOT A VALID DEVICE. An attempt was made to write to an unassigned device with KBWRIT. 7 I/O CHANNEL ALREADY OPEN. A KBOPEN call attempted to use a LUN that was already in use by the program for a file or for other terminal operations because of a previous KBOPEN call. 8 DEVICE NOT AVAILABLE. A KBASGN call was made to assign a terminal that is unavailable to the program and is reserved by another user. 9 I/O CHANNEL NOT OPEN. A call to KBASGN, KBREAD, KBREAU or KBWRIT was made using a LUN that was not opened by a KBOPEN call. 11 END OF FILE ON DEVICE. A user at an assigned terminal typed CONTROL/Z during a KBREAD call. 12 FATAL SYSTEM I/0 FAILURE. A system level I/O error occurred the user has no guarantee that the last operation was performed. F-5 RSTS/E TERMINAL HANDLING SERVICES 13 USER DATA ERROR ON DEVICE. Bad data may have been transmitted during the previous I/O call or a call to KBREAD or KBREAU did not get any data in the requested wait time. 15 KEYBOARD WAIT EXHAUSTED. The wait time requested for input during a KBREAU call has passed with no input. 31 ILLEGAL BYTE COUNT FOR I/O. A bad message length value was used as a parameter during a KBWRIT call. F-6 APPENDIX G SOURCE PROGRAM LISTINGS This appendix contains compiler listings for two COBOL programs. The first, STATB, calls three subprograms; the second, DOCATS, is one of the subprograms. The examples demonstrate some of the features of PDP-11 COBOL, such as: e The COPY statement e The COPY REPLACING statement · The CALL statement · The results of using the /MAP and /OBJ compiler switches · PSECT names resulting from the /KER compiler switch The circled numbers on the source listings indicate features that are annotated in the text. Source Listing Features @- The version of the PDP-11 COBOL compiler. 0- The source file, including file type, or extension, and version number (for RSX-llM and IAS). 0- Date and time when the compilation began. 0- The compiler command line. The contents of the command line can help to explain why the listing looks like it does and how the program runs. For example, this command line shows that the /KER:ST switch was used; it explains why PSECT names contain the characters "ST". ®- The IDENTification number assigned by the compiler. This number identifies the specific compilation of the program and is used in OTS error message displays. 0- Source line number assigned by the compiler. This number is used in OTS error message displays to indicate the location at which the error was detected. It also appears in error message displays that show nested PERFORMS. G-1 SOURCE PROGRAM LISTINGS G- Sequence number. If the source file used conventional format, the sequence field (positions 1-6) appears here. @- Source text. This area contains the text that was processed by the compiler. If a line of text was too long, only the part that appears here was processed. The compiler also prints a diagnostic message when it truncates a line of source text. G- Identification field. If the source file used conventional format, this area contains the identification field (positions 73-8~J). @- Identifies a source line that: a) contains a COPY statement, or b} was copied from a library file. @ - COBOL Verb (appears only when /OBJ switch is used). Identifies the COBOL verb that is referred to by the other entries on the line. @- Segment number (/OBJ switch only). Identifies the program segment, or PSECT. Notice that this is not the PSECT name; it is a consecutive number assigned to all procedural PSECTS during compilation and duplicates the segment numbers in other programs. @ - Offset (/OBJ switch only). Specifies the octal offset (distance) from the beginning of the segment for the object code generated by the COBOL verb (number 11) . @- Compiler diagnostic severity code. Describes the seriousness of the compiler diagnostic. This diagnostic is "informational", which means that it probably does not indicate a serious condition. @- Diagnostic source line number. Identifies the source line to which the diagnostic applies. In this case, OPTIONS-AREA is defined as larger than CUSTOMER-FILE-ID; therefore, truncation occurs. @- Compiler diagnostic number. Use this number to find Appendix H. Identifies the specific diagnostic. a description of the diagnostic in @- Diagnostic message. A one-line description of the condition. ,--...., ~ - FILE-TO-LON ASSIGNMENT TABLE. This table appears for any program that contains file descriptions. @- File-name. The name that is used in the program to refer to the file. @- Source line. The file-description-entry appears on this source iine. ~ ~ - Relative LON. Identifies the file by relative Logical Unit Number. This number can duplicate relative LUNs in other programs in the run unit, because actual LUNs are assigned by the Task Builder. G-2 SOURCE PROGRAM LISTINGS ~ ~ - Data Map. Describes the data-names and file-names used in ~ne program. This section appears only if the /MAP switch is used. @- Level. Contains the level-indicator or level-number of the item. An L preceding the level indicates that the data-name is a Linkage Section item. @- Name. The file-name or data-name. @- Source line. The file-name or data-name is defined on this source line in the Data Division. @-Data Division location. Identifies the octal offset of the file or data-name from the beginning of data PSECT $kkDAT (kk=ke-rnel). For Linkage Section data-names, the offset is from the ii-level. @- Directory location. Identifies the octal offset of the data item's descriptor. For Linkage Section data items, the offset is from data PSECT $kkARG (kk=kernel); for other data items, the offset is from data PSECT $kkDDD. The OTS uses the descriptor to operate on a data item. A directory location that contains asterisKs indicates ~nat the compiler did not generate a descriptor because the data-name was not used in the Procedure Division. @- USAGE. Corresponds to the USAGE clause or implicit usage of the data item description. The following abbreviations are used: DISP CMP CMP3 CMP6 INDX DISPLAY COMPUTATIONAL COMPUTATIONAL-3 COMPUTATIONAL-.6 INDEX @> - Class. Identifies the COBOL class of the data item. The compiler determines class from the PICTURE or level associated with the data-name. The following abbreviations are used: ALPHA NUM AN ANEDIT NMEDIT Alphabetic Numeric Alphanumeric Alphanumeric Edited Numeric Edited @- Occurrence level. Indicates the number of subscripts necessary to refer to the data-name. @ - Length. Specifies the length of the data item in decimal bytes. @ - Procedure Name Map. Describes the procedure-names that appear in the program. This section appears only if the /MAP switch is used. @- Procedure-name. This is the name as it appears in the Procedure Division. @- Source line. Identifies the source line in which the procedure-name is defined. G-3 SOURCE PROGRAM LISTINGS @- PSECT. Identifies the name of the executable code PSECT (program section) in which the procedure-name appears. @ - Offset. Specifies the octal offset (distance) of the location of the procedure-name from the beginning of the PSECT. @- Segment-number. Corresponds to the segment-number in the header for the section in which the procedure-name appears. @ - ·section. An "S" indicates that the procedure-name is a section-name. @- Paragraph. A "P" indicates that the procedure-name is a paragraph-name. @- Segmentation Map. Describes the segmentation for each Procedure Division section. This map appears only when the /MAP switch is used. @- Section Name. The name of the section as it Procedure Division. @- Segment-number. The segment-number specified header or the implied segment-number JJ. appears in the in the section @- PSECT Name. Indicates the name of the procedural PSECT generated for the section. If the generated code exceeds the code segment limit, the compiler generates additional PSECTs; their names are displayed beneath the first. The code segment limit can be changed by using the /CSEG switch. @- The size of the procedural PSECT in octal bytes. @- The size of the procedural PSECT in decimal words. @- Compiler-Generated PSECTs. Describes the procedural PSECT's generated by the compiler to provide run-time execution initialization. @- PSECT Name. @- The size of the PSECT in octal bytes. @- The size of the PSECT in decimal words. @- Referenced OTS Routines. Lists the names of all COBOL OTS routines that are referenced by the compiler-generated code. @- Data PSECT Map. Lists the nonexecutable PSECTs generated by the compiler. Appendix D describes the data PSECTs generated for each compilation. @ - PSECT Name. @ - The size of the PSECT in octal bytes. G-4 SOURCE PROGRAM LISTINGS ~ - The size of the PSECT in decimal words. @- External Subprogram References. Lists the names of all subprograms referenced by CALL statements in the program. @ - Error Severity Code. Describes the seriousness of errors. Chapter 12 describes the severity codes and their meanings. @- Error Count. The number of errors detected in the compilation for each severity level. @- Compiler-generated ODL File. Lists the contents of the ODL file generated for this compilation. G-5 SOURCE PROGRAM LISTINGS JD A COBOL SRC 1STATB,CBL: I.I 05·0CT·78 00:41115 PAGE 001 CMD1STATB1STATBaSTATB/~AP/ORJ/KE~;ST----(4'i <fJ <?- I .. IDENT: 2780bb ~ ~ ~ 00001 IDENTIFICATION DIVISION, ~ \ 001:h~2 01d.,,03 l.Hl001.1 ldi!ill~S 0iil00b J0'307 00008 IM2'00q 000113 00011 ;!11?012 PROGilllH·lD, STATB, INSTALLATION, DATE·,.RITTEtlf, JONES M4IL ORDER COMPANY, s OCT 1·ne. DATE·COMPILED, 0~·0CT·78 · ~EM11RKS, U1in9 celled orogram11 thi· progrem d1mon1tr1t·1 the effects and 1dv1nta;11 of moduler Program develooment, Deoendfng on operator·aoecified ootion1 and the content· of data r·cord1, th· orogr1~ 9ener1te1 v1riou1 output1, 00.,,13 0011114 T~e called Programs ares 00015 ;:!~01b NAME FUNCTION 00017 00018 0001q 0002() EXCE"T DOC ATS CREDLM Generates an exception report, Generates mailing labels, Generates 'credit 1fmft· letters, 00021 00"'22 ENVIRO~MENT DIVISION, 00023 00021.1 1<101:125 1!!002b 00027 00028 0002q CONFIGURATION SECTION, SOURCE·COHPUTE~. POP·11. OSJECT·COMPUfE~. PDP·11 SEGMENT·LIMIT IS 25, INPUT·OUTPuT SECTION, FILE·CONTROL, 00030 00031 00032 00033 01103'1 1'10035 00031:1 0011137 SELECT CUSTOMER·FILE ASSIGN TO "SYICUSTOM,DAT· ORGANIZ4Tl0~ IS INDEXED ACCESS MOOE IS DYNAMIC RtCORD KEY IS CUST·CUST·NUMBER AL.TER~ATE RECORD KEY IS CUST·CUSTOHER·NA~E FILE STATUS IS CUSTOMER·FILE·STATUS, 00038 01:'!0H r.Hl0!'10 00iil1.11 SELECT STATEMENT·REPORT ASSIGN TO "SY1STATEM,REP" FILE STATUS IS STATEMENT·REPORT·STATUS, 00042 0001.13 DATA OIVISIOt~, ~00lll.I 0011)45 FILE SECTION, 00iililb 00.:llJ7 0001J8 000aq FD CUSTOMER·FILE LABEL RECORDS ARE STANDARD VALUE OF ID IS CUSTOMER·FILE·IDo 0ill05<l 00051 00\!!S.? L 00053 COPY "CUSTRC,CPY" ~EPLAC!N~ cvsr-ow~-AMT av cusT-CURRENT·BALANCE1 CUST·80UGHT BY CUST·PURCHASES·YTO, L 01'105'1 L 00055 L 00050 L 00057 L i1l!i!058 L ill<l059 L 0"101:10 L 00ilb1 L 01il0b2 L 0001:13 I. 01:ii!bll L 0iil0oS L 00vH1b I. 00007 L <!0;!1.18 L 01d0o9 L 01'.1070 L 00071 L 00072 L 00073 L 01'1074 L iHliil75 ?1 CUSTO~ER·FILE·RECORD, 03 CUST·CUST·NUMBER PIC XC&), 03 CUST·CUSTOMER·NAME PIC XC3il), 03 CUST·AOORESS·LINE·1 PIC XC30), 03 CUST·4DDRESS·LINE·2 PIC X(30), 03 CUST·AOORE55·LINE·3 PIC X( 3il) · 03 CUST·ADDRESS·ZIP·CODE PIC X(5), l3 CUST·PHO~E. ~S CUSi·PHONE·4REA·COOE PIC ~C3l, 05 CUST·PHONE·EXCHANGE PIC X(3) · 05 CUST·PHONE·LAST·~ PIC 9(Q), CUSi·PHONE·NUHSER REDEFINES CUST·PHONE PIC ~c11n. liJ3 CUST·ATTENTION·LINE PIC XC20), 03 CUST·CREDIT·LIHIT PIC 9(10)V99, 03 CUST·MEADER·DATA REDEFINES CUST·CREDIT·LlMIT, 05 FILLER PIC X(&), ~5 NEXT·ACCT·NUMBER PIC 9(&), CUST·CURRENT·BALANCE PIC G-6 SOURCE PROGRAM LISTINGS L. 00071:1 L. 011l077 I. 00078 L. 00079 L. 00080 00081 00082 00083 001!!84 00085 0008b 00087 il0088 00089 0009ill 00091 00092 00093 00091.1 00095 0009b 00097 00098 00099 00100 00101 00102 '1Clj,t:.1~ 001P.4 01i'1 ~5 00106 00107 1'!01!1!8 00109 00110 00111 icl0112 00113 0011'1 00115 0011b 00117 00118 00119 00120 00121 00122 00123 01!1124 00125 0012b 00127 00128 0M29 00130 00131 00132 00133 00134 00135 00130 00137 00138 00139 0011.10 001111 00142 00143 0011111 00145 0014b 0011.17 001118 0011.19 00150 00151 00152 00153 00151.1 00155 0015b 00157 00158 00159 001b0 00lb1 00lb2 001b3 001bll 03 CUST·PURC~ASES·YTD PIC 9( U)V99. 03 CUST·NEXT·ORDER·SEQUENCE PIC 9(11). 03 CuST·NEXT·PAYMENT·SEQUENCE PIC 9(11). FD STATEMENT·~EPORT L.ABEL. RECORDS ARE STANDARD. 01 STATEMENT·REPORT·RECORD, 03 F IL.L.ER PIC XCS), 03 AOORE.SS·WINDO~ PIC X(.50) · 03 F IL.L.ER PIC x c1). 03 ADDRESS·ZIP PIC X(5), i:l3 F IL.L.E.R PIC XC25l, 03 FORM·NAMEe 05 F IL.L.ER PIC X(b), 05 FORM·DATE PIC X(8), 01 S·R·R·2, 03 FIL.L.ER 03 REPORT·CREDIT 03 F IL.L.ER 03 REPORT·YTD PIC xc 15l. PIC z,zzz,zzz,zzq.99, PIC XCUle PIC z,zzz,zzz,zzq,99, 01 S·~·R·3 0 03 5 TA TEMENT·OATE 03 FIL.L.ER 03 STATEMENT·CA~T!ON "'" ST~iEMfNi·8~~~NCf wOR~!NG·STURAGE SECTION, PIC xc12>. PIC )(( 10). PIC r .,. ~!~~~:zzz.zz~.~~. 01 CUSTOMER·FIL.E·STATUS !1!! STATEMENT·REPORT·STATUS 01 CUSTOMER~FIL.E·ID VAL.UE "SY1CUSTOM,OAT", 01 TOOAYS·DATE 01 TOR REDEFINES TODAYS·DATE. IH TODAY·YEAR 03 TODAY·MONTH 03 TOOAY·DAY 01 TODAYS·REPORT·DATE, 03 TODAY·MONTH 03 FIL.I.ER i'l3 TODAY·OAY 03 FIL.I.ER >l3 TODAY·YEAR 01 STANOARO·MESSA~E 01 DISP·"IESSAGE, 03 F IL.L.ER 03 DISP·NUM PIC xc2>. PIC XC2) 0 PIC x ( 14) PIC 9(b). PIC 9(2). PIC 9(2). PIC 9(2). PIC Z9, PIC X( 1) VALUE .. , i. PIC PIC 9(2). X(1) \IALUE ·1·. PIC 9(2). PIC XC51il) VAL.UE SPACES, PIC XC3flll VAL.UE SPACES, PIC ZC5l, 01 YTD·CATALOG·MINIMUM PIC 9(11)) VAL.UE U0011', 01 EXCEPTION·INDICATORS, 03 EXCEPTlON·!NOICATOR OCCURS 10 PIC 9( 1). 01 OPTIONS·AREA, "13 OPTIONS·AREA·CHAR OCCURS 30 PIC x c1). 01 A·COUNT PIC 9(2). 01 OPTION·STORAGE, 03 QPlION·ENTRY OCCURS 8 PIC 9( 1). 01 OPTION·VALUES REDEFINES OPTION·STORAGE. 03 FIL.I.ER PIC 9(1), 88 ilANT·STATEMENTS VAL.UE THRU 9. 03 FIL.LEI< PIC 9( 1l. 88 ""lNT·INVO!CES \IAL.UE THRU 9. 03 FIL.L.ER PIC 9(1). 88 ~ANT·4L.L.·CATAL.OGS 03 FIL.I.ER VAL.UE THRU PIC 9. 9( o. 88 ~ANT·SOME·CATAL.OGS VAL.UE T"1RU 9. 03 fIL.LER PIC 9(1), 88 1"'ANT·CREDIT·L.IMIT·L.ETTERS VAL.LIE 1 THRU 9 1 0:) FILL.ER PIC X(3) · 01 i<!ECCiRD·COU!',l IC1 STo\ TEMENT ·COUNT 01 INVOICE·COUNT i;.1 CREOIT·LIMIT·COUNT 01 CATAL.DG·COUNT PIC PIC PIC ""·· 9(5) VAL.UE 9(5) VAL.UE 9(5) VALUE 0. PIC 9(5) VAl.UE 0. PIC 9(5) VAL.WE 0. PROCEDURE DIVISION. DECL.ARATIVES, CUSTOM·ERROR SECTION. G-7 SOURCE PROGRAM LISTINGS ~ ~ USE I 01 DISPLAY USE l 02 00000& DISPLAY 02 0~000& STOP 02 000033 0L'lb7 001613 <"0lbq 30170 ~0171 00172 00173 <"21171.1 00175 0Vl17b 111"'177 00178 00179 00180 01!!181 012'182 lt1"1 1 8 3 00181.1 00185 0018& e0187 0~188 MOVE I 03 001!J0b2 DISPLAY ACCEPT IF MOVE : 03 000122 I ~3 00013& 0>'1191 0f!'192 0':'193 ""1q4 0(il1q5 001q& USE AFTER STANDARD ERROR PROCEDURE ON CU8TOMER·FILE 1 SSEGIN, . .. DISPLAY "l·O ERROR ON CUSTOMER·FILE, CODE c· CUSTOMER·FILE·STATUS ) STOP RUN, STATEM·ERROR SECTION, USE AFTER STANOARD ERROR PROCEDURE ON STATEMENT·REPORT, SBEGIN, . .. DISPLAY "I·O ERROR ON STATEMENT·REPORT, CODE C" STATEMENT·REPORT·STATUS ) STOP l'<UN, END DtCLARATIVES, ***********~*********************************************** T~i· 1eetion perform· "ou1ek··Pin; fUP'ICtlor'!I OP'11Vo START·UP·HOUSE~EEPING SECTION 49, 58EGIN, ACCEPT TOOAYS·DATE FROM DATE, ~OVE CORRESPONDING TOR TO TODAVS·REPORT·DATE, ~OVE SPACES TO OPTIONS·AREA. Get CUSTOMER·FILE n1me. U1e def1ult if none 11 eP'ltered, DISPLAY " ENTER CUSTOMER FILE NAME COR CR)"· ACCEPT OPTIONS·AREA. IF OPTIONS·AREA NOT · SPACES MOVE OPTIONS·AREA TO CUSTOMER·FILE·ID l 0~199 l'l371 POSSIBLE ~IG~ ORDER ~ECEIVING FIELO TRUNCATION, DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DISPi.AV ACCEPT MOVE IF DISPl.AV GO I 03 0"'015& I 03 000174 I 03 0illl'l2311 I iH ~00302 03 000314 03 000341'.l IH 0iil035& 00200 ~H'21(11 002;,2 110203 00204 00205 002<!8 00211 00212 0'1l213 01il215 iJ~217 MOVE SPACES TO OPTIONS·AREA, Get optiol"l1 from t"· oper1tor el"ld 1tore re1u1t1. I9nore l"IOn·1t1nd1rd option il"IPUto DISPLAY " a Print 1tatement1·, DISPLAY " · Print 11"1voic··"· DISPLAY " CA a '1111 al 1 c1telog1·. DISPLAY. co. Mail selective c1t1log1·. DISPLAY " CL· Credit limit letter1"1 MOVE ALL ZERO TO OPTION·STORAGE, IF OPTIONS·AREA : SPACES DISPLAY "Di·crepancv Report 0P'11V" GO TO CONFIRM·OPTIONS, MOVE 0 TO A·COUNT 0 G-8 SOURCE PROGRAM LISTINGS INSPECT I 03 00037& IF DISPL.AY STOP I 03 0005&& 03 01Hlb02 1 03 000&20 OISPL.A1 IF OISPl.AY IF OISPL.AY IF OISPl.AY IF OISPL.AY IF O!SP!.U I 03 000&21.1 I 03 000&1.12 I 03 000&72 I 03 000710 I 03 00071.10 1 03 000750 03 00100& I 03 001024 03 001054 I 03 00107l I 03 00!!22 DISPLAY ACCEPT IF GO IF DISPLAY STOP I 03 01H 14& I 03 0011&1.1 I 03 00117& I 03 001240 I 03 001250 : 03 00127& : 03 001311.1 IF DISPLAY MOVE I 03 001320 I 03 001350 I 03 0013bb IF DISPLAY ACCEPT I 03 001410 I 03 0011140 I 03 0011.15b OPEN MOVE START I 03 0011.170 I 03 0015P0 I 03 001510 OPEN 03 001531.1 READ GO I 01.1 00000& I 01.1 00002& 00218 0P-219 00220 00221 00222 00223 00224 lrHl225 0f1122b 00227 00228 i.'10229 00230 00231 <10232 00233 00235 ~0237 00238 00239 0Vl240 002u1 00243 <H:t21.1b 00247 01!248 0021.19 00250 00251 00252 00253 00254 00255 0025& 00257 00258 0025q 002&0 002&1 00202 002&3 0l'l2b4 002&5 0P2bo 002&7 002&8 002&9 00270 INSPECT OPTIONS·AREA OPTION·ENTRY (1) TAI.LYING FOR ALL ·s· OPTION·ENT~Y (2) FOR AL.L ·I· OPTION·ENTRY (3) FOR AL.L ·cA· ·co· OPTION·ENT~Y (4) FO~ ALL OPTION·ENTRY (5) FOR ALL ·cL·. IF OPTION·STORAGE a ALL ZERO STOP RUN 0 DISPl.AY ·Se1ecte1 OPtio"11·. IF NANT·STATEMENTS DISPLAY · St1te~e"t1·. IF ~·~T·INYOICES OISPl.AY · I"voic··"· DISPl.AY. 411 c1t1log1·. IF ~ANT·CREDIT·l.IHIT·LETTERS DISPLAY. CPtdit limit lettep1·. CONFIRM·OPTIONS. DISPLAY "CONFIRM OPTIONSt (Yle· OP (N)o·. ACCEPT OPTIONS·AREA. GO TO CONFIRM·OPTIONS 0 IF OPTIONS·A~EA·CHAR (1) · ·N· DISPl.AI' "ABORTED 8Y OPERATOR· STOP RUN 0 IF ~ANT·INYOICES HOVE 0 TO OPTION·ENTAY (2), IF ~AN!·STATEMENTS DISPLAY "E"t·P 1t1teme"t me111ge OP CA" OPEN INPUT CUSTOMER·FILE. ~UVE "000000" TO CUST·CUST·NUMBER, &TART CUSTOMER·FILE KEY IS > CUST·CUST·NUMBER 0 OPEN OUTPUT STATEMENT·REPORT. *********************************************************** MAINLINE SECTION. SBEGIN 0 READ CUSTOMER·Fil.E NEXT AT END GO TO END·PROCESS 0 G-9 SOURCE PROGRAM LISTINGS ADD I 04 1!00031:> IF PERFORM ADO I 011 000046 I 1!14 i111H1.-io2 04 000070 IF I 04 000100 CALL ADD 04 (<100202 011 e0;;,214 MOVE IF MC''vE IF f'IOVE IF MOVE IF MOVE IF MOVE E.LSE IF 1'10\/E IF CALL I 011 0002.:!ll I 04 000231.1 I i<J(I ft'00250 I 011 011iid272 I 011 000322 I 04 00.l344 I 011 iiH.!03b<l I 04 013.)1102 04 00~Ulo I 04 llJ00Ullll 174 illl!lll1151.1 llJlj 0<)047b 0U <''10')0b I e11 011Jio534 ' 01.1 i.'li11055b I 0LJ !ll(l\0572 IF I '64 00'6~'10 GO I 011 00061:>1.1 GO CALL ADD I 1!)11 00067'1 0'1 01110112 0a 0eoe 121.1 Nl271 0~272 00273 00271.1 0~275 Jl'"':>~4. 'li;;,271 00278 0iil279 "'""280 00281 .ie.2112 00283 00281.1 e028S 00280 iHl287 00288 t:l0289 1:!1il290 00291 0~292 fr.lli.'293 ~02911 0'1215 002% <lr.l297 !00290 1!!'12q9 k!i.'130\d 0i:l301 t:0302 00303 l-J<l3~1.1 1'0305 0030b 1110307 1111"308 llJ03k19 0031iJ itllll311 00312 00313 1!1:'1314 IH'315 01'l3lb llJ03t 7 1(11"318 00319 iHH2J 00321 01.'322 0~323 ~1"324 ~0325 llJ032b 0'1327 ADD 1 TO RECORD·COUNT, Pr I 11t 1tate111ent If !"eQu!l"ed, IF CUST·CURRENT·dALANCE > 0 PEHFOR~ PR!NT~ST~TEMENT ADO 1 TO STATEMENT·COUNT, If we need 1 111111 Ing 1abel for 11 catelog, DI' 1nt Ito IF ~ANT·ALL·CATALOGS OR .. ANT·SOME·CATA~OGS ANO CUST·PURCHASES·YTO NOT c YTD·CATALOG·MINIMUM CALL "DOCATS" USING CUSTOMER·FILE·RECORO ADD 1 TO CATALOG·COUNT, C"itCI( for di1crec1nc1e1 In U1e cu1to111er·1 record, '10\/E ALL ZERO TO EXCEPTION-INDICATORS, ff CUST·CUSTOMER·NAME : SPACES '10YE 1 TO EXCEPTION·INDICATOR (1), IF CuST·ADDRESS·~INE·1 · SPACES OR CUSl·ADORESS·Z!P·CODE NOT > ·00000· 11ovE 1 TO EXCEPTION·INDICATOR (2). IF CUST·PHONE :i SPACES "l.:JVE 1 TO EXCEPTION·INOICATOR ~ 3). IF cuST·CREDIT·LIMIT NOT > 0 MOVE 1 TO EXCEPTION·IkDICATOR (4), IF CUST·CURRENT·BALANCE > CuST·CREDIT·Llf'IIT "'OVE 1 TO EXCEPTION·INOICATOR (5) ELSE * IF CUST·CU~RENT·BALANCE > CUST·CREOIT·~IMIT Ii!, 8 "IOYE 1 TO EXCEPTION·INDICATOR (b). IF tXCEPTION·INOICATORS NOT 1 ALL ZERO CALL "EXCEPT" USING CUSTOMER·FILE·RECORD EXCEPTION·INDICATORS, Generate a ·credit 111111 t 1etter· 1f ttie cu1to~er ha1 exceeded or !· about to exceed 1'111 11 !!lit. IF ~ANT·CREDIT·L.IMIT·~ETTERS .lNO * CJST·CURRENT·BALANCE NOT c CUST·CREDIT·LIMIT 0,8 GO TO DO·CR. Go get t tie next record, GIJ Tn i'!AINL.INE. DO·CR. CALL "CREOLM" USING CUSTOMER·FILE·RECORD, ADD 1 TO CREDIT·L.l"'IT·COUNT, G-10 SOURCE PROGRAM LISTINGS GO I 04 000734 CLOSE CLOSE MOVE MOvE DISPLAY I l!l5 00000b I 05 00001& I 05 00002b I 05 00003b I 05 000052 00328 0032'1 "1'-l330 00331 00332 00333 00334 00335 0e33o 00337 0033'1 0fll340 00341 MOVE DISPLAY MOVE MOVE MOVE MOVE DISPLAY MOVE MOVE DISPLAY STOP I 05 000100 I 05 000114 I 05 000132 I 05 000142 05 00015b I 05 000174 I 05 000204 I 05 000220 I 05 000230 I 05 00024& I 05 000202 05 000300 MOVE MOVE l'!Rl TE MOVE MOVE MOVE MOVE wRITE I 0b 000000 I 0b 000010 I 0o 00002b I 0b 000050 I 0o 000000 I 0o 000070 I 06 00010~ I 0o 000110 0034b 00347 00348 !110350 00351 00352 00353 00355 00350 0"357 00358 0035'1 00360 00301 00302 00303 00304 00305 00300 00307 00368 0030'1 00371 00372 MOVE MOVE "'RITE MOVE MOVE 111RITE I 06 000144 I 0o 000154 1 00 001illo4 I 0o 000210 I 0o 000220 I 06 000231:1 00374 00375 00376 <l0377 00378 003H 00380 GO TO MAINL.INE. *********************************************************** T"e CUSTOMER·FILE "'' been co~Dletely Droce11ed, ReDort 1ign1f1c1nt counta. END·PROCESS SECTION 47 0 SBEGIN, CLOSE CUSTOMER·Fil.E, CLOSE STATEMENT·REPORT, MOVE "RECORD COUNT" TO DISP·MESSAGE, MOVE RECORD·COUNT TO OISP·NUM, DISPLAY DISP·MESSAGE 0 MOVE "STATEMENTS" TO DISP·MESSAGE, MOVE STATEMENT·COUNT TO DISP·NUM, MOVE ·INVOICES" TO OISP·MESSAGE 0 MOVE INVOICE·COUNT TO DISP·NUM 0 MOVE "CATAl.OGS" TO DISP·HESSAGE. MOVE CATAl.OG·COUNT TO DISP·NUM 0 DISPl.AY DISP·MESSAGE. MOVE "CREDIT LIMIT LETTERS" TO DISP·MESSAGE. MOVE CREDIT·LIMIT·COUNT TO OISP·NUM 0 STOP RUN, *********************************************************** * Tnl· section generates · 1t·teme"t for tne curre"t CUSTDMER·Fil.E record. PRINT·STATEMENT SECTION 48 0 SBEG!N 0 MOVE SPACES TO STATEMENT·REPORT·RECORD, MOVE "STATEMENT" TO FORM·NAME, WRITE STATEMENT·HEPORT·RECORD AFTER ADVANCING PAGE, MOVE SPACES TO STATEMENT·REPORT·RECORD 0 ~OVE CUST·CUSTOMER·NAME TO ADDRESS·WINDOW 0 MOVE "DATE:" TO FORM·NAME, MOVE TODAYS·REPORT·DATE TO FORM·DATE. WRITE STATEMENT·REPORT·RECORD AFTER ADVANCING 1 LINE, MOVE CUST·ADORESS·LINE·1 TO ADDRESS·WlNDOw, MOVE "ACCT1" TO FORM·NAME. MOVE CUST·CUST·NUMBER TO FORMaDATE 0 WRITE STATEMENT·REPORT·RECORD AFTER ADVANCING 1 LINE 0 MOVE SPACES TO STATEMENT·REPORT·RECORD 0 MOVE CUST·ADDRESS·LINE·2 TO AODRESS·WINOOw. WRITE STATEMENT·REPORT·RECORD AFTER ADVANCING 1 l.INE, G-11 SOURCE PROGRAM LISTINGS HOVE HOVE wRITE HOVE MOVE MOVE WRITE HOVE HOVE lllRITE HOVE lF MOVE ELSE lF HOVE ELSE HOVE WRITE EXIT I 06 000254 I 06 000264 I 06 000274 I 0& 000320 I 0& 000330 I 06 00031.14 I 0& 0003ci<l I 06 0001.101.1 I 06 0001.1111 I 06 01HHl50 I 06 0001.174 I 06 000501.1 I 06 000520 00381 00382 00383 003811 00385 0038b 00387 00388 0P389 01il390 ll'03<>1 01113<12 01113<>3 I 06 000530 I 06 000540 I 0& 0005&& I 06 000576 I 06 000&0& I 0& 000&16 I 06 00065~ 001.101 001102 001.103 ld01.10U 004~5 00U0o MOVE CUST·AODRESS·LINE·3 TO AOORESS·WINOOw. MOVE CUST·AOORESS·ZIP·COOE TO AODRESS·ZIP. WRITE STATEMENT·REPORT·RECORD AFTER ADVANCING 1 LI~E. HOVE SPACES TO STATEMENT·REPORT·RECORD. HOVE CUST·PURCHASES·YTD TO REPORT·YTD, ~RITE STATEMENT·REPORT·RECORO AFTER ADVANCING 8 LINES, MOVE SPACES TO STATEMENT·REPORT·RECORD. MOVE TODAYS·REPORT·DATE TO STATEMENT·DATE. HOVE CUST·CURRENT·BALANCE TO STATEMENT·BALANCE. MOVE "BALANCE OUE" TO STATEMENT·CAPTIONe wRITE STATEMENT·REPORT·RECORO AFTER ADVANCING 6 LINES, HOVE SPACES TO STATEMENT·REPORT·RECORD. IF CUST·CURRENT·8ALANCE > CUST·CREDIT·LlMIT MOVE "** CREDIT LIMIT EXCEEDED **" TO STATEMENT·REPORT·RECORD ELSE IF CUST·CURRENT·BALANCE > CUST·CREDIT·LIHIT · 0,8 MOVE "CONSIDER AN INCREASED CREDIT LIMIT. " TO STATEMENT·REPORT·RECORD ELSE MOVE STANOARD·MESSAGE TO STATEMENT·REPORT·RECORD. WRITE STATEMENT·REPORT·RECORO AFTER ADVANCING 4 ~INES, SEXIT, EXIT, G-12 SOURCE PROGRAM LISTINGS COBOi. 4,00 SRC1STAT6,CBl.1l.I 05·0CT·78 dbli.11113 PAGE 011 Fil.E·TO·l.UN ASSIGNME~T TABl.E--@ !'-<AME SOURCE RELATIVE ~ C:U&TOMER·FILE STATEMENT·REPOKT LPJE ~ o!l0l4 7 i!JIC0Bl I.UN ~ 0~0fl1. 00002. ,,(§) DATA MAP LEVEL ~ ro FD 01 03 03 a:; 03 !:l3 io!3 i03 i.l5 05 ~5 03 03 03 a3 05 03 03 03 03 01 03 03 <'13 05 01 ;n 03 fll1 23 "3 03 01 lll1 01 01 01 03 ~3 <l3 01 :.13 ;,,3 .n li:l1 1:11 ~3 01 01 H 01 lil3 01 01 "13 iH 01 ill 01 01 01 NAME ~ CUSHlMC.R·fo Il.t. ST~TE~ENT·REPORT CUSTO~Ek·Fil.E·RECORD @-SOURCE DD!V DIR USAGE CLASS DCC LEN L.INE@__LOCN LOC ;,:!031l 7 li:l~<J01.11.1 @ @@ 0Ml6l <i2i004iU I I I i:l.aiil5b ld0ii726 00Nl00 DISP AN @@ I I 00 0205 CUST·CUST·~UMBER 00057 000726 01,HHHl& CISP AN 00 00f/J& CUST·CUSTOMER·NAME CUSi·AOD~~ss-~!NE-i ·N 00058 ~H1eiS; lil00731.1 iiiilii:iii2 000011.1 '5iii~Hi22 OISP ors;;; AN 00 0030 i'iiii i'iiii3iii CUST·ADDRESS·l.I~E·2 00060 011'1030 000030 OISP AN 1110 0030 CUST··DDRESS,l.!~E,3 0006! ~010Cb 01rn.ne O!SP ~N 00 0030 CUST·ADDRESS·ZIP·CODE 000&2 0011211 00001.14 DlSP AN 00 0005 CUST·Pl10NE 000&3 l'l01131 ;HFil052 DISP AN 00 0010 CUST·Pl10~E·AREA·COOE CUST·Pl10NE·EXCl1ANGE CUST·P110NE·LAST·l.I CUST·P~ONE·NUMBER CUST·ATTENlION·LlNE 0!1!3&1.1 01211131 ****** D!SP AN 000&5 01211134 ****** DISP AN 000/J& 001137 ****** DISP NUM 000&7 001 lll ****** DISP NUM .?J00b9 0011Li3 ****** DISP AN 00 0003 0111 0003 00 00011 0(0 0010 00 0020 CUST·CREOIT·LIMIT 001'l10 0011&7 0000&0 DISP NU"! 00 00u CUST·HEAOE~·OATA NEXT·ACCT·NUMBER ia0071 0011&7 ****** DISP AN 00073 001175 ****ill* OISP lllUM 00 0012 00 01i!lli!b CUST·CURRENT·BALANCE 00074 1')01203 0i'l00&b DISP NUM 00 0012 CUST·PURCHASES·VTD 0007& 001217 001iHH4 DISP NUM 00 0012 CUSi·NEAi·O~DER·SE~UE~CE 0007Ci 001233 DI5P NU"i 00 0004 CUST·NEXT·PAYMENT·SEQUENCE STATEMENT·REPORT·RECORD l'l0079 001237 ****** D!SP NUM 00083 00124& 000102 DISP AN 00 00011 00 0080 ADDRESS·"INDO"' 00085 1~1211253 0lil0110 DISP AN 00 01i!l30 ADDRESS·ZIP 0111087 001.312 ~0011& DISP AN 00 00k!5 FORM·NAME 00089 001350 000121.1 DISP AN 00 00111 FORM·OATE 01Hl91 00135& 00ran2 DISP A"l 00 0008 S·R·R·2 'IEPORT·CREDIT 00093 fd0121.1& ****** OISP AN 00 0057 01~095 0012&5 0(1Jii!11.10 DISP NMEOIT 00 00111 REPORT-no 01/1097 001317 00011.1& DISP NHEDIT 00 001& S·R·R·3 STATE,.ENT·DATE 001;99 00121.1& ****** DISP AN :;JQ\100 0012LI& 000154 DISP AN 00 0f/J70 00 0012 STATEMENT·CAPTION 00102 001274 <l0!01&2 DISP AN 00 0032 STATE~ENT·8ALANCE 0!.!103 0013311 ('!00170 DISP NHEOIT B0 001& CUSTOMER·FlLE·STATUS 00107 001370 0[il017& DISP AN 00 0002 STATEMENT·REPURT·STATUS lllfll108 001372 000204 DISP AN 00 0002 CUSTOMER·Fil.E·ID 0<'!109 0013711 000212 DISP AN 00 00111 TODAYS·DHE 0121111 0011.112 "'1110220 DISP NUM 00 0kl0& TOR 00112 0011.112 00022& DISP AN 00 000& TOOAY·YEAR 0121113 iliH'112 000234 DISP NUM 00 0002 100AY·!'10NTrl 00114 0011111.1 000242 DISP NUr-1 00 0002 TODAY·DAY 01<l115 012111.11& 00025fd DISP NUM 00 0f/J02 TODAYS·REPORT·D4TE 0"'1 lb 001420 00025& DISP AN 0lil 0008 TODAY·MONT~ illilll 17 001420 0002&4 DISP NMEOIT 00 0002 TODA1·0AY 00119 <l1211Li23 <!00272 DISP NUM illli!l 0002 TODAY·YEAR 00121 001Ll2& 000H0 DISP NUM 00 0002 STANDARO·MESSAGE 00123 ldill143;.'J 00030& DISP AN 00 0050 DISP·MESSAGE 00125 001512 000314 DISP AN 00 0035 OISP·"/UM 00127 001550 000322 DISP NMEDIT 00 0005 YTD·CATALOG·M!N!MUM 01H29 001551:1 000330 DISP NUM 00 0010 EXCEPTION·Ii'-<DlCATORS 00131 !.!0!1570 00[il33o DISP AN 00 0010 EXCEPTlON·INDICATOR 00132 001570 0003Ll4 DISP NUl'4 01 0001 OPT!ONS·Af<EA i<ll<l13~ !1101&02 00fd3&4 DISP AN 00 0030 QPTIONS·AREA·Cl1AR 00135 ;,01&02 000372 DISP AN 01 0001 A·COUNT 00137 0'l1&40 0001112 DISP NUM 00 0002 OPTIO~·STORAGE 00139 i<l01&Ll2 000420 DISP AN 0ra 0008 OPT!ON·ENTRY lii13ll.li! 1110lb'12 i.'1111211.12& DISP NUM 31 0001 OPTION·\IALUES RECORD·COUNT 0011.11 001&42 ****** DISP AN 00154 001&52 000531' DISP NUM i!0 0008 00 0005 STATEMENT-COUNT 00155 001&&0 00051.12 DISP NUM 00 0005 !NVOICE·COUNT 0015& 001&&& 000550 OISP NUM 00 0005 CREDIT·l.I~IT·COUNT ii:H'157 001&711 0111055& DISP NUM 00 0005 CATAl.OG·COUNT [il0158 "101702 <l'<l05&4 DISP NUM 00 0005 G-13 SOURCE PROGRAM LISTINGS PROCEDURE NAME "1fl.P---® f e NAME CUSTOM·E.RROR SSE.GIN STATEM·ERROR S&EiHN START·UP·MOUSEKEEPING Sl:H:.GI"I CO~F'I~M-OFiIQ~S MAI"ILINE SSE.GIN DO·CR ENlJ·PROCE.SS Sl:!EGl"I PRINT·STHEMENT SBEGIN SEX IT SOURCE @4::_INE. 0illlb4 001bb :/lill 72 00174 0~187 00188 002iii 0..l2bb 0~267 lli'l325 111033b 1'10337 l/J03bll i3'.'13o5 ~0405 ~5CT $ST001 SSHH11 iiiSHH:l2 SST002 $ST003 SST003 SSi003 SST004 SST!il04 SSTl/l011 ssri;.0s SST005 5Sh10b SSHl0b $ST00b OFFSE.T SEG SECT P4RA rp> ~ @ <?!> 00000& 00 s 0>'!00i:lb 01/J 01"01110b 1113 00000b 1111!l lii01:h:l0b 4q 0ill01i106 4q 001 iii& aq 0000111b 0~ 0k1000b 011 p 0i:HH12 0~ p ¥l0000b 47 0000i:!b 47 p 01HHl0b 48 iil00k:'0b <18 p idliliilbSii:! 48 p SE. CT_IOJAN1\NA"1f CUSTO..,·ER~ STATE"'·E'<ROR START·UP·HOUSt~EE.Pl~G MilINLINE ENO·PROCESS PR !NT·SHTEMElllT ~·~E."<T N0 0 @:.AME 42 i}0 SSl 0"1 0111 $51002 4q $STliHl3 0t:I SST;il04 117 SST .31!15 48 SSHl0b & f}) SIZE 0Wl00b<d 00024 "l0001:10 00024 001570 00444 00077~ 00252 0W!0330 00108 "'00b7i/J 00220 ,........ REFEl<ENCED OTS f<OUTINE.S~ 5MGNE SXGO SXl~lT SCFSNE. SMGLA SXOPEN SXENDP SCZDl.T HSTGT UAr2D SXkED"' :SXSTPR $CGZL.T HZDGT $11.MG4 $X,.RIT $XlNSH ~CZDL.E !iCGZGT ~SoIXl $XSTAR SXINTG SCGZL.E SMC Al) HPRF 1 SXCl.OS $XINTO SCSTEQ $MJUSl. SXE·CC SXACCS SCFSEQ SMCFST SXEDIS SXCAl.I. SCSTNE SMGNG G-14 SOURCE PROGRAM LISTINGS OAlA PSECT MAP-@ ~ NAMEfe SIZE SSlOAT SST DOD SST POT $STARG $Sl~RK SST LIT SST LTD SS1LST SS1PFM SST SOT 'SlADT $S1USE SCBIOT SCBFA1 SCbX41 $51108 sCBIF1 SCBIR1 SCBKD1 SCBBD1 SCBK61 SCBFD1 SCBSWT 0017U2 000b0b 000030 000000 00010b 001322 000550 00000& 00021U 00000& 000000 000030 00013U 000120 0001&0 003000 0001U0 000100 0001U0 0001uu 000100 000002 000002 00497 00195 00012 000~0 00035 003b1 0018~ 00003 00070 00003 00000 00012 000Ub 000U0 0~05b 007&8 000u6 00032 000u8 00050 00032 00001 00001 pr-... EXTERNAL SUBPROGRAM REFERtNCES DOC HS EXCEPT ~ SEVERITY cp ERROR COUt-;T COMPILER GENERATED ODL FILE~ 1COBOL STANDARD ODL FILE GENERATED CNS 05·0CT·78 ,coBOBJ=STATB.OBJ JCOBKER·ST JCOBMAIN 1RMSREQ:c1001s JRMSREQsCI0033 ST0U7SI 0 NAME STS0u7,GBL 0 PSECT SST005,GBL,I,R~,CON 0 FCTR wSTS0U7·$ST005 .NAME srs0a8,GBL .PSECT $ST00b,GBL,11Rw,coN ST0ass1 .FCTH ·STS~aS-$STe06 .NAME STs0uq,GBL .PSECT SST0~3,G6L,l,Rw,CON ST0U9SI 0 FCTR ·STS~U9·$Sl003 STOVRSI .FCTR ST~u7s,ST~u8$,ST~49S 0b:Ull13 G-15 SOURCE PROGRAM LISTINGS COBOL 4,00 SRC:DOCATS,CBLl4 05·0CT·78 0bl48123 PAGE 001 CMD100C4TS,00CATS:DOCATS/MAP/06J/KE~1DO 1DENT1 278~68 0001111 :.1001112 00003 ~00~4 0001115 000eo iillHHH \l0008 00i3'/19 lll~ill\l 0111011 01'1012 00013 00014 00015 ;tllil01b iJ.0iil17 00i.118 0ki019 1Wiil2i.:l 00021 i,:l!~022 0\lkl23 00024 00025 \l002b 00027 0e02e 1Hli<'l29 <lli'it'l3io:l 00031 <'lfil032 1()0033 ihll03'1 00035 00irl:Sb lil00H 1:10038 '10039 0004'1 ('1001.11 <Hl01.12 0~01.13 00il4/.I 1hliil''5 00011b 0fil047 1Hl<l48 00049 00i.1151'l i-10051 L 0111052 L '10d53 L 00051.1 L 00055 L 00i<l5b L 00057 ~eiase 0il\l59 "ll0bl:l \l00bl 000b2 0Ql0b3 000b4 01'l0b5 l:l00bb 0~0b7 i.l01:l68 0'110b9 vrnia ;ta 00071 0('-072 0<10i3 ;Jf/J!il74 00075 001d7b \:"10:a77 <10078 !o'lt"079 111~081'1 \'10081 IDENTIFICATION DIVISION, DOC ATS. DATE·l'IRlTTEN, 5 OCT 1978, OATE·COMPILED, lllS·OCT-78 , REMARKS, T~il l~b·proQra~ Prf"tl e ~.111"g l1b1l for eac" CUSTOMER·FILE record P111ed fro~ t"e ce111"g orogr1~. ENVIRONMENT DIVISION, CONFIGURATION SECTION, SOURCE·COMPUTER, PDP·11, OBJECT·COMPUTER. POP·11 SEGMENT·LlMIT 25, JNPUT·OUTPUT SECTION, FlLE·CONTROL, SELECT LABEL·REPORT ASSIGN TO "SYILABEL,REP" FILE STATUS IS LASEL·REPORT·STATUS, DATA DIVISION, FILE SE:CTION, FD LABEL·REPORT LABEL RECORDS ARE STANDARD, 01 LABEL·REPORT·RECORO PIC X(ll0), 01 L·R·DETAIL, ~l FILLER PIC XC34), 03 LR·ACCOUNT ~1 L·R·DETAIL·2, PIC X(b) 0 ~3 FILLER PIC XC32l. ~3 LR·ZIP PIC X(5), WORKING·STORAGE SECTION, 01 LABEL·MEPORT·STATUS VALUE. wxx·, PlC XC2) LINKAGE SECTION, ~1 CUSTOMER·FILE·RECORO, 1113 CUST·CUST·NUMBER ~3 CUST·CUSTOMER·NAME 03 CUST·ADDRESS·LINE·1 ~l CUST·ADDRESS·LINE·2 1113 CUST·4DORESS·LINE·3 03 CUST·ADD~ESS·ZIP·CODE PIC xcei>. PIC x Cli!). PIC X(30) · PIC X(30) · PIC X(30) · PIC xc5>. ~S ~5 CUST·PHONE·AREA·CODE PlC CUST·PHO~E·EXCHANGE PIC X(3) 0 XC3). 05 CUST·PHONE·LAST·4 PIC 9(4). 03 CUST·PHONE·NUMBER REDEFINES CUST·PHONE 03 CUST·ATTENTION·LINE 1113 CUST·CREDlT·LIMlT PIC 9(10) 0 PIC PIC 9X((1200))Y0 99, 03 CUST·HEADER·OATA REDEFINES CUST·CREDIT·~lMIT, 05 FILLER PIC X(&), 05 ~EXT·ACCT·NUMBER PIC 9(b), 03 CUST·O~E·AMT 1113 CUST·80UGHT PIC 9( Ul)Y99. CUSi·NEXi·ORDE~·SEQUENCE CUST·NEXT·PAYMENT·SEQUENCE PIC 9(4), PIC C!(U) · PROCEDURE DIYISIO~ USING CUSTOMER·FlLE·RECORD, DECLARATIVES. REPORT·ER~QR SECTION, G-16 SOURCE PROGRAM LISTINGS USE. I 01 00000b DISPLAY I 01 000000 IF OPEN MOVE MOVE lolRITE '40~E lolRITE MOVE .il'fITE I 02 000000 I 02 000022 I 02 000032 I 02 0000112 I 02 000052 I 02 000010 I 02 01d010o I 02 000132 02 000142 00082 01cl083 00084 00085 00080 00087 00088 00089 00090 00091 lde092 '110093 1()0094 00095 00090 00097 00098 00099 00100 00101 USE AF!ER STANDARD ERROR PROCEDURE ON LABEL·REPORT 0 SBEGIN. . .. DISPLAY "I·O ERROR ON LABEL·REPORT, CODE C" LA6EL·REPORT·STATUS ) END DECLARATIVES. MAINLINE SECTION 0 SBEGIN 0 IF LAaEL·REPORT·STATUS · ·xx· OPEN OUTPUT LABEL·REPORT 0 MOVE SPACES TO LABEL·REPORT·RECORD 0 MOl/E CUST·CUST·NUMBER TO 1..R·ACCOUNT, ~RITE LABEL·REPORT·RECORO AFTER AOl/ANCING 1 i..INE 0 MOVE CUST·CUSTOMER·NAME TO LABEl..·REPORT·RECORD. ~R!TE 1..ABEl..·RE?CRT·RECORO AFTER ADVANCING 2 LINES. MOVE CUST·AOORES3·LINE·1 TO LABEL·REPORT·RECORO, COBOL 11.00 SRC:DOCATS.CBLJl.I MOVE WRITE MOVE MOVE WRITE MOVE lriRITE EXIT I 02 000100 ; 02 liH!017o 02 000222 02 000232 I 02 00(121.12 I 1:12 00id2oo I 02 00027b I 02 000322 00102 00103 00104 til0105 3010b 00107 00108 il!0109 00110 00111 00112 0111113 00114 ta5·0CT·78 00148123 PAGE 003 WRITE LABEL·REPORT·RECORD AFTER ADVANCING 1 LINE, MOVE CUST··DDRESS·LINE·2 TO LABEL·REPORT·RECORD 0 WRITE LABEL·REPORT·RECORD AFTER ADVANCING 1 LINE. MOVE CUST·AOORESS·l..INE·3 TO LABEL·REPORT·RECORD. MOVE CUST·ADORESS·ZIP·CODE TO LR·ZIP. WRITE LABEL·REPORT·RECORO AFTER ADVANCING 1 LINE 0 MOVE SPACES TO l..ASEL·REPORT·RECORD 0 WRITE LABEl..·REPO~T·RECORD AFTER ADVANCING 2 LINES. EXIT PROGRAM. G-17 SOURCE PROGRAM LISTINGS COBOL. 4.00 SRC:DOCATS 0 CHL.J4 FIL.E·TO·L.UN ASSIGNMENT TABL.E 05·0CT·78 0&148123 PAGE 004 NA"'E l.ABEL.·REPOtH SOURCE l.INE RELATIVE !..UN ftlli'HB1 1!0001. L.EVEL. FD 01 01 03 01 il3 01 L 01 I. 03 I. 03 L J3 I. 03 I. rn I. 03 I. 1.H I. .is L 05 I. 05 I. id3 L. i/13 L H I. 03 L. 05 L .n I. '!)3 I. lll3 L. <13 NAME L.ABEL·REPORT L.A~EL.·REPORT·RECORD L.·R·DETAIL. L.R·ACCOUNT L.·R·DE TA IL.· 2 L.R·ZIP L.ABEL.·REPORT·STATUS CUSTOMER.FI!..E·RECORD CUST·CUST·NUMofk cusT-CUSTO~ER-NAME CUST·ADDRESS·LINE·1 CUST·ADOkESS·L.INE·2 CUST·4DD~ESS·L.INE·3 CUST·ADDRESS·lIP·CODE CUST·PHDt.E CUST·PHD~E·A~EA·CODE CUST·PHONE·EXCHANGE CUST·PHONE·LAST·l.I CUST·PMONE·NUMBE~ CUST·ATTENT!ON-L.lNE CUST·C~EDIT·LIMIT CUST·HfAOER·DATA NEXT·4CCT·NUMoER CUST·O"'E·Al'T CUST·~OUGMf CUST·NEXT.O~DE~·SE~UENCE CUST·NEXT·PAYMENT·SEQUE~CE DATA MAP SOURCE ODI\I DIR USAGE CL.ASS OCC L.EN l.I NE L.OCN L.OC 00031 00:dil40 00033 0011147.0 000000 DISP AN 130034 iHh1470 ****** DISP AN 0003b 000532 000i'l0& DISP AN 00037 i00i01.170 ****** DISP AN 0003'1 001tl530 000014 DISP AN ll00ll3 0005112 011hl022 DISP AN 130051 000000 ****** DISP AN 00~52 011113000 013ih'100 DISP AN 00053 00000& 0<'i000b DISP AN 03054 000011ll 01cl01l14 DISP AN 00055 001H02 00ftl022 DISP AN 00\!So ililli11110 000'-i30 DISP AN 00057 001117& 00003& DISP AN 00058 1:11H:l2id3 ****** D!SP AN 00059 000203 ****** DISP A'-1 01:l0b0 00!d20b ****** DISP A"-4 0016&1 000211- ***"'** DISP NUM 000b2 000203 ****** DlSP NUM il00&ll 001cl215 ****** DISP A"I 0ii10os 000241 ****** DISP NUM 00iclbc 01Hl241 ****** DISP AN 0001!8 k'J0<l2'17 ****** DISP NUl'4 il<l!d&9 iHHl255 *"""*** DISP NUM 0011171 011l<l271 ****** DISP NUM 00073 0i<H!305 ****** DISP NUM 00074 000311 ****** DISP NUl-I 00 !0040 00 00110 00 000& 00 0037 1110 0005 00 0002 00 0205 00 000& 00 0030 00 0030 00 0030 00 0A30 00 0005 A0 001111 1110 0003 00 0003 00 00011 00 0010 00 0020 00 0012 00 0012 1110 01110b 00 0012 0111 0012 00 0004 i/10 lll'!llllll NAME REPORTm~RROR SBEGlt>i MA l Nl.I NE SBEGIN PROCEDURE NAME r-1AP SOURCE PSECT OFFSET SEG SECT PARA LI~E ~~~:tel ~oc~el 110e~eb '"~ 00083 Si0001111 1311Hdill0b 00 0009iiJ )00002 00000& 0~ "'"' ""'-'Cll SD0"1r.12 1'10000& SE.CTION "'A"!E REPOl<T·El!RQl'I MA lP\IL!Nt SD0001 $00002 SIZE 0011122 00115 G-18 SOURCE PROGRAM LISTINGS NAME SDOE~T SD00il3 SIZE 0iil003b iHl0051.1 REFERENCED 015 ROUTINES SXOPEN SCST~E SXEDlS !!>MCFST SXGO $MGLA SXEXIT SXSUBK DAlA PSECT ~.4P NA Mt SIZE iDODAi SOODDD SDOPDT SDCARG SDOWRK SDOLIT SOOLTD SOOLST SOOPFM SDOS!JT SDOADT SOOUSE SCBIOT SC6Fili SCBXA1 SDOIOB SCBIF1 SCBIRl SCBKDl SCBBDl SCBK61 SCBFDl SCBS>jT 000541.1 000030 '100011.1 Z0~~a4 011010b 0'1100bll 0111003b 1<1001?102 0l'l0214 0~0e0e 00kl000 i1<'J003lil 000134 00<li20 00<H"00 001"!'100 il000M!' 000"'110 000 .. 00 1100021.1 000000 000002 000i'02 00ii8 00012 00<)00 00018 00035 0002b 01HH5 00i.hH 00117kl 0111000 00iH!l0 00kl12 li!<l0Ub 0ei0'1i: i:H1000 lil"-125b l:li<l0211 00010 00000 00010 0'100;:! 00001 iiHl0'-'1 EXTERNAL SUBPROGRAM REFERENCES NO EXTERNAL SUBPROGRAM REFERENCES NO ERRORS COMPILER GENERATtD ODL FILE JCOBOL STANDARD ODL FILE GE~ERATED ONI 05·0CT·78 ,coBOBJ:DOCATS.OBJ 1COB'<ER:DO 1RMS~EQ:C10015 ,NA~E 00$025,GBL ,PSECT $000~3.GBL1I1Rw1CON 0002ss: ,FCTR ·DOS~25·$000~3 DOOV~!: ,FCTR 00025$ ~6:118:23 G-19 APPENDIX H DIAGNOSTIC ERROR MESSAGES This Appendix contains a numerical listing of the diagnostic messages generated by the compiler. Following the text of most messages are explanations of the diagnostics, including descriptions of the compiler's recovery actions. iii CONTINUE PUNCH WITH BLANK STATEMENT. IGNORED. A blank line has a continue indicator. The continue indicator is ignored. jj2 QUOTE OR CONTINUE PUNCH MISSING. QUOTE ASSUMED. A non-numeric literal has no quote and the following line has no continuation indicator. A terminal quote is assumed at the end of the line. jj3 VIOLATION OF AREA A. ASSUMED CORRECT. The first non-blank character on a continued line occurs in Area A. The error is ignored. jj4 LINE LENGTH EXCEEDS INPUT BUFFER. TRUNCATED. Continuation lines cause a COBOL word to exceed the capacity of the input buffer. The word is truncated on the right; the number of characters retained depends on the type of word being processed. jjS .IO CONTROL. WITHOUT .FILE CONTROL. IGNORED. An I-0-CONTROL paragraph appears when no FILE-CONTROL paragraph was present. The I-0-CONTROL paragraph is ignored. jj6 .STRING. DATA ITEM MUST HAVE DISPLAY USAGE. A data item in a STRING statement is not defined with DISPLAY usage. Fatal. jj7 NAME EXCEEDS 3j CHARACTERS. TRUNCATED TO 3j. A character-string that appears to be a name exceeds 3j characters in length. The string is truncated on the right to 3j characters. H-1 DIAGNOSTIC ERROR MESSAGES g1g NUMERIC LITERAL OVER 18 DIGITS. TRUNCATED TO 18. A numeric literal exceeds 18 digits in length. The literal is truncated on the right, with any necessary adjustm1 ·nt to scaling. The sign is retained. g11 NUMERIC LITERAL HAS MULTIPLE DECIMAL POINTS. A numeric literal has more than one decimal point. g12 PICTURE CLAUSE ILLEGAL ON GROUP LEVEL. IGNORED. A group level item has a PICTURE clause. The clause is ignored. jl3 .SELECT. NOT FOUND. SENTENCE IGNORED. A FILE-CONTROL statement should begin with the word SELECT, but does not. All words up to the next period are ignored. jl4 JUST.SYNC.BLANK CLAUSES WRONG AT GROUP. IGNORED. A group level item may not contain JUSTIFIED, SYNCHRONIZED, or BLANK WHEN ZERO clauses. The clause is ignored. jl5 FILENAME MISSING OR INVALID. SELECT IGNORED. A SELECT statement either contains no user name or the the user name is invalid. The SELECT statement is ignored. g16 USAGE CONFLICTS WITH GROUP USAGE. USES GROUP. The usage specified for this differs from the usage stated higher group level. The group usage is used. item at a level jl7 ILLEGAL NUMERIC DATANAME IN .STRING. A numeric data item in a STRING statement has an illegal description. Fatal. g2g .ALL. ILLEGAL IN CONTEXT OF .STRING. STATEMENT. An ALL literal has been used in a STRING statement. Fatal. g21 SYNTAX ERROR OR NO TERMINATOR. CLAUSES SKIPPED. A SELECT statement is missing its terminating period, or an error causes the statement to be processed before all clauses were found. The SELECT statement is ignored. H-2 DIAGNOSTIC ERROR MESSAGES ~22 NUMERIC LITERAL ILLEGAL IN THIS STATEMENT. A STRING, UNSTRING, or INSPECT statement contains a numeric literal. Fatal. ~23 SENDING LIST OMITTED IN .STRING. STATEMENT. A STRING statement contains no sending fields before a DELIMITED BY phrase. Fatal. ~24 MORE THAN ONE FILENAME IN .ASSIGN. The non-numeric literal of an ASSIGN clause contains more than one file specification. Only the first specification is used. ~25 ILLEGAL DATANAME FOLLOWS .INTO. IN .STRING. The receiving field of a statement is invalid~ Fatal~ STRING ~26 SUBSCRIPTING DEPTH EXCEEDS 3. OVER 3 IGNORED. The OCCURS clause is nested more than three deep. The clause is ignored. ~27 VALUE ILLEGAL IN OCCURS ITEM. IGNORED. A VALUE clause appears in an item an OCCURS clause or in an subordinate to an OCCURS clause. VALUE clause is ignored. with item The ~3~ VALUE ILLEGAL IN REDEFINES ITEM. IGNORED. A VALUE clause appears in an item that either contains a REDEFINES clause or is subordinate to an item with a REDEFINES clause. ~31 NO TERMINATOR FOR .IO CONTROL. PARAGRAPH. The I-0-CONTROL paragraph is not terminated by a period. The terminator is assumed present. ~32 .MAP. NO LONGER APPLICABLE. IGNORED. An APPLY clause with the MAP option is not applicable for this version and future versions of the compiler. The APPLY clause is ignored. ~33 AN IO CONTROL CLAUSE WITHOUT FILES. A file-name is missing in a clause of the I-0-CONTROL paragraph. The clause is ignored. H-3 DIAGNOSTIC ERROR MESSAGES ~34 SYNTAX ERROR IN .APPLY. An APPLY clause has illegal syntax. The clause is ignored. ~35 INVALID ACCESS MODE. TREAT AS SEQUENTIAL. The SELECT statement contains an invalid ACCESS mode. SEQUENTIAL ACCESS mode is assumed. ~36 INVALID FILE ORGANIZATION. TREAT AS SEQUENTIAL. The SELECT statement contains an invalid ORGANIZATION specification. SEQUENTIAL organization is assumed. ~37 NO SELECT STATEMENTS. A FILE-CONTROL paragraph either contains no SELECT statements or none of those present is valid. The FILE-CONTROL paragraph is ignored. ~4~ .ASSIGN. OMITTED FROM SELECT. SELECT IGNORED A SELECT statement contains no ASSIGN clause. The SELECT statement is ignored. ~41 DECIMAL PLACES TRUNCATED. Decimal places have been truncated from a numeric literal during conversion for use as an integer. The integer positions are used. ~42 INTEGER EXPECTED, ZERO ASSUMED. An integer literal was expected, but fractional positions were found. The literal is ignored and a value of zero is assumed. ~43 INTEGER VALUE TOO BIG. LARGEST VALUE USED. A numeric literal is too big for conversion as an integer in the given context. A value of 32,767 is used. ~44 ERROR IN DATA RECORDS CLAUSE. CLAUSE SKIPPED. The word DATA is not followed by RECORD or RECORDS in the DATA RECORDS clause. The DATA RECORDS clause is ignored. ~45 ERROR IN LABEL RECORDS CLAUSE. CLAUSE SKIPPED. The word LABEL is not followed by RECORD or RECORDS in the LABEL RECORDS clause. The LABEL RECORDS clause is ignored. H-4 DIAGNOSTIC ERROR MESSAGES j46 NO INTEGER IN BLOCK CLAUSE. CLAUSE SKIPPED. The BLOCK clause does not contain a numeric literal. The BLOCK clause is ignored. j47 BAD VALUE IN BLOCK CLAUSE. CLAUSE SKIPPED. The numeric literal in the BLOCK clause causes an illegal block size. The block size in bytes must be greater than j and less than 32768. The BLOCK clause is ignored. jS~ NO INTEGER IN RECORD CLAUSE. CLAUSE SKIPPED. The RECORD CONTAINS clause does not contain a numeric literal. The RECORD CONTAINS clause is ignored. jSl INVALID VALUE IN RECORD CLAUSE. CLAUSE SKIPPED. The numeric literal in the RECORD CONTAINS clause is not greater than zero. The RECORD CONTAINS clause is ignored. j52 INVALID FILENAME. FD SKIPPED. The word following FD is not valid as a file-name. The FD entry is ignored. j53 FD TERMINATOR MISSING. ASSUMED PRESENT. The file description entry contains no period terminator. The error is ignored. j54 KEY WORD EXPECTED. REMAINING CLAUSES SKIPPED. A keyword that begins a clause, such as BLOCK, LABEL, DATA, etc., is missing. The remainder of the FD entry is ignored. jSS NO LABEL CLAUSE IN FD . . STANDARD. ASSUMED. The FD entry contains no LABEL RECORD clause. LABEL RECORD IS STANDARD is assumed. j56 NO SELECT. FILE DELETED. The FD entry's file-name has no corresponding SELECT statement. The FD entry is ignored. All references to the file-name will be diagnosed as undefined. H-5 DIAGNOSTIC ERROR MESSAGES ~57 ALLOCATED SPACE EXCEEDS LARGEST RECORD. The maximum record size specified by the RECORD CONTAINS clause exceeds the space required for any ~l entry under the same file. The value specified by the RECORD CONTAINS clause is used. ~6f RECORD AREA EXTENDED TO CONTAIN LARGEST RECORD. The space required by the largest fl record under a file description exceeds the space required by the RECORD CONTAINS clause in the FD entry. The value derived from the fl record description is used. f61 NO RECORD AREA. FILE DELETED. No record area is allocated for a file description. The file description is ignored. All references to the file will be diagnosed as undefined. ~62 ILLEGAL DATANAME FOLLOWS .WITH POINTER. PHRASE. The data item used as a pointer in a STRING or UNSTRING statement is illegal. Fatal. f63 ILLEGAL SYNTAX IN .STRING. STATEMENT. A STRING statement contains illegal syntax. Fatal. f64 77 ILLEGAL IN FILESECTION. CHANGED TO ~l. A 77 level item description has been found in the FILE SECTION. The 77 level is treated as an fl level. ~65 ILLEGAL WORD FOLLOWS .DELIMITED BY. PHRASE. A data-name or literal is expected following a DELIMITED BY phrase in a STRING or UNSTRING statement. Fatal. f66 ILLEGAL USE OF .ALL ·. IGNORED. In the VALUE clause, an ALL numeric 11teral is detected. ALL is ignored by the compiler. f67 CONDITION NAME MISSING OR INVALID. 88 IGNORED. The condition-name in an 88 level entry is either missing or invalid. The entire entry is ignored. H-6 DIAGNOSTIC ERROR MESSAGES i1i TWO INDEXED KEYS START AT SAME OFFSET IN RECORD. The leftmost character position of the RECORD KEY or ALTERNATE RECORD KEY data-name corresponds to the leftmost character position of some other RECORD KEY or ALTERNATE RECORD KEY data-name. The clause is ignored. i11 .REDEFINES. ON i1 LEVEL IN FILE SECTION INVALID. The REDEFINES clause is present on the i1 level in the FILE SECTION, where redefinition is implicit. REDEFINES clause is ignored. i12 PICTURE IGNORED FOR INDEX ITEM. An item defined as USAGE INDEX has a PICTURE clause. The PICTURE clause is ignored. i13 NONNUMERIC PIC ON COMP ITEM. TREATED AS DISPLAY. An item defined with non-DISPLAY usage has a picture-s*:r ing with non-numeric characters. The stated usage is ignored. The item is treated as USAGE DISPLAY. i74 SUBSCRIPT OUT OF RANGE. ASSUME 1. A literal subscript is either less than 1 or greater than the maximum allowable value. A value of 1 is used. i1s .STATUS. OMITTED FROM .FILE STATUS .· ASSUMED. The FILE STATUS clause has incorrect syntax. The error is ignored. i16 SOME FILES WITHOUT POSIT. NO. IN MUL. FILE TAPE. A MULTIPLE FILE TAPE clause contains file-names with POSITION clauses. Not all the file-names contain POSITION clauses. The error is ignored. File searching during OPEN will find the file. i11 .MULTIPLE FILE TAPE. SYNTAX ERROR. A MULTIPLE FILE TAPE clause contains a syntax error. The clause is ignored. ii~ OPERAND CLASSES IN CONFLICT. One or more operands in a statement have an invalid class. Fatal. H-7 DIAGNOSTIC ERROR MESSAGES lgl POSSIBLE RECEIVING FIELD TRUNCATION. A MOVE statement results in right-hand truncation of the receiving field value. This is not an error and is ignored. 112 TOO FEW SOURCE FIELDS FOR ADD .GIVING .. At least two valid source operands must appear in an ADD . · · GIVING statement. Fatal. 113 .EXIT. WAS NOT THE ONLY VERB IN PARAGRAPH. An EXIT statement is not the only statement in a paragraph. The EXIT statement is ignored. 114 SENDING ITEM INVALID OR OMITTED. A MOVE statement contains an invalid or missing sending operand. Fatal. 115 SENDING ITEM NOT FOLLOWED BY .TO .. A MOVE statement does not have the keyword TO following the sending operand. Fatal. 116 RECEIVING ITEM INVALID OR OMITTED. A MOVE statement has no valid receiving operand. Fatal. li7 INVALID CLASS FOR DESTINATION FIELD. The rece1v1ng operand of an ADD or SUBTRACT statement is not numeric or numeric edited. Fatal. 11~ RELATIVE OR RECORD KEY OR STATUS NAME INVALID. The name referenced in a RELATIVE KEY, RECORD KEY, ALTERNATE RECORD KEY or FILE STATUS clause is invalid. The clause is ignored. 111 .STOP. SYNTAX ERROR. The STOP statement is not followed by a literal or the word RUN. Fatal. 112 .SIZE ERROR. STATEMENT INCORRECT. The word ERROR is not found in the ON SIZE.clause. Fatal. 113 .PROCEDURE DIVISION. OMITTED. The source program does not contain a PROCEDURE DIVISION. Fatal. H-8 DIAGNOSTIC ERROR MESSAGES 114 INTERMEDIATE RESULT TOO LARGE. HIGH ORDER TRUNC. An arithmetic statement calls for an intermediate result in excess of 18 digits. The intermediate result is truncated on the left to 18 digits, with a possible loss of high-order, non-zero digits at execution time. 115 INTERMEDIATE RESULT TOO LARGE. LOW ORDER TRUNC. An arithmetic expression calls for an intermediate result in excess of 18 digits. The intermediate result is truncated on the right to 18 digits, with a possible loss of low-order, non-zero digits at execution time. 116 .DIVISION. OMITTED AFTER .PROCEDURE .· The word DIVISION is missing in the PROCEDURE DIVISION header. The error lS ignored. 117 TERMINATOR MISSING AFTER DIVISION HEADER. The period terminator is missing from a division header. The error is ignored. 12~ LITERAL INCOMPATIBLE WITH ATTEMPTED USAGE. Conversion of a literal from one form to another has failed. Fatal. 121 DATANAME MUST FOLLOW .INTO. IN THIS STATEMENT. A valid data-name is not present following INTO in a STRING or UNSTRING statement. Fatal. 122 NUMERIC SUBJECT OR OBJECT MUST BE INTEGER. A numeric, non-integer subject or object is invalid in the context of this relation condition. Fatal. 123 OPERANDS CONFLICT IN .SET ..· TO. STATEMENT. A SET ... TO statement references invalid operands. Fatal. 124 OPERANDS CONFLICT IN .SET ··· BY. STATEMENT. A SET .·· BY statement references invalid operands. Fatal. H-9 DIAGNOSTIC ERROR MESSAGES 125 ILLEGAL FILENAME LITERAL OR FILENAME DATANAME. An ASSIGN statement _or a VALUE OF ID statement contains an invalid file specification or data-name. The statement is ignored. 126 INVALID SUBJECT OF SIGN CONDITION. The subject of a sign condition is not a valid arithmetic expression. Fatal. 127 ITEM IN TABLE MAY NOT BE USED AS A SUBSCRIPT. A data item used as a subscript is itself a table element. Fatal. 13~ .POINTER. MUST FOLLOW .WITH. IN THIS STATEMENT. A STRING or UNSTRING statement has an invalid WITH POINTER phrase. Fatal. 131 RELATIVE KEY INVALID FOR THIS FILE. IGNORED. A RELATIVE KEY clause has been applied to a file that does not have RELATIVE organization. The RELATIVE KEY clause is ignored. 132 SUBJECT OR OBJECT OMITTED IN RELATION CONDITION. The subject or object is omitted in a COBOL relation condition. Fatal. 133 UNIDENTIFIABLE WORD FOUND IN SUBSCRIPT. A subscript list contains a word that is neither a data-name nor a numeric literal. The remainder of the list or sentence is ignored. Fatal. 134 INVALID SUBJECT OR OBJECT IN RELATION CONDITION. The subject or object of a relation condition is an invalid operand. Fatal. 135 SUBSCRIPTS OMITTED. ASSUME VALUE OF 1. A reference to a table item contains no subscript list. Literal subscripts of 1 are supplied as defaults. 136 RELATIVE INDEX LITERAL OUT OF RANGE. INDEX USED. The literal value of a relative index causes an out-of-range reference to the table. The literal value is ignored, and only the index-name is used. H-10 DIAGNOSTIC ERROR MESSAGES 137 SUBSCRIPTS GIVEN WHERE NOT REQUIRED. IGNORED. A reference is made to a non-table item, and a subscript list follows the reference. The subscript list is ignored. 14i TOO FEW SUBSCRIPTS GIVEN. ASSUME 1 FOR REST. A reference to a table item contains a subscript list with too few subscripts. Default literal subscripts of 1 are supplied for missing subscripts. 141 TOO MANY SUBSCRIPTS GIVEN. IGNORE EXCESS. A reference to a table item contains too many subscripts in the subscript list. Extra subscripts are ignored. 142 SUBJECT AND OBJECT USAGE MUST MATCH. A relation condition between non-numeric operands requires the same usage for both operands. Fatal. 143 ARITHMETIC EXPRESSION REQUIRED IN THIS CONTEXT. An arithmetic expression is required in the context of the COBOL statement being compiled. The compiler has failed to recognize the arithmetic expression in this context. Fatal. 144 CONDITION EXPRESSION REQUIRED IN THIS CONTEXT. A condition expression is required in the context of the COBOL statement being compiled~ The compiler has failed to recognize the condition expression in this context. Fatal. 145 ILLEGAL OPERAND FOUND IN COBOL EXPRESSION. An invalid data-name or literal has been found in the COBOL statement being compiled. The class or USAGE of the data item may be invalid here as a reference in an expression. Fatal. 146 OPERATOR IS MISSING IN COBOL EXPRESSION. An operator is omitted in the specification of this COBOL expression. The compiler cannot recognize this expression as a syntactically valid COBOL expression. Fatal. H-11 DIAGNOSTIC ERROR MESSAGES 147 ABSOLUTE VALUE STORED. A negative value has been supplied for an unsigned numeric item. The absolute value of the numeric literal is stored in the item. 15~ ILLEGAL WORD FOUND AFTER .NOT. IN EXPRESSION. The compiler has detected an illegal expression operator following a NOT keyword in the COBOL expression being compiled. Fatal. 151 VERB FOUND IN AREA A. ALLOWED. A statement begins in Area A. The error is ignored. 152 EXPECTED .RELATIVE KEY. DATANAME NOT DEFINED. The data-name given in a RELATIVE KEY clause has not been defined in the Data Division. 153 .LINAGE. CLAUSE DATAITEM IS TOO LONG. A data item named in a LINAGE clause is declared in the Data Division with more than four decimal integer positions of precision. 154 PROCEDURE NAME DUPLICATES DATA NAME. ALLOWED. A procedure name is identical to a data-name. The error is ignored, since there can be no ambiguity in legal references. 155 STATEMENTS FOLLOWING .GO. CAN NEVER BE EXECUTED. A statement follows an unconditional GO statement. The statements following the GO are compiled, but cannot be executed. 156 NONSEQUENTIAL FILE MAY NOT BE OPTIONAL. The SELECT statement may specify OPTIONAL only on files with sequential organization. The word OPTIONAL is ignorede 157 FILE HAS IO CONTROL CLAUSE CONFLICTS. A file is given conflicting clause specifications in the I-0-CONTROL paragraph of the INPUT-OUTPUT SECTION. H-12 DIAGNOSTIC ERROR MESSAGES 16j FILE REQUIRES REL. KEY. TREATED AS SEQ. ACCESS. A file with relative organization and random or dynamic access has no RELATIVE KEY clause. The access mode is changed to SEQUENTIAL. 161 INVALID INDEX DATAITEM USE IN RELATIONAL. The compiler detects the invalid use of an index data item reference as the subject or object of a relation condition. Fatal. 162 UNKNOWN WORD. SCAN TO NEXT CLAUSE. An unknown word is encountered when a clause keyword is expected. All words are ignored up to the next valid clause. 163 CLAUSE DUPLICATED. SECOND OCCURRENCE USED. A SELECT statement contains two occurrences of the same clause. The second occurrence is used. 164 NO FD FOR THIS SELECT. The file-name supplied in a SELECT statement is not further described in an FD in the Data Division. The SELECT statement is ignored, causing the file-name to become undefined. 165 DIFFERENT SAME REC. AREAS FOR SAME AREA. The compiler detects a conflict between the SAME RECORD AREA clause and the SAME AREA clause. 166 .READ. WITHOUT .INVALID KEY ·· AT END. OR .USE. A READ statement contains no conditional clauses, and the file being read has no USE procedure applied to it. Fatal. 167 IO CONTROL CLAUSE HAS FILE WITH NO .SE;ECT. An I-0-CONTROL clause references a file-name that was not named in a SELECT statement. The file-name is ignored in the I-0-CONTROL statement. 17~ INTEGER OMITTED IN .RESERVE ·· DEFAULT ASSUMED. A RESERVE clause fails to specify the number of buffer areas to reserve. The clause is ignored, and a default of one area for SEQUENTIAL and RELATIVE, or two areas for INDEXED, is supplied. H-13 DIAGNOSTIC ERROR MESSAGES 171 INVALID SUBJECT OF CLASS CONDITION. The subject of a class condition is not a data item with an acceptable class. Fatal. 172 VALUE EXCEEDS FIELD CAPACITY. TRUNCATED. A numeric literal supplied by a VALUE clause exceeds the length of the field~ The value is right truncated and stored in the ·field. 173 NO DATA DIVISION STATEMENTS PROCESSED. The Data Division contains no valid entries. This is an observation only. 174 INVALID GRP LEV NUM. REST OF RECORD IGNORED. A level-number is encountered that terminates a previous group item, but does not match any previous group item's level-number. All data entries are skipped until the next i1 level, level indicator or header. 175 INVALID PROCEDURE NAME DEFINITION IN AREA A. The compiler detects source text in Area A of the Procedure Division that does not conform to the rules for the definition of a legitimate paragraph or section name. Source text found in Area A of the Procedure Division is interpreted by the compiler as a user attempt to define a new paragraph or section name. The compiler supplies a system-defined procedure name and proceeds with the processing of the source line text containing the invalid Area A text. The system-defined procedure name is transparent and, thus, inaccessible to the user. 176 MISSING QUOTE ON CONTINUE LINE. QUOTE ASSUMED. A non-numeric literal is continued, but the first non-space character is not a quote. The error is ignored by assuming a quote in front of the first non-space character. 177 COMPARISON OF LITERALS IS NOT PERMITTED. A relation condition has a literal as both subject and object. Fatal. H-14 DIAGNOSTIC ERROR MESSAGES 2iJJ COPY IGNORED WITHIN LIBRARY TEXT. A COPY statement is encountered within library text. The COPY statement is ignored. 2i1 INVALID FILENAME ON COPY. COPY IGNORED. A COPY statement supplies a file specification that is invalid. The COPY statement is ignored. 2i2 COPY FILENAME NOT FOUND. A COPY statement supplies a valid file specification, but the file cannot be found on the specified device. The COPY statement is ignored. 2)J3 PERIOD OMITTED AFTER .DECLARATIVES ·· The word DECLARATIVES is not followed by a period. The error 2~4 .DECLARATIVES. OMITTED FROM .END. STATEMENT. The word END is not followed by DECLARATIVES. END DECLARATIVES is assumed. 2~5 PERIOD OMITTED AFTER .END DECLARATIVES .. The words END DECLARATIVES are not followed by a period. The error is ignored. 2i6 SOURCE PROGRAM ENDS IN DECLARATIVES. The end of the source program occurs in the Declaratives area. Fatal. 2i1 DATANAME MUST FOLLOW .WITH POINTER. PHRASE. A STRING or UNSTRING statement contains an invalid WITH POINTER phrase. Fatal. 2l)J .OVERFLOW. MUST FOLLOW .ON. IN THIS STATEMENT. A STRING or UNSTRING statement contains an invalid ON OVERFLOW phrase. Fatal. 211 ILLEGAL SENDING FIELD DATANAME IN .UNSTRING. The sending field of an UNSTRING statement has an invalid class. Fatal. 212 ILLEGAL SYNTAX IN .UNSTRING. STATEMENT. An UNSTRING statement has invalid syntax. Fatal. H-15 DIAGNOSTIC ERROR MESSAGES 213 MULTIPLE SIGN CLAUSES ON THIS ITEM. More than one SIGN clause appears in a data description. (SEPARATE must follow LEADING or TRAILING.) The second clause is used. 214 ILLEGAL SYNTAX IN COBOL EXPRESSION. The compiler detects a syntax error of a general nature in the COBOL expression being compiled. Fatal. 215 SIGN CLAUSE ON NONNUMERIC ITEM. A SIGN clause appears in a non-numeric data description. The SIGN clause is ignored. 216 SIGN CLAUSE APPLIED TO NONDISPLAY ITEM. A SIGN clause appears in a numeric data description with usage other than DISPLAY. The SIGN clause is ignored. 217 SIGN CLAUSE APPLIED TO UNSIGNED DATAITEM. A SIGN clause appears in a numeric data description that has no "S" in its PICTURE string. The SIGN clause is ignored. 22~ ILLEGAL DELIMITING DATA ITEM IN .UNSTRING. An UNSTRING statement references an invalid delimiter. Fatal. 221 .ALL. FIGURATIVE CONSTANT ILLEGAL IN .UNSTRING. An UNSTRING statement contains an ALL literal reference. Fatal. 222 ILLEGAL RECEIVING DATANAME IN .UNSTRING. An UNSTRING statement references a receiving data item that is invalid. Fatal. 223 .DELIMITED. CLAUSE REQUIRED IN THIS .UNSTRING. An statement contains no DELIMITED BY clause. Fatal. 224 DATANAME MUST FOLLOW .DELIMITER IN. PHRASE. An UNSTRING statement contains a DELIMITER IN phrase with an illegal reference. Fatal. H-16 DIAGNOSTIC ERROR MESSAGES 225 ILLEGAL DATANAME FOLLOWS .DELIMITER IN. PHRASE. An UNSTRING statement contains a DELIMITER IN phrase referencing a data item that is invalid. Fatal. 226 DATANAME MUST FOLLOW .COUNT IN. PHRASE. An UNSTRING statement contains a COUNT IN phrase with an illegal reference. Fatal. 227 ILLEGAL DATANAME FOLLOWS .COUNT IN. PHRASE. An UNSTRING statement contains a COUNT IN phrase that references an invalid data item. Fatal. 23~ DATANAME MUST FOLLOW .TALLYING IN. PHRASE. An UN STRING statem.. ent m~TTVT~~ _ ...... _ _ _ _ ~ ~ ...... ..LOJ.JJ.J.l..J..L'll\,;J .1:-'LlL.Qi:><:: W.J..1..LJ contains an a reference. Fatal. 231 ILLEGAL DATANAME FOLLOWS .TALLYING IN. PHRASE. An UNSTRING statement contains a TALLYING phrase referencing a data item that is invalid. Fatal. 232 DATANAME MUST FOLLOW .INSPECT. VERB. A valid data-name reference does not follow the INSPECT keyword. Fatal. 233 ILLEGAL DATANAME FOLLOWS .INSPECT. VERB. An INSPECT statement references a data item that is invalid. Fatal. 234 ILLEGAL DATANAME PRECEDES .FOR. IN .INSPECT. An INSPECT ... TALLYING statement references a tally data item that is invalid. Fatal. 235 .FOR. OMITTED IN .INSPECT. STATEMENT. An INSPECT ·.. TALLYING statement has invalid syntax. Fatal. 236 DATANAME MUST FOLLOW .TALLYING. PHRASE. An INSPECT .·· TALLYING statement does not reference a tally data-name. Fatal. 237 ILLEGAL WORD FOLLOWS .FOR. IN .INSPECT. An INSPECT .·· TALLYING statement does not state a valid search condition. Fatal. H-17 DIAGNOSTIC ERROR MESSAGES 24~ DATAITEM OMITTED AFTER .ALL . . LEADING. OR .FIRST. An INSPECT statement does not reference a valid search argument. Fatal. 241 .ALL. FIGURATIVE CONSTANT ILLEGAL IN .INSPECT. An ALL literal appears in an INSPECT statement. Fatal. 242 ILLEGAL DATANAME FOLLOWS .ALL. OR .LEADING. An INSPECT statement does not reference a valid search argument. Fatal. 243 ILLEGAL DATANAME FOLLOWS .BEFORE. OR .AFTER. An INSPECT statement does not reference a valid delimiter in the BEFORE/AFTER phrase. Fatal. 244 ILLEGAL DATANAME FOLLOWS .BY. An INSPECT statement does not reference a valid replacement argument. Fatal. 245 ILLEGAL DATANAME PRECEDES .BY. An INSPECT statement does not reference a legal data-name or literal preceding the BY phrase. Fatal. 246 DATAITEM OMITTED IN .BEFORE. OR .AFTER. PHRASE. An INSPECT statement does not reference a legal data-name or literal after the BEFORE or AFTER phrase. Fatal. 247 ILLEGAL SYNTAX IN .INSPECT. STATEMENT. Both the TALLYING and REPLACING keywords are missing in the INSPECT statement. Fatal. 25~ .BY. MUST FOLLOW .CHARACTERS. IN REPLACING LIST. The INSPECT ·.. REPLACING statement must have CHARACTERS BY phrase completely specified. Fatal. 251 DATAITEM OMITTED AFTER .BY. IN .INSPECT. The INSPECT . . . REPLACING statement does not reference a legal data-name or literal after BY. Fatal. H-18 DIAGNOSTIC ERROR MESSAGES 252 DATAITEM FOLLOWING .BY. EXCEEDS 1 CHARACTER. In an INSPECT ·.. REPLACING statement, when: 1) the CHARACTERS BY phrase is specified, or 2) a figurative constant preceding the BY keyword of the ALL, LEADING, or FIRST phrase is specified, the data-name or literal after the BY keyword must be defined as one character in length. Fatal. 253 'DATAITEMS BEFORE AND AFTER .BY. UNEQUAL IN SIZE. In an INSPECT ··. REPLACING statement, the data items before and after the BY keyword of the ALL, LEADING, or FIRST phrase must be equal in length. Fatal. 254 .BEFORE. OR .AFTER. OPERAND EXCEEDS 1 CHARACTER. In an INSPECT ... REPLACING CHARACTERS BY C _ !..f...-....:..:....f. -'-o...m .... '-o.n.....f'--1 the data-name literal following the BEFORE or AFTER keyword must be one character in length. Fatal. 255 ILLEGAL WORD FOLLOWS .REPLACING. IN .INSPECT. A legal keyword was not recognized following REPLACING in the INSPECT statement. Fatal. 256 .BY. OMITTED AFTER REPLACING COMPARISON OPERAND. The keyword BY is omitted in LEADING, or FIRST phrase separates operands to be Fatal. the ALL, where it compared. 257 TOO MANY RIGHT PARENTHESES IN COBOL EXPRESSION. The compiler detects an excess of right parentheses in the COBOL expression being compiled. Parentheses must be specified in balanced pairs; that is, a left parenthesis must exist for each right parenthesis specified. Fatal. 26~ TOO MANY LEFT PARENTHESES IN COBOL EXPRESSION. The compiler detects an excess of left parentheses in the COBOL expression being compiled. Parentheses must be specified in balanced pairs; that is, a right parenthesis must exist for each left parenthesis specified. Fatal. 261 MISSING OPERAND IN ARITHMETIC EXPRESSION. An operand is omitted in a arithmetic expression. Fatal. COBOL H-19 DIAGNOSTIC ERROR MESSAGES 262 ILLEGAL OPERAND IN ARITHMETIC EXPRESSION. The compiler detects an illegal operand in a COBOL arithmetic expression. The class or usage of the operand may be invalid in the context as a reference in an arithmetic expression. Fatal. 263 NONINTEGER EXPONENT FOUND IN COBOL EXPRESSION. The compiler detects a non-integer, numeric exponent in a COBOL arithmetic expression. The arithmetic expression is considered invalid. Fatal. 264 SUBJECT OMITTED IN CLASS CONDITION. The compiler detects the omission of the subject in a NUMERIC or ALPHABETIC class condition. Fatal. 265 SUBJECT OMITTED IN SIGN CONDITION. The compiler detects the omission of the subject in a sign condition. Fatal. 266 OPERAND MISSING IN COMPLEX CONDITION. The compiler detects the omission of an operand in an AND or OR complex condition. Fatal. 267 INVALID OPERAND IN COMPLEX EXPRESSION. The compiler detects a complex condition operand that is not a simple condition, combined condition, or complex condition. Fatal. 27~ ILLEGAL SYNTAX IN NEGATED SIMPLE CONDITION. The compiler detects illegal syntax in a COBOL negated simple condition. Fatal. 271 INVALID NEGATED SIMPLE CONDITION. The compiler detects the application of the NOT keyword to an invalid simple condition. Fatal. 272 ILLEGAL SYNTAX IN .COMPUTE. STATEMENT. The compiler detects illegal syntax in a COMPUTE statement. The left side of the assignment symbol or the assignment symbQl itself may have been omitted. Fatal. H-20 DIAGNOSTIC ERROR MESSAGES 273 .AT END. ILLEGAL FOR RANDOM .READ. The file is specified with either ACCESS RANDOM or ACCESS DYNAMIC without the word NEXT being included in the READ statement. The AT END clause is treated as an INVALID KEY clause. 274 INVALID KEY ILLEGAL FOR SEQUENTIAL .READ. Either the file has ACCESS SEQUENTIAL or the READ statement contains the word NEXT. In either case, the INVALID KEY clause is illegal. It is treated as an AT END clause. 275 INDEX DATA ITEM ILLEGAL AS INDEX ON TABLE. An index data item is used as an index for a table. The index data item reference is ignored. A literal subscript of 1 replaces the index data item reference. 276 INDEX NAME NOT DEFINED FOR THIS TABLE. An index-name used in a subscript list either is not defined for this table or appears in the wrong logical position of the subscript list for this table. The index-name is ignored and a default value of 1 is assumed as the subscript. 277 RELATIVE INDEX IS INVALID. The literal component of a relative index is zero or less in value, or is an invalid word. Relative indexing is ignored and only the index-name is used. 3j~ PROGRAM NAME OMITTED AFTER .CALL. VERB. The program-name is omitted after the key word CALL. Fatal. 3jl LINAGE ~ OR LESS THAN FOOTING. The LINAGE clause must specify a page body of at least one line, and the page body size must be equal to or greater than the footing size specified in the FOOTING phrase. 3j2 FILE CLOSED BUT NOT OPENED. A CLOSE statement was encountered for a file that is not opened in this program. Fatal. H-21 DIAGNOSTIC ERROR MESSAGES 3j3 PRINT CONTROL ON NON SEQUENTIAL FILE. IGNORED. An APPLY PRINT-CONTROL clause references a file that does not have SEQUENTIAL organization. The file-name is ignored in the APPLY clause. 3j4 DATANAME OMITTED IN .KEY IS. PHRASE. The KEY IS phrase of the START statement is not followed by a data-name. The prime RECORD KEY data-name is assumed present. 3j5 SECTION OR PARAGRAPH NAME ·MISSING. The Procedure Division does not start with a section or paragraph name, or a section header is not followed by a paragraph name. Fatal. 3j6 .PROCEDURE. MISSING IN .USE. STATEMENT. ASSUMED. The keyword PROCEDURE is missing in the USE statement. It is assumed and processing is continued. 3j7 .START. WITHOUT .INVALID KEY. OR .USE. The INVALID KEY option is missing from the START statement, or no USE procedure is declared for the referenced file. Fatal. 31~ .WRITE. WITHOUT .INVALID KEY. OR .USE. The INVALID KEY option is missing from the WRITE statement, or no USE procedure is declared for the referenced file. Fatal. 311 DATA DIVISION MUCH TOO LARGE. Too much buffer space is being used for the files in this program. Too many files are declared to be OPEN simultaneously. Fatal. H-22 DIAGNOSTIC ERROR MESSAGES 312 .REDEFINES. SPECIFIES INVALID REDEFINITION. The compiler detects the invalid application of REDEFINES to a data description entry that contributes new character positions between the data description entry containing the REDEFINES clause and the item being redefined. Also, the source of error may be the definition of another data description entry with a lower level number appearing between the data description entry containing the REDEFINES clause and the item being redefined. The compiler ignores the REDEFINES clause and continues processing the data description entry. 313 ILLEGAL TO REDEFINE ANOTHER REDEFINITION. The REDEFINES clause specifies the redefinition of a data item whose data description entry contains a REDEFINES clause itself. The compiler ignores the REDEFINES clause and continues processing the data description entry. 314 ILLEGAL TO REDEFINE A COBOL TABLE. The REDEFINES clause specifies the redefinition of a data item whose data description entry contains an OCCURS clause. The compiler ignores the REDEFINES clause and continues processing the data description entry. 315 .REDEFINES. APPLIED'TO VARIABLE LENGTH DATAITEM. The compiler detects an application of the REDEFINES clause to a data item whose length is variable at run time because it has a subordinate data item whose data description entry contains an OCCURS DEPENDING ON clause. The application of the REDEFINES clause to such a data item is syntactically invalid. The compiler ignores the REDEFINES clause and continues processing the data description entry. 316 .OCCURS DEPENDING ON. ILLEGAL IN REDEFINITION. The compiler detects a redefinition that contains a data description entry declared with an OCCURS DEPENDING ON clause. The OCCURS DEPENDING ON clause causes the redefinition to contain a data item whose length is variable at run time. The DEPENDING ON phrase is ignored and processing continues. H-23 DIAGNOSTIC ERROR MESSAGES 317 PICTURE EXCEEDS 3j CHARACTERS. PIC X ASSUMED. The unexpanded PICTURE string exceeds 3j characters in length. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 32j FILENAME MUST FOLLOW .CLOSE VERB. The data item following the CLOSE verb was not a file-name. Fatal. 321 .NO. MUST FOLLOW .WITH. IT IS ASSUMED. The keyword NO is missing in the WITH NO REWIND phrase of the CLOSE statement. NO is assumed present. 322 .REWIND. MUST FOLLOW .NO. IT IS ASSUMED. The WITH NO REWIND phrase of the CLOSE statement must be completely specified. It is assumed present. 323 .REMOVAL. MUST FOLLOW .FOR. IT IS ASSUMED. The FOR REMOVAL phrase of the CLOSE statement must be completely specified. It is assumed present. 324 .LOCK. OMITTED AFTER .WITH. IT IS ASSUMED. The keyword WITH in a CLOSE statement is recognized but is not followed by one of the keywords NO or LOCK. The WITH LOCK phrase is assumed present. 325 DATANAME SPECIFIED WHERE FILENAME EXPECTED. The name used in an I/O verb to reference a file was not a file name but was some other data-name. Fatal. 326 FILENAME MUST FOLLOW MODE SPEC. IN .OPEN. The OPEN statement does not reference a valid file name where a file-name reference is expected. Fatal. 327 ILLEGAL MODE SPECIFIED AFTER .OPEN. VERB. One of the OPEN mode keywords INPUT, OUTPUT, I-0, or EXTEND is required immediately after the OPEN verb. Fatal. 33j .END. MUST FOLLOW .AT ·· IT IS ASSUMED. The keyword END was omitted in the AT END phrase of the READ statement. The AT END phrase is assumed present. H-24 DIAGNOSTIC ERROR MESSAGES 331 FILENAME MUST FOLLOW .READ. VERB. Either the file-name was omitted following the READ verb or the data item following the READ verb is not a valid file-name reference. Fatal. 332 DATANAME OMITTED AFTER .INTO. IN .READ. The data-name reference following the INTO keyword of the READ statement was omitted. Fatal. 333 RECORDNAME MUST FOLLOW .WRITE. OR .REWRITE. The i1 record-name reference immediately following the WRITE or REWRITE verb was omitted. Fatal. 334 STATEMENT IGNORED DUE TO ILLEGAL RECORDNAME. The data-name immediately following the WRITE or REWRITE verb is not a valid 11 record-name reference. Fatal. 335 .ADVANCING. OPTION OMITTED IN .WRITE. 1 ASSUMED. A data-name reference, numeric integer literal reference, or the keyword PAGE was not recognized in the BEFORE/AFTER ADVANCING phrase of the WRITE statement. A numeric integer literal value of 1 is assumed. 336 .EOP. MUST FOLLOW .AT .. IT IS ASSUMED. The keyword EOP was omitted in the AT EOP phrase of the WRITE statement. The AT EOP phrase is assumed present. 337 DATANAME OMITTED AFTER .FROM. The data-name reference following the FROM keyword of the WRITE or REWRITE statement was omitted. Fatal. 34i .ADVANCING. INTEGER TOO BIG. TRUNCATED TO 63. The numeric integer in the BEFORE/AFTER ADVANCING phrase of the WRITE statement is greater than 63. 63 is assumed. 341 .NO REWIND. ILLEGAL WITH .IO. OR .EXTEND. MODE. An OPEN statement with the I-0 or EXTEND mode specified cannot have the NO REWIND phrase also specified. Fatal. H-25 DIAGNOSTIC ERROR MESSAGES 342 ILLEGAL .ADVANCING. DATANAME. 1 IS ASSUMED The data-name in the BEFORE/AFTER ADVANCING phrase of the WRITE statement is not an elementary numeric integer data-name reference. A numeric integer literal value of 1 is assumed. 343 4 FILENAME MUST FOLLOW .DELETE. VERB. Either the file-name was omitted following the DELETE verb or the data item following the DELETE verb is not a v~lid file-name reference. Fatal. 344 FILENAME MUST FOLLOW .START. VERB. Either the file name was omitted following the START verb or the data item following the START verb is not a valid file name reference. Fatal. 345 .LESS. OMITTED AFTER .NOT. IN .START. ASSUMED. The keyword LESS is omitted after NOT in the relational condition of the START statement. LESS is assumed present. 346 DATANAME OMITTED IN .KEY IS. PHRASE. ASSUMED. The RELATIVE KEY data-name for the referenced file was omitted in the KEY IS phrase of the START statement. The RELATIVE KEY data-name is assumed present. 347 RELATIONAL WORD OMITTED AFTER .KEY IS. PHRASE. None of the relational keywords EQUAL, GREATER, or NOT was recognized following the KEY IS phrase of the START statement. Fatal. 35~ TERMINATOR IGNORED IN .IO CONTROL. PARAGRAPH. A clause is terminated by a period, but a header does not follow in Area A. The period is ignored. The compiler assumes it is still in the I-0-CONTROL paragraph. 351 TERMINATOR IGNORED IN .SPECIAL NAMES. PARAGRAPH A clause is terminated by a period, but is not followed by a header in Area A. The period is ignored, and the compiler continues processing the SPECIAL-NAMES paragraph. H-26 DIAGNOSTIC ERROR MESSAGES 352 .NATIVE. MISSING IN SPECIAL NAMES CLAUSE. The alphabet-name clause does not contain NATIVE or STANDARD-1. The alphabet-name clause is ignored. 353 SYNTAX ERROR IN .OBJECT COMPUTER. PARAGRAPH. The OBJECT-COMPUTER paragraph contains an unrecognizable word. The compiler scans over all words until a word is found in Area A. 354 TERMINATOR OMITTED IN .OBJECT COMPUTER. PARA. The OBJECT-COMPUTER paragraph is not terminated by a period. The compiler scans over all words until a word is found in Area A. 355 DATANAME FOLLOWING .KEY IS. PHRASE IS ILLEGAL. The data-name following the KEY IS phrase of the START statement is not a RECORD KEY associated with the referenced indexed file, nor is it subordinate to a RECORD KEY whose leftmost character position corresponds to its own leftmost character position. Fatal. 356 INVALID USAGE ON CONDITIONAL VARIABLE. The level 88 condition variable cannot be defined as USAGE INDEX. 357 ILLEGAL SEPARATOR IN COBOL STATEMENT. IGNORED. An illegal character was detected between two consecutive words of a COBOL statement. The illegal character is ignored. 36i ILLEGAL CHARACTER FOUND WITHIN A COBOL WORD. Illegal characters were found in an alphanumeric COBOL word, but not in an alphanumeric literal. The illegal characters are replaced by dollar signs in the internal representation of the COBOL word. 361 UNRECOGNIZABLE TEXT FOUND IN COBOL STATEMENT. In scanning the source text, the compiler was unable to recognize an alphanumeric COBOL word (a keyword or user-defined word), an alphanumeric literal, or a numeric literal. The error is not internally corrected and usually will cause further error messages. H-27 DIAGNOSTIC ERROR MESSAGES 362 COBOL WORD BEGINS WITH OR ENDS IN HYPHEN. In attempting to recognize a keyword or user-defined word, the compiler has detected that the COBOL word begins or ends with a hyphen. 363 NONNUMERIC LITERAL TOO LONG. TRUNCATED TO MAX. An alphanumeric literal greater tnan 132 characters in length is detected. The literal is truncated on the right, retaining the first 132 characters as the literal. 364 COBOL SOURCE LINE TOO LONG. TRUNCATED TO MAX. The indicated COBOL source line contains more than 65 characters in terminal format. The excess characters are ignored, and only those characters in the printed COBOL source line are retained. 365 .BY. OMITTED IN REPLACING OPTION. COPY IGNORED. The keyword BY was not found in a COPY ··· REPLACING statement. The statement is ignored. 366 TERMINATOR OMITTED IN .COPY. IT IS ASSUMED. The required period terminating the COPY statement is omitted. It is assumed present. 367 .LINAGE. CLAUSE DATANAME MUST BE AN INTEGER. A data-name referenced in the· LINAGE clause of the FILE SECTION is defined with decimal places in the WORKING-STORAGE SECTION. 37j .LINAGE.CLAUSE DATANAME MUST BE UNSIGNED. A numeric data-name referenced in the LINAGE clause of the FILE SECTION is defined as a signed data item in the WORKING-STORAGE SECTION. 371 POSSIBLE HIGH ORDER RECEIVING FIELD TRUNCATION. Truncation of high-order information during a MOVE or an arithmetic operation upon a receiving field is possible. This.is an observation only. H-28 DIAGNOSTIC ERROR MESSAGES 372 POSSIBLE LOW ORDER RECEIVING FIELD TRUNCATION. Truncation of low-order information during a MOVE or an arithmetic operation upon a receiving field is possible. This is an observation only. 373 PD HEADER NOT FOLLOWED BY AN AREA A WORD. The word following the PROCEDURE DIVISION header does not begin in Area A. The compiler scans over all words until a word is found in Area A. 374 OPEN OPTIONAL FILES ONLY IN .INPUT. MODE. An OPTIONAL file can be OPENed in INPUT mode only. The compiler assumes that the OPTIONAL file is OPENed in INPUT mode. 375 EXPECTED .FILE STATUS. DATANAME NOT DEFINED. A data-name referenced in a FILE STATUS phrase of a SELECT clause in the FILE-CONTROL paragraph is not defined in the WORKING-STORAGE SECTION of the DATA DIVISION. 376 EXPECTED .VALUE OF ID. DATANAME NOT DEFINED. The data=name referenced in a VALUE OF ID clause of an FD is not defined in the WORKING-STORAGE SECTION of the DATA DIVISION. Fatal. 377 EXPECTED .LINAGE. CLAUSE DATANAME NOT DEFINED. A data-name referenced in the LINAGE clause of the FILE SECTION is not defined in the WOR~ING-STORAGE SECTION of the DATA DIVISION. 4ii .RELATIVE KEY. DATANAME HAS INVALID CLASS. A data-name referenced in a RELATIVE KEY phrase of a SELECT clause in the FILE-CONTROL paragraph is defined with non-numeric class in the WORKING-STORAGE SECTION. 4il .RELATIVE KEY. DATANAME HAS INVALID CLASS. A data-name referenced in a RELATIVE KEY phrase of a SELECT clause must not be defined with INDEX usage in the WORKING-STORAGE SECTION. H-29 DIAGNOSTIC ERROR MESSAGES 4~2 .RELATIVE KEY. DATAITEM IS TOO LONG. A numeric integer data-name referenced in a RELATIVE KEY phrase is defined with more than eight digits of precision in the WORKING-STORAGE SECTION. 4,3 .RELATIVE KEY. DATANAME MUST BE AN INTEGER. A numeric data-name referenced in a RELATIVE KEY phrase is defined with decimal places in the WORKING-STORAGE SECTION. 4,4 .FILE STATUS. DATANAME HAS INVALID CLASS. A data-name referenced in a the FILE STATUS phrase of a SELECT clause must be defined in with DISPLAY usage in the WORKING-STORAGE SECTION. 4,5 .FILE STATUS. DATA NAME HAS INVALID USAGE. A data-name referenced in a FILE STATUS phrase of a SELECT clause is defined with DISPLAY USAGE in the WORKING-STORAGE SECTION. 4,6 LENGTH OF .FILE STATUS. DATAITEM IS ILLEGAL. An alphanumeric data-name referenced in a FILE STATUS phrase of a SELECT clause must be defined in the WORKING-STORAGE SECTION as an alphanumeric variable consisting of two characters. 4,7 .VALUE OF ID. DATANAME HAS INVALID CLASS. A data-name referenced in a VALUE OF ID clause of an FD is defined with non-alphanumeric class in the WORKING-STORAGE SECTION. 41~ .VALUE OF ID. DATANAME HAS INVALID USAGE. A data-name referenced in a VALUE OF ID clause of an FD must be defined with DISPLAY usage in the WORKING-STORAGE SECTION. 411 LENGTH OF .VALUE OF ID. DATAITEM IS ILLEGAL. An alphanumeric data-name referenced in a VALUE OF ID clause of an FD must be defined in the WORKING-STORAGE SECTION as an alphanumeric variable whose length, L, falls in the range 9<=L<=4~ characters. H-30 DIAGNOSTIC ERROR MESSAGES 412 .LINAGE. CLAUSE DATANAME HAS INVALID CLASS. A data-name referenced in the LINAGE clause of the FILE SECTION is defined with non-numeric class in the WORKING-STORAGE SECTION. 413 .LINAGE. CLAUSE DATANAME HAS INVALID USAGE. A data-name referenced in the LINAGE clause of the FILE SECTION must be defined with COMPUTATIONAL USAGE in the WORKING-STORAGE SECTION. 414 INVALID RECEIVING OPERAND IN .SET ·. IGNORED. A receiving operand of a SET statement is invalid. Fatal. 415 NO RECEIVING OPERAND SPECIFIED IN .SET .· No receiving operands are specified in a SET statementG FatalG 416 OMITTED OR ILLEGAL OPERAND AFTER .TO. IN .SET .. A SET statement has no valid sending operand. Fatal. 417 ILLEGAL SYNTAX IN .SET. STATEMENT. The words TO, UP or DOWN do not follow the rece1v1ng operands of a SET statement. Fatal. 42~ .BY. MUST FOLLOW .UP. OR .DOWN .. ASSUMED. The keyword BY does not follow the word UP or DOWN in a SET statement. BY is assumed present. 421 OMITTED OR ILLEGAL OPERAND AFTER .BY. IN .SET ·. The operand following the UP BY or DOWN BY phrase in a SET statement is invalid or omitted. Fatal. 422 NO OPERANDS SPECIFIED No operands were recognized following the keyword DISPLAY. Fatal. 423 SETTING INDEX NAME OUT OF RANGE . . SET. IGNORED. A SET statement is attempting to set an index name using a literal that is too large. Fatal. H-31 DIAGNOSTIC ERROR MESSAGES 424 .IF. TRUE PATH OMITTED. ASSUME .NEXT SENTENCE .. The true path code is omitted from the IF statement. NEXT SENTENCE is assumed as the true path of the IF statement. 425 CONFLICTING SIGN SYMBOLS IN PICTURE STRING. The compiler recognizes both the + and sign symbols in this PICTURE string. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 426 ZERO SUPPRESSION CONFLICTS IN PICTURE STRING. The compiler recognizes both the z and * zero suppression symbols in this PICTURE string. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 427 ILLEGAL CHARACTER IN THE PICTURE STRING. A character that is not in the PICTURE string character set is recognized in this PICTURE by the compiler. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 43~ .BLANK WHEN ZERO. CONFLICTS WITH ZERO SUPPRESS. A BLANK WHEN ZERO clause is recognized with a zero suppression field specified in the PICTURE string. The compiler ignores the BLANK WHEN ZERO clause and continues with its processing. 431 PARENTHESIZED SPECIFIER EXCEEDS 18 DIGITS. The specification contained inside the parentheses of a PICTURE string exceeds 18 digits in length. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 432 SPECIFIER MISSING INSIDE PARENTHESES. The specification contained inside parentheses of a PICTURE string is missin9. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. H-32 DIAGNOSTIC ERROR MESSAGES 433 ILLEGAL SYMBOL PRECEDES LEFT PAREN. IN PICTURE. The compiler recognizes an s, v, CR, DB, or "." character preceding a left parenthesis in a PICTURE string. The error is ignored and processing continues. 434 TERMINATOR OMITTED IN .NOTE. PARAGRAPH. The compiler detected a NOTE paragraph that does not end with a period. 435 INVALID OPERAND IN .VARYING. OR .AFTER. PHRASE. The expected operand is not a valid name reference in the VARYING or AFTER phrase of this PERFORM VARYING statement. Fatal. 436 INVALID OPERAND IN .FROM. OR .BY. PHRASE. The FROM or BY phrase of a PERFORM VARYING statement does not contain a valid operand reference. Fatal. 437 TOO MANY .AFTER. PHRASES IN .PERFORM. STATEMENT. The compiler detects more than two AFTER phrases in the PERFORM VARYING statement being compiled. Fatal. 44~ .FROM. OR .BY. OR .UNTIL. MISSING IN PERFORM. The compiler detects the omission of the keywords FROM, BY, or UNTIL in the PERFORM VARYING statement. Fatal. 441 ILLEGAL CONDITION EXPRESSION IN THE PERFORM. The compiler detects an invalid condition expression in the PERFORM statement. Fatal. 442 NONPOSITIVE LITERAL IN .FROM. OR .BY. PHRASE. The compiler detects a non-positive, numeric integer literal in this PERFORM statement. Fatal. 443 INVALID RELATION CONDITION IN .SEARCH ALL. The compiler detects either a syntax error or an invalid operand in the restricted form of a relation condition in the SEARCH ALL statement. Fatal. H-33 DIAGNOSTIC ERROR MESSAGES 444 NONINTEGER DATA CONFLICTS WITH INDEXNAME USAGE. The compiler detects a non-integer data item reference in a PERFORM VARYING statement in which the VARYING, AFTER, and/or FROM phrase contains an index-name reference. Fatal. 445 IMPLICIT REFERENCE TO BAD CONDITION VALUES. Through a reference to a condition-name, the compiler detects a reference to an associated condition-value that is improperly declared in the Data Division. Fatal. 446 IMPLICIT REFERENCE TO BAD CONDITION VARIABLE. Through a reference to a condition-name, the compiler detects that the associated condition-variable is improperly declared in the Data Division. Fatal. 447 TOO MANY NAMES IN COBOL PROGRAM. RECOMPILE. The COBOL program being compiled has too many data-names or procedure-names. This condition has caused a compiler table to overflow, aborting the compilation. The program should be recompiled using the "/SYM:N" switch to reserve more space for the compiler symbol tables. 45~ REFERENCE TO UNDEFINED DATANAME. IGNORED. The COBOL statement being compiled contains a reference to an undefined data-name. The compiler ignores the reference. This diagnostic may be issued in conjunction with other diagnostics for the erroneous statement. Fatal. 451 QUALIFIED REFERENCE ILLEGAL IN THIS CONTEXT. The compiler detects a qualified reference in a context in which an unqualified reference is required. The comoiler oermits the qualified reference in this context and continues with the compilation of the statement containing the reference. H-34 DIAGNOSTIC ERROR MESSAGES 452 QUALIFIER OMITTED IN QUALIFIED REFERENCE. A data-name is omitted after the keyword OF or IN in a qualified reference in the COBOL statement being compiled. The reference is ignored. This diagnostic may be issued in conjunction with other diagnostics for the statement in error. 453 TOO MANY QUALIFIERS IN QUALIFIED REFERENCE. The compiler detects more than 48 qualifiers in a qualified reference. The excess qualifiers are ignored in the reference. 454 UNDEFINED QUALIFIER IN QUALIFIED REFERENCE. The compiler detects a qualified reference in which a qualifier is a reference to an undefined data-name. The compiler ignores the entire qualified reference. This diagnostic may be issued in conjunction with other diagnostics for the erroneous statement containing the reference. 455 COBOL STATEMENT CONTAINS AMBIGUOUS REFERENCE. The compiler detects a reference to COBOL data that is not uniquely referenceable through qualification. The compiler uses a reference that satisfies the reference in the text of the COBOL program. This diagnostic may be issued in conjunction with other diagnostics for the statement in error. 456 DATANAME REFERENCE EXPECTED IN THIS CONTEXT. The compiler detects a reference to a data item that is not alphabetic, numeric, alphanumeric-edited, alphanumeric, or numeric-edited. The context of this reference requires that the reference be to one of these classes of data items. This diagnostic may be issued in conjunction with other diagnostics for the statement in error. 457 ILLEGAL REFERENCE DETECTED IN THIS CONTEXT. The compiler detects a reference to an item that is invalid in the context of its usage. This diagnostic may be issued in conjunction with other diagnostics for the statement in error. Fatal. H-35 DIAGNOSTIC ERROR MESSAGES 461 EXTRA OPENING QUOTE ON LITERAL IS IGNORED. The compiler detects a superfluous quote at the beginning of a non-numeric literal specification. The compiler ignores the extra quote and continues processing the non-numeric literal. 462 PROGRAM NAME MUST BE A NONNUMERIC LITERAL. The program-name literal following the key word CALL is not a nonnumeric literal. Fatal. 464 LITERALS ARE ILLEGAL IN ARGUMENT LIST OF .CALL ·· Literals are not allowed in the argument list of a CALL statement. Fatal. 465 ARGUMENT LIST OMITTED AFTER .USING. IN .CALL . . The required argument list is missing after the key word USING in the CALL statement. Fatal. 47~ ILLEGAL SYNTAX IN .CODE SET. CLAUSE. IGNORED. A valid alphabet-name reference is omitted in the CODE-SET clause. The compiler ignores the CODE-SET clause and continues to process the remainder of the FD. 471 DATANAME IN .KEY IS. PHRASE NOT ALPHANUMERIC. The data-name following the KEY IS phrase in a START statement referencing an indexed file must be alphanumeric. Fatal. 472 .RECORD KEY. DATAITEM LENGTH GREATER THAN 255. A data-name referenced in a RECORD KEY or ALTERNATE RECORD KEY phrase of a SELECT clause in the FILE-CONTROL paragraph must be defined in the FILE SECTION as an item whose length is less than or equal to 255. 473 DATANAME IN .KEY IS PHRASE IS SUBSCRIPTED OR INDEX. The data-name following the KEY IS phrase in a READ or START statement referencing an indexed file must not be subscripted or indexed. Fatal. H-36 DIAGNOSTIC ERROR MESSAGES 474 .RECORD KEY. DATAITEM MUST NOT BE A COBOL TABLE. A data-name referenced in a RECORD KEY or ALTERNATE RECORD KEY phrase of a SELECT clause in the FILE-CONTROL paragraph must not be defined in the FILE SECTION with an OCCURS clause or be subordinate to an item with an OCCURS clause. 475 .RECORD. OMITTED FROM .ALTERNATE RECORD. ASSUMED. The reserved word RECORD is missing from the ALTERNATE RECORD KEY clause. The error is ignored. 476 UNDEFINED .ALTERNATE RECORD KEY. DATANAME. The data-name given in an ALTERNATE RECORD K~Y clause has not been defined in the Data Division. 477 .ALTERNATE RECORD KEY. CLAUSES ARE SEPARATED. In the SELECT statement the ALTERNATE RECORD KEY clauses are interleaved among the other clauses. The ALTERNATE RECORD KEY clauses should follow one another with no intervening clauses. This error is ignored. sii LINKAGE SECTION ITEM APPEARS TWICE IN .USING ·· A LINKAGE SECTION data item must not appear more than once in the USING phrase of a PROCEDURE DIVISION USING header. Fatal. si1 ILLEGAL .SEGMENT-LIMIT. VALUE IGNORED. The segment-limit is not a numeric literal or is a numeric literal whose value is outside of allowed segment-limit range. si2 INTEGER 1 BEYOND AREA A TREATED AS LEVEL NUMBER. An i1 level item was detected beyond Area A and accepted as if in Area A. si3 MULTIPLE PICTURES FOR SAME ITEM. LAST USED. A data item has more than one PICTURE clause. The compiler used the last PICTURE clause specified. H-37 DIAGNOSTIC ERROR MESSAGES 5~4 CLOSING PARENTHESIS MISSING IN PICTURE. The right parenthesis is missing in the PICTURE string. The compiler uses the last four characters of the PICTURE string. 5~5 NOT A SUBPROGRAM .PROGRAM. IGNORED. An EXIT PROGRAM has been detected, but the COBOL program being compiled is not a subprogram. Because EXIT PROGRAM is meaningful only in a subprogram, the word PROGRAM is ignored, and the statement is treated as if it were a simple EXIT statement. 5~6 EXPANDED PICTURE STRING TOO LONG. PIC X ASSUMED. The expansion of a PICTURE string specification produces a string that exceeds implementation limitations. The compiler ignores the user-supplied PICTURE and treats the data item as if it had a "~ICTURE X" declaration. 5~7 SPECIFIER OMITTED BEFORE LEFT FAREN. IN PIC. The first character of a PICTURE string is a left parenthesis. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 51~ SECTION NO. GREATER THAN 49 TREATED AS 49. A segment number greater than 49 follows the word SECTION. The segment is treated as if it were 49. 511 INVALID ITEM LENGTH IN PARENTHESES OF PICTURE. The parenthesized length specifier in a PICTURE contains non-numeric characters. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 512 VALUE CLAUSE NOT ALLOWED IN LINKAGE SECTION. The VALUE clause cannot appear in data items in the LINKAGE SECTION. The only place the VALUE clause can appear in the LINKAGE SECTION is in a condition name definition. 513 OPERAND IN .USING. MUST BE LINKAGE SECTION ITEM. Only level ~l or 77 LINKAGE SECTION items may appear in the USING phrase of a PROCEDURE DIVISION header. Fatal. H-38 DIAGNOSTIC ERROR MESSAGES 514 MULTIPLE FLOATING FIELDS IN NUMERIC EDIT ITRM. The PICTURE string contains multiple floating fields. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 515 MULTIPLE ZERO SUPPRESS FIELDS IN PICTURE STRING. Multiple zero suppression fields are detected in a PICTURE string. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 516 ZERO SUPPRESSION ILLEGAL WITH FLOATING FIELD. The PICTURE string contains both floating and zero suppression fields. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 517 ILLEGAL SYNTAX IN PICTURE STRING. The PICTURE string is not specified correctly according to the rules of PICTURE string syntax. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 52~ MULTIPLE DECIMAL POINTS IN PICTURE. The PICTURE string contains multiple decimal point specifications (V's, P's, or periods). The compiler ignores the user-supplied PICTURE and. treats the data item as alphanumeric with a "PICTURE X" declaration. 521 OPERAND IN USING MUST BE LEVEL i1 OR 77. Only level i1 or 77 LINKAGE SECTION items may appear in the USING phrase of a PROCEDURE DIVISION header. Fatal. 522 INVALID USAGE. IGNORED. The USAGE clause contains an invalid word. The compiler ignores the entire USAGE clause. H-39 DIAGNOSTIC ERROR MESSAGES 523 MULTIPLE USAGE CLAUSES. LAST USED. The defined data-name has multiple USAGE clauses specified. The last USAGE clause specified is used by the compiler. 524 MULTIPLE OCCURS CLAUSES. LAST USED. The defined aaca-name has multiple OCCURS clauses specified. The compiler uses the last OCCURS clause specified. 525 OCCURS SPECIFICATION ERROR. 1 ASSUMED. The integer entry of the OCCURS clause is either non-numeric or non-integer or is not in the range 1 to 4i95. The compiler assumes an integer value of 1. 526 DATANAME OMITTED IN DATA DESCRIPTION ENTRY. The data-name declaration is omitted after a level-number in the data description entry. The compiler supplies a system-defined name and proceeds with the processing of the data description entry. The system-defined name is transparent and, thus, inaccessible to the user. 527 INVALID INDEX NAME. IGNORED. The compiler did not recognize a valid index name in the INDEXED BY phrase. The compiler ignores the INDEXED BY phrase. 53i USAGE OPTION NOT YET IMPLEMENTED. IGNORED. The compiler detected COMP-1 in the USAGE clause. This option is not implemented and is ignored. The default USAGE of DISPLAY is used by the compiler. 531 TERMINATOR OMITTED AFTER DATAITEM DESCRIPTION. A data description entry in the DATA DIVISION .is not terminated by a.period. The compiler assumes the period is present and continues processing. H-40 DIAGNOSTIC ERROR MESSAGES 532 INVALID SIGN IN NUMERIC PICTURE. The sign character S is detected in a position other than the leading character position of a numeric PICTURE string. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 533 PICTURE CLAUSE OMITTED ON ELEMENTARY ITEM. An elementary item is recognized with its PICTURE clause omitted in the description. The compiler treats the data item as alphanumeric with a PICTURE X declaration. 534 NUMERIC ITEM EXCEEDS 18 DIGIT MAX. TRUNCATED. A numeric field is defined in this PICTURE with more than 18 digits of precision. The numeric field is truncated to 18 digits. 535 COMP ITEM EXCEEDS 18 DIGITS. ASSIGN 4 WORDS. A COMPUTATIONAL data item exceeds 18 digits in its specification. The compiler truncates it and allocates four words for its run-time storage. 536 INDEX ITEM HAS ILLEGAL CLAUSE. The compiler recognized a JUSTIFIED, SYNCHRONIZED, VALUE, PICTURE, or SIGN clause on a data-item description that has INDEX USAGE. The compiler ignores the offensive clause. 537 NUMERIC VALUE FOR DISPLAY ITEM. IGNORED. The VALUE clause specifies numeric value initialization for a non-numeric data-item that is defined with DISPLAY USAGE. The VALUE clause is ignored. 54~ VALUE TOO LONG. TRUNCATED. The non-numeric literal in the VALUE clause is longer than the associated data-item. The literal is truncated onthe right to fit in the storage allocated to the data-item. 541 CLAUSE DUPLICATION. IGNORED. This clause has been previously recognized for this item. The duplicate clause is ignored. H-41 DIAGNOSTIC ERROR MESSAGES 542 INVALID WORD IN .BLANK WHEN ZERO .· IGNORED. The keyword ZERO was not recognized in the BLANK WHEN ZERO clause. The entire clause is ignored. 543 LEVEL NUMS UNEQUAL IN .REDEFINES. CLAUSE IGNORED. A REDEFINES clause attempts to redefine ~wu items of different level numbers. The REDEFINES clause is ignored. 544 POSSIBLE OVERLAP OF DEPENDING ON ITEM AND TABLEe The DEPENDING ON item and variable length table are both defined in the LINKAGE SECTION. Because LINKAGE SECTION items are associated with data items appearing in a CALL statement, there is no way at compile time to ensure that the DEPENDING ON items and table do not overlap. The COBOL run-time OTS does not check for overlap of the DEPENDING ON item and the table during execution. It is, therefore, your responsibility to ensure that overlap does not occur. 545 LEVEL ILLEGAL AFTER 77. TREATED AS ~l. An invalid level number (~2-49) follows a 77 level item. The 77 level item is treated as an ~l level item. This action can cause further diagnostics if it is not a valid group item. 546 PERIOD OMITTED AFTER .EXIT PROGRAM. The words EXIT PROGRAM are not followed by a period. The error is ignored. 547 .EXIT PROGRAM. NOT LASTSTMT OF SENTENCE. An EXIT PROGRAM statement appears in a sequence of statements within a sentence. But, it is not the last statement. All of the statements following it are compiled, but can never be executed. 55~ REDEFINING LENGTH SHOULD MATCH ORIGINAL LENGTH. The length of a non-ii level REDEFINES item is not the same as the length of the item it REDEFINES. The new length is used. 551 REDEFINITION OF .OCCURS. ITEM. IGNORED. Items with OCCURS cannot be redefined. REDEFINES is ignored. H-42 DIAGNOSTIC ERROR MESSAGES 552 PROCESSING RESUMES AFTER BAD FD. Prior to issuing this message, the compiler discovered bad syntax in the FD of the FILE SECTION. The compiler at that time issued an error message identifying the syntax error. Then the compiler attempted to recognize another FD, the WORKING-STORAGE SECTION header or th~ PROCEDURE DIVISION. Upon recognizing one of these three language elements, the compiler issues this diagnostic to indicate that normal processing has resumed. 553 INVALID CLAUSE KEYWORD. OTHER CLAUSES SKIPPED. A reserved clause keyword was expected at this point in a data item description entry of the DATA DIVISION, but was not recognized by the compiler. The compiler skips to the next level number data item description. 554 INVALID WORD FOLLOWING .VALUE ·· IGNORED. The VALUE clause contains an invalid word for this data description. The entire VALUE clause is ignored. 555 VALUE CONFLICT. GROUP VALUE USED. The VALUE clause assigns a value to an item subordinate to a group item that also has a VALUE clause. The subordinate VALUE clause is ignored. 556 LEVEL NUMBER OMITTED. ITEM IGNORED. The level number has been omitted in a data-item description. All source text is ignored up to and including the next period. 557 NO VALUE AFTER CONDITION NAME. 88 IGNORED. An 88 level condition-name has no VALUE clause specified. The entire 88 level data-item is ignored. 56i SYNTAX ERROR IN SWITCH CLAUSE. CLAUSE IGNORED. The SWITCH clause has a syntax error in its specification. The compiler ignores the entire clause. H-43 DIAGNOSTIC ERROR MESSAGES 561 .NO. MISSING IN ADVANCING PHRASE. ASSUMED. The keyword NO is missing in the ADVANCING phrase of the DISPLAY statement. NO is assumed present. 562 .ADVANCING. MISSING AFTER .NO ·. ASSUMED. The keyword ADVANCING is missing in the ADVANCING phrase of the DISPLAY statement. ADVANCING is assumed present. 563 DUPLICATE DATANAME DECLARATION DETECTED. In the ENVIRONMENT DIVISION and/or DATA DIVISION, a data-name is defined that is not uniquely referenceable even with complete qualification. 564 ILLEGAL PARAGRAPH HEADER ID DIV. PAR IGNORED. An illegal paragraph header appears in the IDENTIFICATION DIVISION. The paragraph is ignored. 565 ILLEGAL PARAGRAPH HEADER ENV DIV. PAR IGNORED. An illegal paragraph header appears in the ENVIRONMENT DIVISION. The paragraph is ignored. 566 NUMERIC LITERAL ILLEGAL ON GROUP ITEM. IGNORED. A numeric literal is illegal in the VALUE clause of a group item. The VALUE clause is ignored. 567 .ENVIRONMENT. NOT FOLLOWED BY .DIVISION .· The word ENVIRONMENT is not followed by the word DIVISION. DIVISION is assumed present. 57j TERMINATOR MISSING AFTER .DATA DIVISION. HEADER. The DATA DIVISION header is not followed by a period. The period is assumed present and processing continues. 571 TERMINATOR MISSING AFTER PARAGRAPH HEADER. A paragraph header in the IDENTIFICATION or ENVIRONMENT DIVISION is not terminated by a period. The period is assu~ed present and processing continues. H-44 DIAGNOSTIC ERROR MESSAGES 572 .RENAMES. SPECIFIES STORAGE OVERLAP ON RIGHT. In processing the RENAMES clause, the compiler detects the condition in which the end of the storage allocated to the data-name after the THRO keyword is not to the right of the end of the storage allocated to the data-name after the RENAMES keyword. The compiler ignores the entire RENAMES data description entry. 573 .SECTION. OMITTED FROM SECTION HEADER. An ENVIRONMENT DIVISION section name is not followed by the word SECTION. The error is ignored. 574 TERMINATOR MISSING AFTER SECTION HEADER. An ENVIRONMENT DIVISION section header is not terminated by a period. The error is ignored. 6ii ILLEGAL LEVEL NUMBER. TREAT AS i1. This level number is not an jl-49, 66, 77, or 88 level number. The level number is assumed to be i1. 6il TERMINATOR MISSING AFTER ENV DIV HEADER. The ENVIRONMENT DIVISION header is not terminated by a period. The period is assumed present and processing continues. 6i2 .DATA. NOT FOLLOWED BY .DIVISION. The word DATA is not followed by the word DIVISION. DIVISION is assumed present. 6j3 ENVIRONMENT DIVISION HEADER OMITTED. The program contains no ENVIRONMENT DIVISION header. The compiler resumes processing at the next paragraph header. 6j4 UNRECOGNIZABLE COBOL PROGRAM FORMAT. ABORT. The compiler is unable to recognize the reserved word IDENTIFICATION as the first word required in a COBOL source program. Failure to recognize this required reserved word may be due to one of the following reasons: (!)IDENTIFICATION is, in fact, omitted as the first word of the source file, (2) the user is attempting to compile a H-45 DIAGNOSTIC ERROR MESSAGES COBOL source program in conventional format without specifying the ~onventional format- switch, or (3) the user is attempting to compile a file that is not a COBOL source program. The compiler issues a string of diagnostics and then aborts the compilation. 6j5 .IDENTIFICATION. NOT FOLLOWED BY .DIVISION .. The word IDENTIFICATION is not followed by the word DIVISION. DIVISION is assumed present. 6j6 TERMINATOR OMITTED AFTER .ID DIVISION. HEADER. The IDENTIFICATION DIVISION not terminated by a period. is assumed present and continues. header is The period processing 6j7 .PROGRAMID. EXPECTED AFTER DIVISION HEADER. The IDENTIFICATION DIVISION header is not followed by the PROGRAM-ID paragraph. The error is ignored and processing continues. 6lj TERMINATOR OMITTED AFTER .PROGI~. PARA HEADER. The PROGRAM-ID paragraph-name is not terminated by a period. The period is assumed present and processing continues. 611 INVALID PROGRAM NAME IN .PROGRAM ID. PARAGRAPH. The program name of the PROGRAM-ID paragraph contains an invalid character or exceeds the maximum length. The error is ignored and processing continues. 612 TOO MANY FILES FOR LONS OR TEMPORARY SPACE. The compiler has discovered either that more than 3j files are declared in the program or that more than 3j SAME RECORD AREA clauses are specified in the program. The compiler imposes a limit of 3j in both cases, because the associated compiler and/or object time table space is exhausted. 613 INVALID WORD SUSPENDS PROCESSING. SCAN FORWARD. An unidentifiable word is found where a verb is expected. The compiler scans to a verb, period, or word in Area A. H-46 DIAGNOSTIC ERROR MESSAGES 614 PROCESSING RESTARTS ON VERB. Due to a previous syntax error, the compiler scanned forward for the next verb, period, or Area A word at which to resume compilation. The compiler recognized a verb and resumes normal compilation at this point. This message is an observation only. 615 PROCESSING RESTARTS ON PROCEDURE NAME. Due to a previous syntax error, the compiler scanned forward for the next verb, period, or Area A word ~t which to resume compilation. The compiler recognized an Area A word and resumes compilation at this point. This message is an observation only. 616 PROCESSING RESTARTS AFTER TERMINATOR. Due to a previous syntax error, the compiler scanned forward for the next verb, period, or Area A word at which to resume compilation. The compiler recognized a period and resumes normal compilation on the word following the period. This is an observation only. 617 .IDENTIFICATION. KEYWORD NOT IN AREA A. The compiler detects that the IDENTIFICATION keyword is not in Area A. The compiler ignores the error and continues processing. 62~ PARAGRAPH TERMINATOR ASSUMED OMITTED. A paragraph was terminated without a period. The period is assumed and processing continues. 621 .LINAGE. INVALID FOR THIS FILE. CLAUSE IGNORED. The LINAGE clause must not be specified for a file that has RELATIVE or INDEXED organization. The LINAGE clause is ignored. 622 TERMINATOR MISSING AFTER PROCEDURE NAME. A section or paragraph name is not terminated by a period. The period is assumed present and processing continues. H-47 DIAGNOSTIC ERROR MESSAGES 623 .ELSE DOES NOT HAVE ASSOCIATED .IF .. IGNORED. The word ELSE has no associated IF statement. The ELSE is ignored. 624 VERB EXPECTED TO FOLLOW ELSE · · . ELSE. IGNORED. A sentence ends with the word ELSE. The ELSE is ignored. 625 .JUSTIFY. WITH NUMERIC OR EDITED ITEM. IGNORED. The JUSTIFIED clause must not be specified for a numeric or numeric-edited data item. The JUSTIFIED clause is ignored. 626 .BLANK WHEN ZERO. ILLEGALLY SPECIFIED. IGNORED. The BLANK WHEN ZERO clause must be specified only for a numeric or numeric-edited data item. The clause is ignored. 627 INVALID OR MISSING DATANAME AFTER .REDEFINES .· The compiler detects the omission of a valid data-name reference following the keyword REDEFINES. The compiler ignores the REDEFINES clause and continues processing the data description entry. 63~ .REDEFINES. MUST FOLLOW DATA NAME. IGNORED. The REDEFINES keyword appears in the wrong position of a data description entry. The REDEFINES clause is ignored. 631 DEPTH OF NESTED .IF. EXCEEDS LIMIT. A nested IF statement has exceeded the maximum depth of 3~ levels. The compiler ignores nesting beyond this depth. 632 DUPLICATE PROCEDURE NAME DETECTED. In the Procedure Division, a paragraph or section-name is defined that is not uniquely referenceable even with qualification= 633 REFERENCE TO UNDEFINED PARAGRAPH NAME. In the Procedure Division, an explicit qualified reference is made to a paragraph-name that is undefined in the section specified by the qualifier. H-48 DIAGNOSTIC ERROR MESSAGES 634 FILENAME LITERAL TOO LONG. TRUNCATED. A file specification in the ASSIGN clause exceeds 4~ characters in length. It is truncated to 4~ characters. 635 ILLEGAL SYNTAX IN .GO TO. STATEMENT. The compiler detects illegal syntax in the GO TO statement. Fatal. 636 INVALID INTEGER OR DATANAME. In the LINAGE clause, the compiler failed to recognize a non-negative integer literal or a numeric integer data-name. This phrase of the LINAGE clause is ignored. · GO HAS MULTIPLE PROCEDURE NAMES · A GO TO statement without the ON phrase has more than one procedure-name. Fatal. 64j INVALID WORD FOLLOWS .DATA DIVISION. The word following the DATA DIVISION header either does not start in Area A or is not one of the reserved words FILE, WORKING-STORAGE! LINKAGE, or PROCEDURE. The compiler skips all source text until one of the keywords FILE, WORKING-STORAGE, LINKAGE, or PROCEDURE is recognized. 641 INVALID WORD IN FILE SECTION. SCAN FORWARD. An invalid word was detected in the FILE SECTION where the keyword FD is expected. The compiler skips all source text until one of the keywords FD, WORKING-STORAGE, LINKAGE, or PROCEDURE is recognized. 642 .OMITTED LABELS IGNORED WITH .VALUE OF ID. The LABEL RECORDS ARE OMITTED clause is ignored if VALUE OF ID is specified for a file. STANDARD labels are assumed. Warning. 643 .SECTION. EXPECTED AFTER HEADER WORD. The keyword SECTION is omitted after the word FILE, WORKING-STORAGE, OR LINKAGE SECTION. It is assumed present and processing continues. H-49 DIAGNOSTIC ERROR MESSAGES 644 TERMINATOR EXPECTED AFTER SECTION HEADER. The FILE SECTION, WORKING-STORAGE SECTION, or LINKAGE SECTION header is not terminated by a period. The period is assumed and processing continues. 646 .OF. OR .ID. MISSING IN .VALUE OF ID .· One or both of the keywords OF or ID is omitted in the VALUE OF ID clause. Their presence is assumed and processing continues. 647 ILLEGAL WORD IN AREA A. SCAN FORWARD. In the WORKING-STORAGE SECTION, an ~l or 77 level number or the PROCEDURE keyword was expected in Area A, but was not recognized. The compiler skips all source text until one of the three expected language elements is recognized in Area A. 65~ GROUP LEVEL .VALUE. DISALLOWED. The VALUE clause on this group item is not permitted because a subordinate elementary item has a non-DISPLAY usage specified or has a SYNCHRONIZED clause specified. The group VALUE clause is ignored. 651 REFERENCED LINKAGE SECTION ITEM NOT ID .PD. USING ·· This LINKAGE SECTION item has been referenced in the PROCEDURE DIVISION. However, neither this item nor the level ~l to which it is subordinate appeared in the PROCEDURE DIVISION USING phrase. Only those LINKAGE SECTION items appearing in the PROCEDURE DIVISION USING phrase, or items subordinate to them, may be referenced in the PROCEDURE DIVISION of a COBOL program. Fatal. 652 NON-SEQ FILE IN .MULTIPLE. FILE TAPE. CLAUSE. In the I-0 CONTROL paragraph, the MULTIPLE FILE TAPE clause is specified for a file whose organization is not SEQUENTIAL. The MULTIPLE FILE TAPE clause is ignored for this file. 653 .VALUE. CLAUSE ILLEGAL IN FILE SECTION. A VALUE clause is specified for a data description entry given in the FILE SECTION. The VALUE clause is ignored. H-50 DIAGNOSTIC ERROR MESSAGES 654 SYNTAX ERROR IN CURRENCY CLAUSE. The alphanumeric literal expected in the CURRENCY SIGN clause of the SPECIAL-NAMES paragraph is omitted. The clause is ignored and the currency sign defaults to the dollar sign. 655 ILLEGAL CURRENCY SIGN. The alphanumeric literal in the CURRENCY SIGN clause is not allowed as the currency sign either because the literal is longer than one character or because it is an invalid COBOL currency sign. The CURRENCY SIGN clause is ignored, and the currency sign defaults to the dollar sign. 656 SPECIALNAMES CLAUSE INVALID. An unrecognizable word appears in a position where a SPECIAL-NAMES paragraph clause keyword is expected. All source text is skipped until the next keyword is recognized. 657 SYNTAX ERROR IN DECIMALPOINT CLAUSE. The keyword COMMA is omitted in the DECIMAL-POINT IS COMMA clause of the SPECIAL-NAMES paragraph. The clause is ignored. 66i .AFTER. MISSING IN .USE. STATEMENT. ASSUMED. The keyword AFTER is omitted in the USE statement. AFTER is assumed present and processing continues. 661 NO .ERROR. OR .EXCEPTION. IN .USE. ASSUMED. One of the keywords ERROR or EXCEPTION is omitted in the USE statement. The missing keyword is assumed present and processing continues. 662 NO KNOWN CLAUSES IN SPECIALNAMES. The SPECIAL-NAMES paragraph contains no valid clauses. This is an observation only. 663 REDUNDANT .USE. COVERAGE. PREV . . USE. IGNORED. Multiple USE statements have referenced the same file. The last USE statement specified is then applied to the referenced file. Fatal. H-51 DIAGNOSTIC ERROR MESSAGES 664 UNKNOWN OPEN MODE IN .USE. STATEMENT. An unrecognizable OPEN mode option was specified in the USE statement. Fatal. 665 GROUP ITEM HAS BEEN CALLED FILLER. A FILLER item cannot have any elementary items subordinate to it. The compiler replaces the FILLER declaration with a system-defined name and proceeds with the processing of the newly-named group item. The system-defined name is transparent and inaccessible to the user. 666 MISSING ENVIRONMENT DIVISION. The program does not contain an ENVIRONMENT DIVISION. The compiler skips to the DATA DIVISION and continues processing. 667 DIVISION BY ZERO. The divisor of a DIVIDE statement is a literal of zero value. The error is ignored. 67~ VALUE NOT PERMITTED WITH THIS ITEM. A VALUE clause is recognized in a data description entry that contains a REDEFINES or an OCCURS clause. The VALUE clause is ignored. 671 INVALID CONSTANT OR LITERAL FOLLOWING .ALL ·· The reserved word ALL is not followed by a non-numeric literal or a figurative constant. ALL is ignored and processing continues. 672 BAD FILENAME IN .USE. STATEMENT. An unrecognizable word appears where a file-name is expected in the USE statement. Fatal. 673 FILE NOT CLOSED. The referenced file was opened, but there was no CLOSE statement detected for this file in the program. H-52 DIAGNOSTIC ERROR MESSAGES 674 SUBJECT OF .ALTER. IS SECTION NAME. The ALTER statement references a section name. Only paragraph names may be altered. If this statement is reached during execution, the program will be aborted. 675 FILE COVERED BY CONFLICTING USE PROCEDURE. There was more than one conflicting USE procedure specified for the referenced file. Fatal. 676 DATA DIVISION EXCEEDS ADDRESS RANGE. The maximum DATA DIVISION size is 65,535 bytes. Fatal. 677 SUPPLIED VALUE INVALID FOR NUM ITEM. IGNORED. The VALUE clause specifies invalid value initialization for a numeric data item. The compiler ignores the VALUE clause. 711 FILE ACCESSED BY VERB REQUIRING REL. OR IDX ORG. A file whose organization is SEQUENTIAL is referenced by the START or DELETE verbs or by an I/O verb that has the INVALID KEY clause specified. In all these cases, the referenced file must have RELATIVE or INDEXED organization. Fatal. 711 FILE ACCESSED BY VERB REQ. SEQUENTIAL ORG. A file whose organization is RELATIVE or INDEXED is referenced by an I/O verb that has the AT EOP or ADVANCING clauses specified. The referenced file must have SEQUENTIAL organization. Fatal. 712 VERB NOT IMPLEMENTED. An ANS 1974 COBOL verb appears that is not implemented in this release of the compiler. The compiler scans to another verb, period, or word in Area A. 714 OCCURS ILLEGAL FOR 11 OR 77 ITEM. IGNORE. An OCCURS clause is specified for an 11 or 77 level data-name. The compiler ignores the OCCURS clause. 715 .ACCEPT FROM. OBJECT NOT IN SPECIALNAMES. The mnemonic-name used in the ACCEPT statement was not defined in the SPECIAL-NAMES paragraph. Fatal. H-53 DIAGNOSTIC ERROR MESSAGES 7g6 ACCEPT IDENTIFIER INVALID. The word following the ACCEPT verb is not a data-name or is a data-name that has non-DISPLAY usage or invalid class. Fatal. 7g7 VERB OR COND. CLAUSE CONFLICTS WITH FILE ACCESS. There is a conflict between the ACCESS MODE of the referenced file and the I/O verbs ~nd/or condition clauses that reference this file. Fatal. 7lg DATANAME AFTER .GO DEPENDING. INVALID. The word following the DEPENDING ON phrase of the GO TO statement is not a data-name or is a data-name that has INDEX usage. Fatal. 711 INVALID CLASS OF DATANAME AFTER .GO DEPENDING. The data-name following the DEPENDING ON phrase of the GO TO statement is not a numeric data-name or is a numeric, non-integer data-name. Fatal. 712 .DISPLAY UPON. OBJECT NOT IN SPECIALNAMES. The mnemonic-name used in the DISPLAY statement was not defined in the SPECIAL-NAMES paragraph. Fatal. 713 .DISPLAY. OPERAND IS INVALID. A data item in the DISPLAY statement has invalid class or USAGE. 714 MISSING OR INVALID OPERAND FOR ARITHMETIC VERB. One of the operands of an arithmetic statement is either missing or invalid. n-~-1 ra~ai. 715 MISSING OR INVALID SOURCE OPERAND. The source operand is missing following an arithmetic verb. Fatal. 716 MISSING OR INVALID DESTINATION OPERAND~ 717 .GIVING. REQUIRED AFTER .DIV ... BY. The GIVING phrase INTO is missing in a DIVIDE ·.. BY statement. Fatal. H-54 DIAGNOSTIC ERROR MESSAGES 72i .GIVING. REQUIRED AFTER LITERAL OPERAND. The GIVING phrase is required if the second operand of an ADD, DIVIDE, MULTIPLY, or SUBTRACT statement is a literal. Fatal. 721 .BY. MISSING IN .MULTIPLY. The keyword BY is missing in a MULTIPLY statement. Fatal. 722 .BY. OR .INTO. MISSING FROM aDIVIDE. One of the keywords BY or INTO is missing from the DIVIDE statement. Fatal. 723 .FROM. MISSING IN .SUBTRACT. The keyword FROM is missing from the SUBTRACT statement. Fatal. 724 FILE NEEDS DYNAMIC ACCESS FOR .READ NEXT ·. In a READ NEXT statement, the referenced file must have ACCESS MODE IS DYNAMIC specified in the FILE-CONTROL paragraph. Fatal. 725 BAD PROCEDURE NAME IN .PERFORM .. A missing or invalid procedure name is recognized in the PERFORM statement. Fatal. 726 ILLEGAL OPERAND OF .TIMES. OPTION OF .PERFORM ·. The TIMES operand of the PERFORM statement is not a numeric integer data-name or numeric integer literal. The compiler assumes a value of 1 for the TIMES operand. 727 .TIMES. MISSING FROM .PERFORM .· ASSUMED. The PERFORM statement does not contain the keyword TIMES but does contain the iteration value required to execute the PERFORM correctly. The keyword TIMES is assumed present. 73~ PROCEDURE NAME OMITTED IN .ALTER .· A valid procedure-name was not recognized in the ALTER statement. Fatal. H-55 DIAGNOSTIC ERROR MESSAGES 731 ILLEGAL .ALTER. DUE TO MISSING .TO ·. The keyword TO was not recognized in the ALTER statement. Fatal. 732 FILE HAS VAR. SIZE RECS . . READ INTO. ILLEGAL. It is illegal for the READ INTO statement to reference a file that has multiple record descriptions of different lengths. Fatal. 733 FILE ACCESSED BY VERB REQUIRING .LINAGE. A file that did not have a LINAGE clause in its specification is accessed by an I/O verb. Fatal. 734 .DELETE. OR .REWRITE. WITHOUT INV. KEY OR USE. A DELETE or REWRITE statement without the INVALID KEY phrase references a file for which there is no USE procedure. Fatal. 735 OPEN MODE OR NO READ PROHIBITS REWRITE OR DELETE. A DELETE or REWRITE statement references a file that was not OPENed in the proper mode or that has no READ statement referencing it in the program. Fatal. 736 .START. CONFLICTS WITH OPEN MODE. A START statement references a file that was not opened in the proper mode. Fatal. 737 .WRITE. CONFLICTS WITH OPEN MODE. A WRITE statement references a file that was not opened in the proper mode. Fatal. 74j .READ. CONFLICTS WITH OPEN MODE. A READ statement references a file that is only opened in OUTPUT or EXTEND mode. Fatal. 741 USE NOT IN DECLAR. OR NOT FOLLOWING SECTION NAME~ The USE statement is not in the DECLARATIVES section of the PROCEDURE DIVIqION or is not immediately following a section name inside the DECLARATIVES. Fatal. H-56 DIAGNOSTIC ERROR MESSAGES 742 MORE THAN 255 ALTERNATE KEYS. IGNORED. The maximum of 255 ALTERNATE KEYS has been exceeded. The clause is ignored. 743 INTEGER IN SWITCH CLAUSE INVALID OR OMITTED. A SWITCH clause of the SPECIAL-NAMES paragraph either contains an invalid numeric integer or has omitted the integer in its specification. A SWITCH clause integer must be in the decimal range l<=n<=l6. The SWITCH clause is ignored. 744 .IS. OMITTED IN SPECIALNAMES. ASSUMED PRESENT. The required keyword IS is omitted in a clause of the SPECIAL-NAMES paragraph. IS is assumed present and processing continues. 745 DEVICE MNEMONIC OMITTED IN SPECIALNAMES. A valid device mnemonic-name is not recognized in one of the CONSOLE, LINE-PRINTER, CARD-READER, PAPER-TAPE-READER, or PAPER-TAPE-PUNCH clauses of the SPECIAL-NAMES paragraph. All source text is skipped until the next recognizable keyword. 746 TERMINATOR OMITTED IN SPECIALNAMES. The SPECIAL-NAMES paragraph is not terminated by a period. The period is assumed present and processing continues. 747 SUBJECT OF .ALTER. NOT .GO TO .. ALTER IGNORED. The paragraph referenced by an ALTER statement does not contain a GO TO statement as its first statement. The ALTER statement is ignored. 75i KEYWORD OMITTED IN .SWITCH. CLAUSE. One of the keywords OFF or ON is omitted in the SWITCH clause of the SPECIAL-NAMES paragraph. The SWITCH clause is ignored. 751 CONDITION NAME MISSING IN .SWITCH. CLAUSE. A valid condition-name is not recognized in the SWITCH clause of the SPECIAL-NAMES paragraph. The SWITCH clause is ignored. H-57 DIAGNOSTIC ERROR MESSAGES 752 .CR. OR .DB. NOT AT RIGHT END OF PICTURE. The PICTURE symbol CR or DB does not appear at the right end of the PICTURE string. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" DECLARATION. 753 , · CR. "T-.. V~ T"\.,... · J.JO · USED WITH SIGNED ITEM. Both the PICTURE symbols, CR or DB, and a sign, + or , appear in the same PICTURE. The compiler ignores the user-supplied PICTURE and treats the data item as alphanumeric with a "PICTURE X" declaration. 754 MULTIPLE DEFINITION OF SWITCH. FIRST USED. Multiple definitions of a COBOL switch are detected in the SPECIAL-NAMES paragraph. All but the first definition of SWITCH are ignored. 755 .SENTENCE. ASSUMED AFTER .NEXT. The keyword NEXT is not followed by the keyword SENTENCE. SENTENCE is assumed present and processing continues. 756 SUBSCRIPT NOT NUMERIC INTEGER. A data-name used as a subscript is not numeric in class. A default value of 1 is assumed as the subscript. 76~ ILLEGAL SYNTAX IN .DIVIDE. STATEMENT. The compiler detects illegal syntax in the DIVIDE statement. Fatal. 761 INDEXED FILE REQUIRES .RECORD KEY. PHRASE. Self explanatory. 762 RECORD KEY INVALID FOR THIS FILE. The RECORD KEY clause is valid only for indexed files. 763 .ALT RECORD KEY. INVALID FOR FILE. IGNORED. The ALTERNATE RECORD KEY clause is valid only for indexed files. 764 READ-AHEAD. OR. WRITE-BEHIND. NOT SUPPORTED. The APPLY READ-AHEAD and APPLY WRITE-BEHIND clauses are not supported in this version of the compiler. The APPLY clause is ignored. H-58 DIAGNOSTIC ERROR MESSAGES 765 INTEGER INVALID IN. RESERVE AREA. CLAUSE. The number of buffer areas reserved by the RESERVE clause is invalid. The clause is ignored, and a default of one area for SEQUENTIAL and RELATIVE or two areas for INDEXED is supplied. 766 BAD VALUE IN BLOCK CONTAINS CLAUSE. The numeric literal in the BLOCK clause is less than the sum of the record size, the record header size, and the bucket header size. The BLOCK CONTAINS clause is ignored. 767 VALUE IN. BLOCK CONTAINS. CLAUSE IS ROUNDED UP. The numeric literal in the BLOCK clause is not a multiple of 512. The value is rounded up to the next even multiple of ~., ..... ;:).!. ~. 77i EXPECTED .RECORD KEY. DATANAME NOT DEFINED. The data-name in a RECORD KEY clause has not been defined in the DATA DIVISION. 771 .RECORD KEY. DATANAME HAS INVALID CLASS. A data-name referenced in a RECORD KEY or ALTERNATE RECORD KEY phrase of a SELECT clause in the FILE-CONTROL paragraph is defined with non-alphanumeric class in the FILE SECTION. 772 .RECORD KEY. DATA ITEM CANNOT BE VARIABLE LENGTH. A data-name referenced in a RECORD KEY or ALTERNATE RECORD KEY phrase of a SELECT clause in the FILE-CONTROL paragraph is defined in the FILE SECTION as an item whose size is variable. 773 .RECORD KEY. ITEM NOT DEFINED IN RECORD OF FILE. A data-name referenced in a RECORD KEY or an ALTERNATE RECORD KEY phrase of a SELECT clause is not defined in the record description of the associated file. 774 FILE ACCESSED BY VERB REQUIRING INDEXED ORG. A file whose organization is SEQUENTIAL or RELATIVE is referenced by the READ verb that has the KEY IS data-name phrase specified. The referenced file must have INDEXED organization. Fatal. H-59 DIAGNOSTIC ERROR MESSAGES 775 .KEY IS. PHRASE INVALID FOR SEQUENTIAL .READ. Either the file has ACCESS SEQUENTIAL or the READ statement contains the word NEXT. In either case the KEY IS data-name phrase is illegal. Fatal. 776 INVALID DATANAME IN .KEY IS. PHRASE. The K~Y ~~ phrase of the READ s~acement was not followed by a data-name. Fatal. 777 .KEY IS. PHRASE NOT FOLLOWED BY RECORD KEY. The data-name following the KEY IS phrase of the READ statement is not a RECORD KEY or ALTERNATE RECORD KEY for the referenced file. The RECORD KEY 1,,, data-name is assumed. VARIABLE OCCURRENCES TABLE MUST END RECORD. A COBOL table declared with the DEPENDING ON phrase can be followed in the record only by data description entries whose level-numbers are greater than the level-number of this table entry. The compiler ignores the remainder of the record descriptor from the point where the error is detected. Fatal. 1,,1 .ASCENDING. OR .DESCENDING. DATANAME EXPECTED. A user-defined data-name was expected, but not found, in the ASCENDING KEY IS or DESCENDING KEY IS phrase. 1,,2 RENAMED DATAITEMS NOT IN CURRENT RECORD. The data items specified after the RENAMES keyword (that is, the data items being renamed) are defined outside of the current record description. The compiler ignores the entire RENAMES data description entry. 1,,3 MAXIMUM OCCURRENCES NOT GREATER THAN MINIMUM. In a variable occurrence table declaration, the integer following the keyword TO (that is, the maximum) must be greater than the integer following the keyword OCCURS (that is, the minimum) . The compiler assumes the maximllm value to be one greater than the minimum value. H-60 DIAGNOSTIC ERROR MESSAGES 1~~4 .DEPENDING. IS OMITTED IN THE .OCCURS. CLAUSE. In a variable occurrence table declaration, the keyword DEPENDING has been omitted. The compiler ignores the remainder of the OCCURS clause and treats the table declaration as an ordinary COBOL table. 1~~5 A DATANAME MUST FOLLOW THE .DEPENDING. KEYWORD. In a variable occurrence table declaration, a valid data-name is not found following the keyword DEPENDING. The compiler ignores the remainder of the OCCURS clause and treats the table declaration as an ordinary COBOL table. iii6 .OCCURS DEPENDING. SUBORDINATE TO AN .OCCURS. The compiler detects a table declaration with a DEPENDING ON phrase subordinate to a group item that has an OCCURS clause. The compiler ignores the DEPENDING ON phrase and treats the declaration as an ordinary COBOL table. 1~~7 MAXIMUM NO. TABLE OCCURRENCES MUST BE POSITIVE. In a variable occurrence table declaration, the integer following the keyword TO (that is, the maximum) must be greater than zero. The compiler assumes the maximum value to be one greater than the integer value following the keyword OCCURS (that is, the minimum) . l~l~ EXPECTED .DEPENDING ON. DATANAME NOT DEFINED. The data-name referenced in a DEPENDING ON phrase was not defined in the DATA DIVISION. Fatal. 1~11 EXPECTED .ASCENDING KEY. DATANAME NOT DEFINED. The data-name referenced in an ASCENDING KEY phrase was not defined in the DATA DIVISION ..Fatal. 1~12 EXPECTED .DESCENDING KEY. DATANAME NOT DEFINED. The data-name referenced in a DESCENDING KEY phrase was not defined in the DATA DIVISION. Fatal. H-61 DIAGNOSTIC ERROR MESSAGES ljl3 .DEPENDING ON. DATANAME NOT A NUMERIC INTEGER. The data-name referenced in a DEPENDING ON phrase was not declared as a numeric integer in the DATA DIVISION. Fatal. ljl4 .RENAMES. APPLIED TO AN INVALID LEVEL OF DATA. The RENAMES clause specifies the renaming of data items whose level number is jl, 66, 77, or 88. The compiler ignores the entire RENAMES data description entry. ljl5 .DEPENDING ON. DATANAME DETECTED WITHIN TABLE. The compiler detects a data-name, that follows a DEPENDING ON phrase and that defines the current number of occurrences in a variable occurrence table, to have its storage allocated within the range of the table. Fatal. ljl6 .OCCURS. CLAUSE ON A TABLE KEY DATANAME. The compiler detects the presence of an OCCURS clause on a data item that has been declared as an ASCENDING or DESCENDING KEY. Fatal. 1~17 .SEARCH ALL. TABLE DOES NOT HAVE KEYS. The table being searched by a SEARCH ALL statement must have the ASCENDING KEY or DESCENDING KEY phrase specified in its declaration. Fatal. lj2~ IMPERATIVE STATEMENT EXPECTED DURING .SEARCH. A period or a non-imperative statement was found where the SEARCH statement environment is expecting an imperative statement. Fatal. 1~21 KEYS SPECIFIED FOR .SEARCH ALL. NOT DENSE. When a key is referenced for the SEARCH ALL statement, all preceding keys in the KEY clause of the table declaration must also be referenced. Fatal. 1~22 .WHEN. EXPECTED BUT NOT FOUND IN .SEARCH. The compiler expected but failed to recognize the WHEN keyword while compiling the SEARCH statement. Fatal. 1~23 THE KEYWORD .WHEN. ILLEGAL IN THIS CONTEXT. The compiler detects the presence of the keyword WHEN outside the environment of the SEARCH statement. Fatal. H-62 DIAGNOSTIC ERROR MESSAGES ii24 THE KEYWORD .SEARCH. ILLEGAL IN THIS CONTEXT. While compiling a SEARCH statement, the compiler detects the presence of another SEARCH statement. The second SEARCH statement is detected at a point where an imperative statement is expected. Fatal. li2s KEY MUST BE SUBSCRIPTED BY FIRST INDEX OF TABLE. The SEARCH ALL statement requires that the key referenced on the left side of the simple condition must be subscripted by the first index name of the table being searched. Fatal. li26 THE KEYWORD .SENTENCE. EXPECTED AFTER .NEXT ·. The keyword SENTENCE was not detected after the NEXT keyword during the compilation of a SEARCH statement. Fatal. li27 TABLE NAME NOT FOUND AFTER .SEARCH. VERB. The compiler failed to recognize a valid table data item after the keyword SEARCH or SEARCH ALL. Fatal. i~3~ INVALID TABLE REFERENCE IN .SEARCH. STATEMENT. The table data item reference following the SEARCH or SEARCH ALL verbs must have both the INDEXED BY and the OCCURS clauses specified in its declaration. Fatal. li3l DATANAME EXPECTED AFTER .VARYING. IN .SEARCH. No data-name reference was found after the VARYING keyword in the SEARCH statement being compiled. Fatal. li32 .VARYING. ITEM MUST BE INDEX OR INTEGER. The data-name reference following the VARYING keyword must be an index data item, an index-name, or an elementary, numeric, integer data-name reference. Fatal. 1~33 .SEARCH ALL. DATA ITEM IS NOT A KEY. The data item referenced on the left side of the SEARCH ALL simple condition must be declared as an ASCENDING or DESCENDING KEY. Fatal. H-63 DIAGNOSTIC ERROR MESSAGES 1034 DATA ITEM NOT A KEY FOR THIS .SEARCH. TABLE. The data item referenced on the left side of the SEARCH ALL simple condition is not a key for the table being searched. Fatal. 1035 .RENAMES. SPECIFIES RENAMING OF A COBOL TABLE. The RENAMES clause specifies the renaming of an item that has an OCCURS clause in its declaration or is subordinate to another item having an OCCURS clause. The compiler ignores the entire RENAMES data description entry. 1036 .RENAMES. APPLIED TO VARIABLE LENGTH DATAITEM. The compiler detects an application of the RENAMES clause to a range of data items that contains a data item whose length is variable at run-time because is has a subordinate data item whose data description entry contains an OCCURS DEPENDING ON clause. The compiler ignores the entire RENAMES data description entry. 1037 DATANAME OMITTED AFTER 66 LEVEL NUMBER. The data-name declaration is omitted after a 66 level number. The compiler ignores the entire RENAMES data description entry. 1040 .RENAMES. OMITTED IN LEVEL 66 DESCRIPTION ENTRY. The RENAMES keyword is omitted in a level 66 data description entry. The compiler ignores the entire level 66 data description entry. 1041 SEARCH KEY NOT SUBORDINATE TO TABLE. The compiler detects an ASCENDING or DESCENDING data-name key that is not defined as a data item subordinate to the associated SEARCH table. 1042 INVALID OR MISSING DATANAME AFTER .RENAMES .· The data-name is missing after the RENAMES keyword or, if present, is not recognized as a valid data item that was previously defined. The compiler ignores the entire RENAMES data description entry. H-64 DIAGNOSTIC ERROR MESSAGES 1~43 .OCCURS. ITEM NOT ALLOWED BETWEEN TABLE AND KEY. The compiler detects a data item declared with an OCCURS clause "sandwiched" between the declaration of another COBOL table and its associated SEARCH key. lg44 .RENAMES. SPECIFIES INVALID NOMENCLATURE RANGE. In processing the RENAMES clause, the compiler detects an invalid nomenclature range specified by identical data-names following the RENAMES and THRU keywords, respectively. The compiler ignores the entire RENAMES data description entry. lg45 .RENAMES. SPECIFIES STORAGE OVERLAP ON LEFT END. In processing the RENAMES clause; the compiler detects the condition in which the beginning of the storage allocated to the data-name after the THRU keyword is to the left of the beginning of the storage allocated to the data-name after the RENAMES keyword. The compiler ignores the entire RENAMES data description entry. lg46 INVALID OR MISSING DATANAME AFTER .THRU ·· In specifying the RENAMES clause, a data-name is missing after the THRU keyword or, if present, is not recognized as a valid data item that was previously defined. The compiler ignores the entire RENAMES data description entry. lg47 DATANAME MISSING AFTER .CORRESPONDING. In the processing of an ADD, SUBTRACT, or MOVE CORRESPONDING statement, the compiler detects the omission of a valid data-name reference after the CORRESPONDING keyword. Fatal. lgsg .TO. OR .FROM. OMITTED IN .CORRESPONDING .· In the processing of an ADD, SUBTRACT, or MOVE CORRESPONDING statement, the compiler detects the omission of the TO or FROM keyword. Fatal. lgSI INVALID OR MISSING DATANAME AFTER .TO. OR .FROM. In the processing of an ADD, SUBTRACT, or MOVE CORRESPONDING statement, the compiler detects the omission of a valid data-name reference after the keyword TO or FROM. Fatal. H-65 DIAGNOSTIC ERROR MESSAGES li52 NO OBJECT CODE PRODUCED FOR .CORRESPONDING. In the processing of an ADD, SUBTRACT, or MOVE CORRESPONDING statement, the compiler produced no object code because no "correspondence" was found between the two group items referenced in the COBOL statement containing the CORRESPONDING option. This diagnostic is informational only. li53 GROUP ITEM NOT REFERENCED IN .CORRESPONDING. In the processing of an ADD, SUBTRACT, or MOVE CORRESPONDING statement, the compiler discovered that one of the references is a reference to an elementary item. Fatal. li54 LEVEL 66 REFERENCE DISALLOWED IN .CORRESPONDING. In the processing of an ADD, SUBTRACT, or MOVE CORRESPONDING statement, the compiler detects a reference to a data-name declared at level 66. This is an invalid reference. Fatal~ 1~55 .FILE STATUS. ITEM DEFINED IN .FILE SECTION. A data-name referenced in a FILE STATUS phrase of a SELECT clause is defined in the FILE SECTION of the COBOL program. The compiler ignores this error and continues to process the FILE STATUS data-name. 1~56 INCOMPATIBLE OPERANDS FOUND IN .CORRESPONDING. In the processing of an ADD, SUBTRACT, or MOVE CORRESPONDING statement, the compiler detects a pair of CORRESPONDING data items that are incompatible. This diagnostic is informational only. 1~57 EMPTY .GO TO. WAS NOT THE SUBJECT OF AN .ALTER ·. A GO TO statement without a procedure reference was detected. The empty GO TO is not the subject of an ALTER statement. Fatal. 1~6~ QUALIFIER OMITTED IN PROCEDURE REFERENCE. A section name is omitted after the keyword OF or IN in a qualified procedure reference of the COBOL statement being compiled. Fatal. H-66 DIAGNOSTIC ERROR MESSAGES lj61 INCONSISTENT NUMBER OF ARGUMENTS IN .CALL ·· The subprogram referenced in this CALL statement has been referenced before. The number of arguments in the earlier CALL differs from the number in the current CALL. lj62 PARAGRAPH WITHOUT SECTION PRECEDES THIS SECTION. In a COBOL program, if one paragraph is in a section, then all paragraphs must be in sections. In this source program, a paragraph not within a section has been detected preceding this section in the source program. lj63 DUPLICATE PARAGRAPH NAME DETECTED. In a section of the Procedure Division, a paragraph name is defined more than once and is net uniquely referenceable even with qualification. lj64 REFERENCE TO UNDEFINED PROCEDURE NAME. The compiler detects a reference to an undefined procedure name in the PROCEDURE DIVISION. 1~65 UNDEFINED PROCEDURE QUALIFIER REFERENCE. The compiler detects a qualified procedure reference that contains an undefined qualifier in the PROCEDURE DIVISION. lj66 ILLEGAL PROCEDURE NAME REFERENCE. The compiler detects an procedure name referen~e PROCEDURE DIVISION. invalid in the lj67 AMBIGUOUS PROCEDURE NAME REFERENCE. The compiler detects a reference in the PROCEDURE DIVISION to a procedure name that is not uniquely referenceable, even through qualification. 107~ PARAGRAPH NAME DISALLOWED AS QUALIFIER. The compiler detects a qualified procedure reference in which the qualifier is a paragraph name. 1071 SECTION NAME REFERENCE MAY NOT BE QUALIFIED. The compiler detects a qualified procedure reference in which a section name is qualified by another section name. H-67 DIAGNOSTIC ERROR MESSAGES 1~72 AMBIGUOUS PARAGRAPH NAME REFERENCE. The compiler detects a reference in the PROCEDURE DIVISION to a paragraph name that is not uniquely referenceable, even through qualification. 1~73 POSSIBLE .PERFORM. RANGE VIOLATION. The compiler detects a PERFORM THRU statement in which the procedure name following THRU is defined before the procedure name following the PERFORM. This condition could a logic problem in the COBOL program being compiled. 1~74 NUMERIC PROCEDURE NAME EXCEEDS 3~ CHARACTERS. A numeric string that appears to be a numeric procedure name exceeds 3J characters in length. The string is truncated on the right to 3J characters and processing of the numeric procedure name continues. 1~75 NUMERIC PROCEDURE NAME CONTAINS DECIMAL POINT. A numeric string that appears to be a numeric procedure name contains a decimal point. The compiler ignores the presence of the decimal point and proceeds with the processing of the numeric procedure name. 1~76 .RELATIVE KEY. ITEM DEFINED IN RECORD OF FILE. A data-name referenced in a RELATIVE KEY p~rase of a SELECT clause is defined in the record description of the associated file. The compiler ignores this error and continues to process the RELATIVE KEY data-name. li77 NO. OF AREAS DEFAULTS TO MAX. FOR FILE TYPE. The number of buffer areas reserved by the RESERVE clause is greater than the maximum allowed for the file organization. The compiler allocates two areas for a sequential file and one for a relative file. 11~5 UNRECOGNIZED LITERAL TYPE ··· SYSTEM ERROR The compiler has failed to properly identify a literal. System error. Fatal. H-68 DIAGNOSTIC ERROR MESSAGES 11~7 .TO. OR .GIVING. MISSING IN ADD The keyword TO or GIVING was not found after the second operand in an ADD statement. Fatal. 111~ MORE THAN 18. DIGITS IN COMPOSITE. TRUNCATING. The length of an arithmetic composite is greater than 18 digits. The composite is truncated on the left to 18 digits. Warning. 1111 ONLY ONE DEST ALLOWED AFTER .CORRESPONDING. USE FIRST. More than one destination data-name follows the keyword CORRESPONDING. The compiler ignores all but the first. Warning. 1113 UNSIGNED COMP 3 ITEMS ILLEGAL The PICTURE for a COMP-3 item does not contain an S character. Fatal. H-69 APPENDIX I RECORD MANAGEMENT SERVICES ERROR CODES This appendix lists the RMS error codes that can be reported during COBOL program execution. These codes appear in conjunction with COBOL Object Time System error messages, which are described in Appendix J. The error codes appear in the form: CBL -- NN: (MESSAGE) ASSOCIATED RECORD SERVICES ERROR: -nn (mm) The NN portion of the CBL message is the COBOL OTS error code; (MESSAGE) is the message text, which provides a brief description of the error. The nn portion of the RMS message is one of the error codes listed below. The (mm) portion of the RMS message is displayed for I/O errors only. The (mm) error codes are listed in the: · IAS/RSX-11 I/O Operations Reference Manual (Appendix I). · RSTS/E Systems Manager's Guide (Appendix C). Most errors can occur in RSX-llM, IAS, and RSTS/E systems. System-specific errors are identified in the description. The term "file processor" refers to FIP fon RSTS/E systems) or FllACP (on RSX-llM and IAS systems) · If you encounter an error code that is not listed, submit a Software Performance Report fSPR). -32 fmm) -96 -112 (mm) An OPEN statement in the program failed because the file processor could not access the file. The program failed to create a new file because the allocation quantity specified in the /AL or /CO switch was too large. The program failed to OPEN a file on an ANSI-labelled magnetic tape because the records in the file were variable-length but not in ANSI D format. I-1 -16~ (mm) -176 fmm) -32~ -336 (mm) -368 frnm) -448 -464 RECORD MANAGEMENT SERVICES ERROR CODES The file processor detected an error while reading the attributes of the file. The file processor detected an error while writing the attributes of a file. A REWRITE operation failed because: 1. The value of the prime key field of the record to be written has changed or, 2. The value of an ALTERNATE key field has changed but the change attribute was not specified for the key when the file was created. NOTE The second condition can occur only if the file was not created by a COBOL program, since all alternate keys are changeable according to the 1974 ANSI COBOL standard. The program failed to perform a record operation because RMS detected an index bucket format check-byte failure. The bucket has been corrupted and random access to one or more records is affected. Use the RMS DEFINE and CONVERT utilities to correct the file or use a backup copy of the file to restore it. The program failed to CLOSE a file on magnetic tape because the RSTS/E CLOSE failed to access the magnetic tape unit specified in the program's ASSIGN or VALUE OF ID clause. This error can occur only on RSTS/E systems. The program failed to OPEN a file for OUTPUT because the file processor could not create the file. The program failed to CLOSE a file because the file processor could not deaccess the file. · The program failed to OPEN a file because it specified an invalid or inappropriate device. Assigning the file to a non-existent device or assigning an indexed file to a magnetic tape device could cause this error to be reported. The program failed to OPEN a file because a syntax error appears in the directory portion of the file specification. Check the VALUE OF ID and SELECT clause for the file. I-2 -48$ -496 -512 -520 (mm) -544 -56~ f mm} -576 -592 -616 -624 fmm) -672 -7~4 RECORD MANAGEMENT SERVICES ERROR CODES The program failed to OPEN the file because there is insufficient buffer space for RMS to allocate either I/O buffers or control structures to support file processing. This can occur, for example, if the actual bucket size for a relative or indexed file is larger than the bucket size implied by the program's BLOCK CONTAINS clause and/or record descriptions. Use the RMS DISPLAY utility to determine the actual size of the buckets in the file. The program failed to OPEN the file because the directory in the file-spec specified in either the VALUE OF ID or SELECT clause cannot be found. The program failed to OPEN a file because the specified device was not ready. The program failed to OPEN the file because the file processor detected a device positioning error. This is a transient hardware error; however, if it persists, contact your Digital field service representative. The program failed to perform a WRITE or REWRITE operation because the operation would cause duplication in the file of one or more alternate keys that do not have the WITH DUPLICATES attribute. The program failed to OPEN a file because the file processor could not insert the file directory entry. The program failed for one of the following reasons: 1. An OPEN operation has failed because the organization of the file being opened was not correctly specified in the file's SELECT clause. 2. A record operation has failed because it is inconsistent with the OPEN mode of the file. For example, this error would be reported if the program executed a WRITE statement for a file opened for INPUT. The program detected end-of-file on a file that it was processing. The program failed to OPEN a magnetic tape file for OUTPUT because the expiration date has not been reached. Character positions 48-53 of the file-header label fHDRl} contain the expiration date. The program failed to perform a WRITE or REWRITE operation because the file processor could not extend the file. The program failed to create (that is, OPEN for OUTPUT) a file because the specified file already exists. The program was not able to access a file because the file was locked by another user. I-3 -72~ -736 -752 -784 -88~ -896 -96~ -lj~8 -1~24 -11~4 RECORD MANAGEMENT SERVICES ERROR CODES The program failed to OPEN a file because the file processor could not locate the specified file directory entry. The program failed to OPEN a file because it does not exist. The program failed to OPEN a file because a syntax error was detected in the file-name portion of the file specification obtained from the ASSIGN or SELECT clause of the program. The program was not able to create (i.e., OPEN for OUTPUT} or extend (as part of WRITE or REWRITE operation} a file because the recording medium is full. The program attempted to perform an operation that is not allowed for the file organization. For example, deleting a record from a sequential file. The program failed to perform a READ, WRITE, or REWRITE operation because a record with an invalid count field was detected in a sequential file. The program failed to perform a READ or START operation because the specified data item does not represent a key that is defined for the file. The program failed to OPEN a file on magnetic tape because the tape volume was not in ANSI format. The program failed to perform the specified operation because the file processor detected a busy channel. The program failed to perform a random record operation on a relative file because the value in the RELATIVE KEY data item exceeds the maximum record number specified when the file was created. NOTE This condition can occur only if the file was not created by a COBOL program (for example, the file was created by the RMS DEFINE utility which permits specification of a maximum record number} . The program failed to perform a WRITE operation to a sequential file because the file was not positioned at EOF. I-4 RECORD MANAGEMENT SERVICES ERROR CODES -1168 -12i~ (mm) -1248 -1296 - l 3 7 6 f m..rn) -1392 -144,0 -1456 (mm) -1472 (816) -1488 -152i (mm) -1568 The program failed to OPEN a file because the SELECT clause in the program did not specify the same number of alternate record keys that were specified when the file was created. Therefore, insufficient buffer space is available in the task for the allocation by RMS of internal control structures known as index descriptors. The program failed to OPEN a file because the RSTS/E OPEN function could not access the magnetic tape unit specified in the ASSIGN and/or SELECT clause. This error occurs only on ~STS/E systems. The program failed to perform the specified operation because an error was detected in the file's prologue. The file may be corrupted. use the RMS DEFINE and CONVERT utilities to recreate and reload the file, or use a backup copy of the file to restore it. The program failed to OPEN a file because the program does not have the proper privilege authority to access the file. The program failed to OPEN a file because the file processor detected a read error. The program failed to perform a WRITE operation to a relative file because a record already exists in the target record position. The program failed to perform the specified operation to a relative or indexed file because the target bucket was locked by another user. The program failed to CLOSE a file because the RSX-FllACP REMOVE function could not delete the directory entry. This error occurs only on RSX-llM and IAS systems. The program failed to perform a READ, START, DELETE, or REWRITE operation to a relative or indexed file because the record specified in the random access operation does not exist. When an (mm) code of -816 also appears in the RMS error message, it further indicates that the operation is to an indexed file and that the file is empty. The program failed because it tried to UNLOCK a bucket (record) that was not LOCKED. The program failed because RMS detected a file processor error. An error was detected while reading the file prologue, and the file may be corrupted. Use the RMS DEFINE and CONVERT utilities to recreate and reload the file, or use a backup copy of the file to restore it. The program failed because: 1. The size of the record to be written by a WRITE or REWRITE operation exceeds the maximum record size specified when the file was created, or I-5 -1584 -16~~ -1616 -1664 -168~ -1696 -1744 -1776 (mm} -1784 -1792 fmm) RECORD MANAGEMENT SERVICES ERROR CODES 2. The size of the record in a REWRITE operation to a sequential file does not equal the size of the original record. The program failed to READ a record because the program does not have a buffer large enough for the record. Either the record descriptions or the BLOCK CONTAINS clause are inconsistent with the actual size of the records in the file. Use the RMS DISPLAY utility to determine the actual or maximum size of the file's records. The program failed to perform a WRITE or REWRITE operation to an indexed file in sequential access mode becuase the prime key of the record is not greater than the key of the last accessed record. The program failed to OPEN a file because the file is sequentially organized and cannot be shared with another user. This error could be reported if the program specifies the /SH switch in the ASSIGN or VALUE OF ID clause for the file. The program failed to OPEN or CLOSE a file because a system directive error occured. The program failed to perform a record operation (READ, WRITE, REWRITE, UPDATE or DELETE) to an indexed file. The file is corrupted. Use the RMS DEFINE and CONVERT utilities to recreate and reload the file, or use a backup copy of the file to restore it. The program failed to OPEN a file because a syntax error was detected in the file type portion of the file specification obtained from the SELECT and VALUE OF ID clauses. The program failed to OPEN a file because a syntax error exists in the version number portion of the file specification obtained from the VALUE OF ID and SELECT clauses. This error can occur only on RSX-llM and !AS systems. The program failed to CLOSE a file because the file processor detected a write error. The program failed to OPEN a file because the recording medium is write-locked. For magnetic tapes, insert a write-ring; for disk-drives, move the write-lock switch to the off position. An error has occurred during an RMS write operation to the file's prologue. The file may be corrupted. Use the RMS DEFINE and CONVERT utilities to correct the file, or use a backup copy of the file to restore it. I-6 APPENDIX J OBJECT-TIME SYSTEM ERROR MESSAGES This appendix lists and describes the COBOL Object-Time System error messages. The run-time system.displays these messages when it detects errors during the execution of COBOL tasks. In some cases, the OTS displays an additional line containing an associated Record Management Services error code that further specifies the error condition. RMS error codes appear in Appendix I. NOTE Error codes that are preceded by an asterisk (*) indicate fault conditions during task execution. They are described in the documentation set for your operating system. These fault conditions could result from COBOL program errors, such as: · a "run-away" subscript or index in a program compiled with the /-BOU switch · using CID in a program compiled with the /RO switch 1: SUBSCRIPT TOO SMALL OR TOO LARGE The subscript value for a data item is not greater than zero, or it is greater than the maximum number of occurrences of the table data item. 2: INDEX TOO SMALL OR TOO LARGE The value of an index-name is not greater than zero, or it is greater than the maximum number of occurrences of the table data item. J-1 OBJECT-TIME SYSTEM ERROR MESSAGES 3: DEPENDING ON ITEM TOO LARGE OR TOO SMALL The value of the data item that defines the size of the table is not in the table size range specified in the OCCURS clause. 4: ILLEGAL PROGRAM REENTRY A COBOL subprogram attempted to call itself, either directly or indirectly. The EXIT PROGRAM statement must be executed in a subprogram before the subprogram can be called again. 5: INCORRECT NUMBER OF ARGUMENTS The number of arguments received by a COBOL subprogram does not agree with the expected number of arguments; that is, the number of CALL statement arguments in the calling program is not the same as the number of arguments in the PROCEDURE DIVISION USING phrase of the called program. 6: PERFORM STACK OVERFLOW The number of nested PERFORMS has exceeded the maximum; the maximum is either the default (ten) or the number specified by the value of the /PFM:n compiler switch. 7: PERFORM END OF RANGE VIOLATION The program reached the end of an active PERFORM while processing a more-recently executed PERFORM~ that is, the program executed a PERFORM statement whose range overlaps the end of the PERFORM statement that is currently being executed. 8: ILLEGAL NESTED PERFORM The program attempted to execute a PERFORM statement whose exit is also the exit of a previously executed PERFORM that is still active. 9: NULL ALTERABLE GO TO The program reached an alterable GO TO statement before assigning it a procedure name. l~: SAME AREA ALREADY BUSY WHEN OPENING The program tried to OPEN a file that uses the same buffer area as another open file. J-2 OBJECT-TIME SYSTEM ERROR MESSAGES 11: FILE ALREADY OPEN The program tried to OPEN a file that is ·currently open. 12: FILE NOT OPEN The program tried to CLOSE or otherwise access a file that is not currently open. 13: INVALID OPERATION ATTEMPTED The program tried to execute one of the following I/O statements for a file that is open in an incompatible mode: (a) a READ for a file open for OUTPUT (b) a WRITE for a file open for INPUT (c) an I/O opera~1on not consistent with the file organization (for example, START on a sequential file) 14: READ MUST PRECEDE REWRITE OR DELETE The program attempted to execute a REWRITE or DELETE statement for a sequentially accessed file, but the last I/O operation on the file was not a READ. 15: FILE PREVIOUSLY LOCKED The program tried to access a file for which it had previously executed a CLOSE ... WITH LOCK statement. 16: CLOSING UNIT OR REEL UNSUCCESSFUL The program executed a CLOSE UNIT or CLOSE REEL statement that failed. The accompanying RMS error code £urther specifies the error. 1 7: OPEN ERROR The execution of an OPEN statement failed. The accompanying RMS error code further specifies the error. 18: CLOSE ERROR The execution of a CLOSE statement failed. The accompanying RMS error code further specifies the error. J-3 OBJECT-TIME SYSTEM ERROR MESSAGES 19: NOT OPEN FOR OPERATION The program tried to execute an I/O statement for a file that is not open. 2~: INVALID LINAGE VALUE The LINAGE clause specifies a page body size that results in an invalid value; the value is not greater than zero, or it is out of range. 21: NO END OF FILE PROCESSING An end-of-file has been detected, but the I/O statement does not have an AT END clause, and the program has no USE procedure for end-of-file processing. 22: READ ERROR The execution of a READ statement failed. The accompanying RMS error code further specifies the error. 23: WRITE ERROR The execution of a WRITE statement failed. The accompanying RMS error code further specifies the error. 24: REWRITE ERROR The execution of a REWRITE statement failed. The accompanying RMS error code further specifies the error. 25: DELETE ERROR The execution of a DELETE statement failed. The accompanying RMS error code further specifies the error; 26: START ERROR The execution of a START statement failed. The accompanying RMS error code further specifies the error. 27: UNLOCK ERROR An unsuccessful attempt has been made to unlock a record in the r:i.ie. The accompanying RMS error code further specifies the error. 28: BAD NAME USING file-name The file specification or associated switches for a file description are syntactically incorrect. J-4 OBJECT-TIME SYSTEM ERROR MESSAGES 29: STOP Not an error. The program executed a STOP literal statement. Enter a carriage return to continue program execution. 3i: UNKNOWN PROCEDURE The program attempted to transfer control to an undefined procedure-name; a fatal diagnostic error message was issued at compile time. The program was compiled with the /ACC:2 switch. See compiler source program listing. 31: ACCEPT ERROR The program failed to ACCEPT data from the user. The input device is busy, off-line, or otherwise unavailable. 32: DISPLAY ERROR The program failed to DISPLAY data to the user. The output device is busy, off-line, or otherwise unavailable. 33: UNABLE TO COMMUNICATE WITH USER The run-time system failed to display an error message to the user. This error is not displayed, but its code is returned as the exit status. 34: FATAL SOURCE ERROR ENCOUNTERED The run-time system tried to execute a part of the program that contains fatal errors. The program was compiled with the /ACC:2 switch. See compiler source program listing. 35: ENVIRONMENTAL INTEGRITY FAULT Part of the run-time system has been damaged by the COBOL program or by an error in the run-time system itself. This error could result from a "run-away" subscript or index in programs compiled with the /-BOU switch. 36: SPECIFY ALL "ON" SWITCHES Not an error. This message appears when program execution begins if the SPECIAL-NAMES paragraph contains a SWITCH ON or OFF statement. fSee Section 2.6.2, Setting Program Switches.) J-5 OBJECT-TIME SYSTEM ERROR MESSAGES 37: INVALID INPUT, TRY AGAIN The user incorrectly responded to the SPECIFY ALL "ON" SWITCHES message. fSee Section 2.6.2, Setting Program Switches.) * 38: ODD ADDRESS FAULT * 39: MEMORY PROTECTION VIOLATION * 4~: BPT INSTRUCTION * 41: IOT INSTRUCTION * 42: RESERVED INSTRUCTION * 43: INVALID EMT INSTRUCTION * 44: FLOATING POINT EXCEPTION 45: PERFORM COUNT TOO LARGE The value of the iteration counter used in a PERFORM procedure identifier TIMES statement exceeded the limit, which is 32767. 46: EXPONENT TOO LARGE OR TOO SMALL The exponent used in a COMPUTE statement is out of range. The legal range is -32768 to 32767. J-6 INDEX Abbreviated ODL file, 2-19 Abortive diagnostic, 12-4 /ACC:n switch, 2-12, 2-15, 12-4 ACCEPT statement, 6-39, 6-45 Access method, 6-1 ACCESS MODE clause, 6-19, 6-32 Acceps modes, 6-19 Accumulation of storage overhead, 14-9 Active/Inactive arguments, 3-41 ADD statement, 4-19 multiple operands, 4-18 Addressing, CID, 13-3 ADVANCING clause, 6-6 /AL:n switch, 14-4, 14-11 Alignment of data, 3-3 ALL literal, 3-26 Alphabetic data, 3-1 Alphanumeric data. 3-1 ALTER statement, 7-5 Alternate key, 6-24 Alternate key index, 14-7 Argument, Replacement, 3-52 Tally, 3-44 Argument address list, lf-6 Argument list, Tally, '3-45 Argument match, INSPECT, 3-42 Arguments, Subprogram, lf-3 Arithmetic expression processing, 4-22 Arithmetic statements, 4-15 common errors, 4-21 ASCENDING/DESCENDING KEY attributes, 5-17 ASCII character set, 3-3 ASCII codes, 3-4 ASSIGN clause, 6-43 Assumed decimal point, 4-6 AT END condition, 12-4 BEFORE/AFTER phrase, 3-37, 3-41, 3-51 Binary format, 4-1 Binary search of table, 5-17 Blank insertion, 3-lf Block, logical, 6-6, 6-15, 6-27 Virtual, 6-6, 6-15, 6-27 BLOCK CONTAINS clause, 6-6, 6-15, 6-28, 14-8 Blocking factor, 6-8, 6-3J Blocking of records, 6-15 /-BOU switch, 2-12, 14-lf Breakpoints in CID, 13-9 Bucket, 6-15, 6-27, 14-5 Bucket pointer, 14-7 Bucket size, Effect of, 6-15 Selecting, 14-8 Bucket split, 14-7 Buffer size, 6-8, 6-18, 6-3J Buffer space, 6-31 Buffering, 6-7, 6-17, 6-3J Caching index roots, 14-3 Calculating bucket size, 6-17, 6-28 Calculating buffer space, 6-8, 6-18, 6-31 CALL statement, lf-1, lf-2, E-1 Calling a subprogram, lf-2 Calling MACRO programs, lf-4 CANCEL BREAKPOINT, CID command, 13-5 Card reader, 6-39 Characteristics of devices, 6-38 Characters, Special, 3-3 Choosing data types, 14-lf CID, 2-19, 13-1 breakpoints in, 13-9 command errors in, 13-lf examples, 13-11 program initiation, 13-8 program suspension, 13-9 program termination, 13-9 CID addressing, 13-3 CID command, 13-4 CANCEL BREAKPOINT, 13-5 DEPOSIT, 13-5, 13-6 EXAMINE, 13-6 GO, 13-7 SET BREAKPOINT, 13-7 SHOW BREAKPOINTS, 13-8 XIT I 13-8 CID command mode, 13-2 CID environment, 13-2 /CL:n switch, 14-11 Class, on source listing, G-3 Class tests, 4-lf Data, 3-6 Classes of data, 3-5 CLOSE REEL clause, 6-39 CLOSE statement, 6-13, 6-24, 6-37 Closing indexed files, 6-37 Closing relative files, 6-24 /CM6 switch, 2-13 /CO:n switch, 14-4, 14-12 COBOL file types, 6-2 COBOL Interactive Debugger, 13-1 Codes, Device, 6-37 Collating sequence, 3-6 Command, CID, 13-4 Index-1 INDEX (Continued) Command line, compiler, 2-1i, 2-11, 2-16 Command mode, CID, 13-2 Common errors, arithmetic statements, 4-21 INSPECT statement, 3-55 library facility, 2-8 MOVE statement, 3-12 numeric moves, 4-14 STRING statement, 3-2~ UNSTRING statement, 3-36 Communication with the program, 6-45 Comparison operation, 3-6 Compatibility, 6-47 Compilation, 2-9 identification number, G-1 multiple program, 2-1i single program, 2-9 Compilation date and time, G-1 Compiler, version, G-1 Compiler command line, 2-1i, 2-11, 2-16 Compiler error messages, H-1 Compiler-generated PSECTs, D-1, G-4 Compiler limitations, C-1 Compiler name, 2-9 Compiler performance, Effect of qualification on, 7-12 Compiler switches, 2-11, 2-13, 2-14, 2-15 Compiler system errors, 12-1 COMPUTATIONAL, 4-1, 4-2, 4-12 COMPUTATIONAL-3, 4-5, 4-12 COMPUTATIONAL-3 signs, 4-5 COMPUTATIONAL-6, 4-3, 4-4, 4-12 COMPUTE statement, 4-21, 14-li Concatenation of fields, 3-13 Condition, AT END, 12-4 Class, 3-6 INVALID KEY, 6-35, 12-4 Overflow, 3-17, 3-34 Relation, 3-4 Condition-names, 7-6 Conventional format, identification field, G-2 sequence number, G-2 Conventional reference format, 2-1 Conversion of reference format, 8-1 COPY, 2-2, 2-3 example, 2-4, 2-5, 2-6, 2-7 use of, 2-4 COPY in source listing, 2-8 COPY REPLACING, 2-5, 2-6 Count field, 6-4, 6-27 COUNT phrase, 3-28 Counter, Tally, 3-44 /CREF switch, 2-13 /CSEG:nnnn switch, 2-13, 9-2, 9-3 /CVF switch, 2-13 Data, Alphabetic, 3-1 Alphanumeric, 3-1 Non-numeric, 3-1 Numeric, 3-1 Data Division location, G-3 Data item, Definition of, 7-1~ Qualification of, 7-1~ Data level buckets, 14-7 Data map, G-3 Data movement, 3-7 Data-name subscripting, 5-11 Data-names, maximum, C-1 Data organization, 3-2 Data references, Qualified, 7-8 DATE, 6-45 Date, compilation, G-1 DAY, 6-45 Debugger, 2-19, 13-1 Debugging session example, 13-11 Decimal point, assumed, 4-6 Decimal scaling position, 4-6 DECLARATIVES, 6-49 Defining a table, 5-1 Defining data items, 7-li DELETE statement, 6-22, 6-35 Deleting records from a relative file, 6-22 Deleting records from an indexed file, 6-35 DELIMITED BY phrase; 3-15, 3-23 DELIMITER phrase, 3-29 Delimiters, Multiple, 3-27 Variable, 3-27 DEPOSIT, CID command, 13-5, 13-6 Determining buffer space, 6-8 Device assignment, 6-43 Device characteristics, 6-38 Devices, 6-37 Diagnostic, informational, 12-2, 12-3 Diagnostic error messages, 12-1, H-1 Directory location, G-3 Disk processing, 6-38 DISPLAY, 4-1 maximum number of operands, C-1 DISPLAY statement, 6-39, 6-46 DIVIDE statement, 4-21 Dynamic access mode, 6-2~, 6-32 Index-2 INDEX (Continued) Edited moves, 3-1~ elementary numeric, 4-13 Efficient program structure, 14-2 Elementary items, 3-2 Elementary moves, 3-8 Elementary numeric edited moves, 4-13 Elementary numeric moves, 4-11 Embedded diagnostics, 12-1 End-of-file mark, 6-3 ENDS routine, E-3 Environment, CID, 13-2 /ERR switch, 2-13 Error codes, sort, E-5 terminal handling, F-5 Error message summary; 2-15 Error messages, 12-1 diagnostic, H-1 Merge utility, 2-23, 2-24, 2-25 OTS, J-1 RMS, I-1 Run-time, 12-5 Error procedures, Run-time file I/O, 12-4 /EX:n switch, 14-4, 14-12 EXAMINE, CID command, 13-6 Executing a COBOL task, 2-29, 2-3~ EXIT PROGRAM statement, lj-3 Explicit filenames, 6-41 Expression processing, arithmetic, 4-22 EXTEND mode, 6-11, 6-13 Extend quantity, 14-4 Fatal diagnostic, 12-3 File, 6-4j abbreviated ODL, 2-19 listing, 1-1, 2-lj merged ODL, 2-19 Multi-volume, 6-3 object, 1-2, 2-11 ODL, 1-2, 2-16, 2-17 Print, 6-13 source, 2-lj Storage, 6-13 Transportable, 6-48 File activity, 14-9 File body, ODL, 11-2 File design, 14-4 File Handling, 6-1 File header, ODL, 11-1 File organization, indexed, 6-24 relative, 6-13 Sequential, 6-3 File specification, 2-lj, 6-41 File specification switches, 14-11 File status key values, 12-4 File-to-LUN assignment table, G-2 File types, COBOL, 6-2 Filenames, 6-41 Fixed-length records, 6-4, 6-14, 6-27 Form control characters, 6-47 Formatting source programs, 7-1 General formats, A-1 GIVING phrase, 4-18 GO, CID command, 13-7 GO TO DEPENDING, C-1 Good programming practices, 7-1 Group items, 3-2 Group moves, 3-8, 4-11 /HELP switcn, ~-lJ Hierarchy of index, 14-5 HISEG, 2-26 I/O buffer areas, 6-8, 6-18, 6-31 I/O mode, 6-22 I/O routines, overlaying_, 2-19 I/O statements, 6-2 Identical tally arguments, 3-47 Identification field, conventional format, G-2 Identification number, compilation, 12-5, G-1 IF statement, 3-4 Illegal values in numeric fields, 4-8 Implicit redefinition of fields, 3-38 Including non-COBOL programs in task, 11-5 Index buckets, 6-31 Index data items, 5-14 Index depth, 14-9 Index structure, 14-5 INDEXED BY phrase, 5-12, 5-17 Indexed file organization, 6-24 Indexed files, 14-5 Sequential reading, 14-3 Indexed I/O statements, 6-31 Indexed OPEN modes, 6-32 Indexed sending field, 3-14 Indexed subscripting, 5-12 Indexing, 5-9 Relative, 5-13 Informational diagnostic, 12-2, 12-3 Initializing tables, 5-7 Insertion, Blank, 3-11 Index-3 INDEX (Continued) Insertion (continued) Slash, 3-1.0' Zero, 3-1~ INSPECT operation, 3-4,0' INSPECT statement, 3-36 Inter-program communications, 1,0'-l Interactive debugger, 13-1 Interference of replacement arguments, 3-54 Interference of tally arguments, 3-47 Intermediate results, 4-15, 4-25 INVALID KEY clause, 6-19, 6-35 INVALID KEY condition, 12-4 JUSTIFIED clause, 3-9 Justified moves, 3-1.0' KBASGN terminal handling routine, F-2, F-3 KBCLOS terminal handling routine, F-2 KBDEAS terminal handling routine, F-3 KBOPEN terminal handling routine, F-2 KBREAD terminal handling routine, F-4 KBREAU terminal handling routine, F-4 KBWRIT terminal handling routine, F-3 /KER:kk switch, 2-14 Key, Definition of, 6-24 Key value, 14-7 Keys, sort, E-3 LEADING condition, 3-49 Legal non-numeric elementary moves, 3=9 Level 88, 7-6 Level number, 7-1~ Library facility, 2-2 common errors, 2-8 Library file, creating, 2-3 Library text, merging, 2-4 Limitations. compiler, C-1 LINAGE clause, 6-6 LINAGE counters, 6-11 Line number, source, G-1 Line printer, 6-39 LINKAGE SECTION, l,0'-2 Linking sort routines, E-4 Listing, source, G-1 Listing file, 1-1, 2-1.0' Literal sending field, 3-14 Literal subscripting, 5-9 /LO switch, 14-12 Location, Data Division, G-3 directory, G-3 LOCK option, 6-24, 6-37 Logical block, 6-6, 6-15, 6-27 Logical block size, 6-6 Logical name assignment, 6-39 Logical processing units, Grouping of, 7-4 Logical Unit Number, 6-43 Logical unit number assignment, B-1 LUN, E-4 relative, G-2 LUN assignment, 6-43, B-1 MACRO programs, Calling, 1.0'-4 Magnetic tape processing, 6-39 Main program, COBOL, l~-1 Map, data, G-3 procedure name, G-3 /MAP switch, 2-14, 13-1, G-3 Mapping table elements, 5-3 Mass storage I/O, Optimizing, 14-1 Merge, 1-3, 2-16, 2-17, 2-18 ODL files for, 11-1 Merge dialogue, 2-19, 2-2,0', 2-21 example, 2-22, 2-23 MERGE routine, E-2 Merge utility, 2-16 Merge utility error messages, 2-23, 2-24, 2-25 Merged ODL file, 2-19 Merging library text, 2-4 Merging ODL files, 11-5 Mode, EXTEND, 6-13 OUTPUT, 6-12 Modifying ODL files, 11-6 Modular proqrams, 1-2 Module, - - object code, 1-1 MOVE CORRESPONDING, 3-8, 3-12 MOVE statement, 3-7, 3-8, 4-12 numeric, 4-1~ Moves, elementary numeric, 4-11 elementary numeric edited, 4-13 group, 4-11 Multi-block read and write, 14-3 MULTI-FILE TAPE clause, 6-39 Index-4 INDEX (Continued) Multi-volume files, 6-3 Multiple delimiters, 3-27 Multiple operands, 4-18 Multiple receiving fields, 3-11~ 3-21 Multiple sending fields, 3-13 MULTIPLY statement, 4-2J Names, PSECT, D-1 Nested PERFORM source line number, 12-5 Nesting of parentheses, C-1 Nesting of PERFORM statements, C-1 /NL switch, 2-14 NO ADVANCING phrase, 6-47 Non-COBOL object modules, lJ-4, 11-5 Non-edited movesi 3-11 NOT, 3-5 Numeric character handling, 4-1 Numeric data, 3-1 Numeric edited moves, elementary, 4-13 Numeric fields, illegal values, 4-8 testing, 4-8 Numeric MOVE statement, 4-lJ Numeric mo~1es, common errors, 4-14 elementary, 4-11 /OBJ switch, 2-14, 13-1, G-2 Object code module, 1-1 Object file, 1-2, 2-lJ Object file input to Task Builder, 2-27 Object modules, 1-1 Non-COBOL, lJ-4 Object-time system, 1-3 Object-time system error messages, J-1 OCCURS clause, 5-1, 5-2, 5-17 ODL directives for overlays, 11-3 ODL file, 1-1, 1-2, 2-16, 2-17 abbreviated, 2-19 merged, 2-19 on source listing, G-5 Rearranging, 11-6 Standard, 11-1 ODL file body, 11-2 ODL file header, 11-1 ODL file input to Task Builder, 2-25 ODL file merging, 11-5 ODL files for Merge, 11-1 ODL files for Task Builder, 11-1 Offset, 12-5, 13-3, 13-4 OPEN I-0 statement, 14-3 OPEN statementi 6-9, 6-2J, 6-33 Opening indexed files, 6-33 Opening relative files, 6-2J Opening sequential files, 6-9 Operating system prompts, 2-9 Operator, Relational, 3-5 Optimization, 14-1 Optimizing computation, 14-lJ Options, Task Builder, 2-26 ORGANIZATION clause, 6-1 OTS, 1-3 OTS action on OPEN, 6-lJ OTS error checking, lJ-3 OTS error messages, J-1 OTS operations on subscripted references, 5-11 OTS routines, on source listing, G-4 OUTPUT mode, 6-12, 6-22 /OV switch, 9-2 Overflow condition, 3-17, 3-34 OVERFLOW phrase, 3-17, 3-33 Overhead accumulation, 14-9 Overlay Description Language, 1-1 Overlay structure, 14-2 Overlaying I/O routines, 2-19 Parentheses, nesting of, C-1 Passing of arguments, lJ-3 PERFORM statement, 7-5 PERFORM statement nesting, C-1 /PFM:nn switch, 2-14, C-1 /-PLT switch, 2-14 Pointer, Bucket, 14-7 POINTER phrase, 3-14, 3-3J, 3-31 Position, decimal scaling, 4-6 Preallocation of file, 14-4 Primary key, 6-24 Primary key index, 14-7 Print-controlled records, 6-6 Print files, 6-13 Procedure name map, G-3 Procedure-names, maximum, C-1 Procedure reference, Qualified, 7-11 Processing I/O errors, 6-49 Program development, 14-2 PROGRAM-ID, lJ-3, 12-5 Program initiation in CID, 13-8 Program segments, Non-overlayable, 9-1 Overlayable, 9-1 Program suspension in CID, 13-9 Program switches, 2-29, 2-3J Program termination in CID, 13-9 Prompts, operating system, 2-9 Index-5 INDEX (Continued) PSECT, 9-2, 12-5 compiler-generated, D-1, G-4 on source listing, G-4 PSECT names, l~-3, D-1 PSECT size, G-4 Punctuation, use of, 7-4 Qualification and performance, 7-12 Qualified procedure reference, 7-11 Qualified references, 7-8 Qualifiers, maximum number, C-1 Qualifying data items, 7~1~ RANDOM access mode, 6-19 Random access mode, 6-32 READ NEXT statement, 6-21, 6-23 READ statement, 6-11, 6-21, 6-34 Reading buckets, 6-17 Reading indexed files, 6-34 Reading relative files, 6-21 Reading sequential files, 6-11 Rearranging ODL files, 11-6 Receiving fields, Multiple, 3-21 Record, Fixed-length, 6-4 fixed-length, 6-14 variable-length, 6-14 Record blocking, 6-6, 6-15, 6-27 RECORD CONTAINS clause, 6-4, 6-14, 6-27 Record Management Services, 6-47 Record size, 6-4, 6-14, 6-27 Redefinition, implicit, 3-38 Reference format, 2-1 conventional, 2-1 terminal, 2-1 Reference format conversion, 8-1 REFORMAT command string, 8-2 REFORMAT error messages, 8-3 REFORMAT utility program, 7-1, 8-1 Relation condition, 3-4 Relation tests, 3-4, 4-8 Relative file organization, 6-13 Relative files, 14-5 Relative I/O statements, 6-18 Relative indexing, 5-13 RELATIVE KEY clause, 6-23 Relative LUN, G-2 RELES routine, E-2 Replacement argument, 3-52 Replacement argument list, 3-53 Replacement arguments, Interference of, 3-54 Replacement value, 3-52 REPLACING, 2-5, 2-6 REPLACING arguments, 3-4~ REPLACING phrase, 3-36, 3-51 RESERVE clause, 6-8, 6-18, 6-3~ Results, intermediate, 4-15, 4-25 RETRN routine, E-2 Returning from a subprogram, l~-3 REWRITE statement, 6-12, 6-22, 6-34 Rewriting records, indexed file, 6-34 relative file, 6-22 sequential files, 6-12 RMS default overlay structure, 14-2 RMS DEFINE utility, 14-4, 14-5 RMS error codes, I-1 RMS error messages, I-1 /RO switch, 2-15 Root bucket, 14-5 ROUNDED phrase, 4-16 RSORT routine, E-1 RSTS/E terminal handling, F-1 RUN command, 2-3i Run-time error messages, 12-5 Run-time I/O errors, 12-4 Run-time system, 1-3 SAME AREA clause, 6-8, 6-13, 6-18, 6-24, 6-31, 6-37, 14-4 SAME RECORD AREA claQse, 6-5, 6-15, 6-27, 14-4 Scanner, INSPECT, 3-41 Search argument, REPLACING, 3-51 SEARCH statement, 5-16 SEARCH verb, 5-16 Section, Linkage, l~-2 Section-name, 9-1 SEGMENT-LIMIT clause, 9-1 Segment-number, 9-1 Segmentation, 9-1 SELECT statement, 7-1 Selecting bucket size, 14-8 Sequence number, conventional format, G-2 Sequential access mode, 6-19, 6-32 Sequential file organization, 6-3 Sequential files, 14-4 Sequential I/O statements, 6-9 SEQUENTIAL organization, 14-3 Sequential reading of indexed files, 14-3 Sequential search of table, 5-16 SET BREAKPOINT, CID command, 13-7 SET statement, 5-12, 5-14 Setting the INSPECT scanner, 3-41 Severity code, G-2 Severity level of diagnostic, 12-3 /SH switch, 14-12 Index-6 INDEX (Continued) Sharing buffer space among files, 6-8, 6-18, 6-31 SHOW BREAKPOINTS, CID command, 13-8 Sign conventions, 4-6, 4-7 Sign movement, 4-12 Sign tests, 4-9 Signs, COMPUTATIONAL-3, 4-5 SIZE ERROR phrase, 4-17 Slash insertion, 3-lj Sort error codes, E-5 Sort keys, E-3 Sort routine, ENDS, E-3 MERGE, E-2 RELES, E-2 RETRN, E-2 RSORT, E-1 Sort routines, linking, E-4 Sorting, E-1 Source file, 2-lj Source line number, G-1 Source program, creating, 2-1 entering, 2-2 Source program formatting, 7-1 Source program listing, G-1 Special characters, 3-3 SPECIAL-NAMES, 2-29, 2-3j, 6-39 Specifying bucket size, 6-28 Specifying next record to be read, 6-23, 6-35 Specifying Task Builder options, 11-8 Standard ODL file, 11-1 START statement, 6-23, 6-35 Statement, DISPLAY, 6-39 STRING, 3-7 Statements, arithmetic, 4-15 Storage files, 6-13 STRING statement, 3-7, 3-18 Structure of index, 14-5 Subordinate data items, 3-2 Subprogram, COBOL, lj-1 Return from, lj-3 Subprogram arguments, lj-3 Subprogram calls, lj-2 Subprogram references, G-5 Subscript evaluation, Sequence of, 3-35 Subscripted fields in INSPECT statement, 3-43 Subscripted fields in STRING statement, 3-18 Subscripted fields in UNSTRING statement, 3-34 Subscripted moves, 3-11 Subscripting, 3-19, 5-9 Subscripting operations by software, 5-lj Subscripting with data-names, 5-11 Subscripting with indexes, 5-12 Subscripting with literals, 5-9 SUBTRACT statement, 4-19 multiple operands, 4-18 Switch, /ACC:n, 2-12, 2-15, 12-4 /AL:n, 14-4, 14-11 /-BOU, 2-12, 14-lj /CL:n, 14-11 /CM6, 2-13 /CO:n, 14-4, 14-12 /CREF, 2-13 /CSEG:nnnn, 2-13, 9-2, 9-3 /CVF, 2-13 /ERR, 2-13 /EX:n, 14-4, 14-12 /HELP, 2-13 /KER:kk, 2-14 /LO, 14-12 /MAP, 2-14, 13-1, G-3 /NL, 2-14 /OBJ, 2-14, 13-1, G-2 /OV, 9-2 /PFM:nn, 2-14, C-1 /-PLT, 2-14 /RO, 2-15 /SH, 14-12 /SYM:n, 2-15 /WI :n , 14-12 Switches, compiler, 2-11, 2-13, 2-14, 2-15 File specification, 14-11 program, 2-29, 2-3j /SYM:n switch, 2-15 SYNCHRONIZED clause, 5-3 Table, Definition of, 5-1 variable-length, 5-2 Table Handling, 5-1 Table search, Binary, 5-17 Sequential, 5-16 Tally argument, 3-44 Interference of, 3-47 Tally arguments, identical, 3-47 Tally counter, 3-44 TALLYING arguments, 3-4~ TALLYING phrase, 3-31, 3-32, 3-36, 3-43 Target bucket, 14-7 Task, 1-3 Index-7 INDEX (Continued) Task Builder, 1-2, 2-16, 2-25, 2-26 object file input, 2-27 ODL file input, 2-25 ODL files for, 11-1 Task Builder options, 2-26, 11-8 Task-building, 2-25 Task image, 1,-1 Terminal handling (RSTS/E) , ¥-i Terminal handling error codes, F-5 Terminal handling routine, KBASGN, F-2, F-3 KBCLOS, F-2 KBDEAS, F-3 KBOPEN, F-2 KBREAD, F-4 KBREAU, F-4 KBWRIT, F-3 Terminal reference format, 2-1, 7-1 Testing non-numeric fields, 3-4 Testing numeric fields, 4-8 Tests, class, 3-6, 4-1, relation, 4-8 sign, 4-9 TIME, 6-45 Time of compilation, G-1 Truncation, 4-11, 4-12 Unique reference, 7-11 UNSTRING statement, 3-7, 3-21 Usage, on source listing, G-3 Usages, 4-1 USE procedure, 12-4 USE statement, 6-49 USING phrase, l~-1 Utility programs, 1-3 Value, Replacement, 3-52 VALUE cl·ause, 5-1 VALUE OF ID clause, 6-4,, 6-41 Variable delimiters, 3-27 Variable-length records, 6-14, 6-27 Variable-length tables, 5-2 Version of compiler, G-1 Virtual block, 6-6, 6-15, 6-27 Warning diagnostic, 12-3 /WI:n switch, 14-12 WRITE statement, 6-6, 6-12, 6-22 XIT, CID command, 13-8 Zero insertion, 3-1, Index-a READER'S COMMENTS PDP-11 COBOL User's Guide AA-1757D-TC NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the company's discretion. Problems with software should be reported on a Software Performance Report (SPR} form. If you require a written reply and are eligible to receive one under SPR service, submit your comments on an SPR form. Did you find errors in this manual? If so, specify by page. Did you find this manual understandable, usable, and well-organized? Please make suggestions for improvement. Is there sufficient documentation on associated system programs required for use of the software described in this manual? If not, what material is missing and where should it be placed? Please indicate the type of user/reader that you most nearly represent. 0 Assembly language programmer 0 Higher-level language programmer 0 Occasional programmer (experienced) [] User with little programming experience 0 Student programmer 0 Non-programmer interested in computer concepts and capabilities CitY~~~~~~~~~~~~~~State~~~~~~~Zip Code~~~~~~~ or Country ------------------------------------------------------------Fold llere------------------------------------------------------------ ·--------------------------------------------- Do Not Tear · Fold llere and Staple -------------------------------':"--------------- BUSINESS REPLY MAIL NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES Postage will be paid by: mnmnoma Software Documentation 146 Main Street ML5-5/E39 Maynard, Massachusetts 01754 FIRST CLASS PERMIT NO. 33 MAYNARD; MASS. digital equipment corporation Printed in U.S.A.