COBOL Manual For TNS And TNS/R Programs
User Manual:
Open the PDF directly: View PDF .
Page Count: 2046
Download | |
Open PDF In Browser | View PDF |
HP COBOL Manual for TNS and TNS/R Programs Abstract This publication describes the HP implementation of the 1985 version of the COBOL language. It includes information on the COBOL85 and NMCOBOL compilers (T9257 and T8107, respectively) and program execution, task-oriented information to help an experienced COBOL programmer use HP COBOL for NonStop™ systems, and summaries of compiler and run-time error messages. Product Version COBOL85 D32, D42, D44, D46 NMCOBOL D44, D46 Tandem Development Suite (TDS) PC COBOL D45, G06 HP Enterprise Toolkit—NonStop Edition (ETK) PC COBOL G06, H01 Supported Release Updates (RVUs) This publication supports D46.00, G06.00, H06.03 and all subsequent D-series, G-series, and H-series RVUs until otherwise indicated by its replacement publication. Part Number Published 522555-006 July 2005 Document History Part Number Product Version Published 522555-001 COBOL85 D32, D42, D44, D46; NMCOBOL D44.01, D46; PC COBOL D45, G06.06 February 2002 522555-002 COBOL85 D32, D42, D44, D46; NMCOBOL D44.01, D46; TDS PC COBOL D45, G06.06; ETK PC COBOL G06.06, G06.15, G06.18, G06.20 May 2003 522555-003 COBOL85 D32, D42, D44, D46; NMCOBOL D44.01, D46; TDS PC COBOL D45, G06.06; ETK PC COBOL G06.06, G06.15, G06.18, G06.20 April 2004 522555-006 COBOL85 D32, D42, D44, D46; NMCOBOL D44.01, D46; TDS PC COBOL D45, G06.06, H06.03; ETK PC COBOL G06.06, G06.15, G06.18, G06.20, H06.03 July 2005 HP COBOL Manual for TNS and TNS/R Programs Glossary Index What’s New in This Manual liii Manual Information liii New and Changed Information Examples Figures liv About This Manual lix Manuals to Which This Manual Refers Acknowledgment lxiv Notation Conventions lxv lix Part I. Features of HP COBOL 1. Introduction HP COBOL Language 1-1 Embedded SQL/MP 1-2 Embedded SQL/MX 1-2 Summary of Execution Modes 1-3 HP COBOL Compilers for TNS and TNS/R Programs 1-4 Guardian and OSS Environments 1-4 Compiler Input 1-5 Compiler Output 1-6 Combining Separately Compiled Source Programs 1-7 Executing Loadfiles 1-8 Guardian Environment 1-8 OSS Environment 1-8 2. Source Program Organization and Format Source Program Components 2-2 Reference Format for Source Program Lines Indicator Area 2-4 Area A and Area B 2-6 Restrictions 2-6 COPY Libraries 2-9 2-3 Hewlett-Packard Company—522555-006 i Tables 2. Source Program Organization and Format (continued) Contents 2. Source Program Organization and Format (continued) Nested Source Programs 2-9 Directly Contained Programs and Indirectly Contained Programs Scope of User-Defined Names 2-11 Common Programs 2-14 Programs in the Same Run Unit 2-14 Initial Programs 2-14 How Programs Share Resources 2-15 Global and Local Names 2-16 External and Internal Objects 2-17 Shared Data 2-18 Shared Files 2-24 3. Language Elements COBOL Character Set 3-2 Punctuation Characters 3-4 Separators 3-4 Comments 3-6 Nonnumeric and National Literals 3-6 Numeric Literals and PICTURE Character-Strings Character-Strings 3-6 COBOL Words 3-7 Literals 3-16 PICTURE Character-Strings 3-24 Comments 3-24 3-6 4. Data Fundamentals Data Levels, Classes, and Categories 4-1 Data Structures 4-2 Level-Numbers 4-2 Records 4-4 Files 4-6 Tables 4-12 Data Representation 4-14 Data Alignment in Receiving Items 4-15 Data Alignment in Memory 4-15 HP COBOL Manual for TNS and TNS/R Programs —522555-006 ii 2-10 4. Data Fundamentals (continued) Contents 4. Data Fundamentals (continued) Implicit FILLER Bytes 4-16 Records 4-17 Tables 4-17 REDEFINES Clause 4-18 References to Data Items 4-18 Qualifiers 4-19 Subscripts 4-19 Reference Modifiers 4-22 Identifiers 4-24 Condition-Names 4-25 5. Identification Division Identification Division Syntax 5-1 PROGRAM-ID Paragraph 5-4 DATE-COMPILED Paragraph 5-5 6. Environment Division Environment Division Syntax 6-2 Configuration Section 6-3 SOURCE-COMPUTER Paragraph 6-4 OBJECT-COMPUTER Paragraph 6-5 SPECIAL-NAMES Paragraph 6-10 Input-Output Section 6-22 FILE-CONTROL Paragraph 6-23 I-O-CONTROL Paragraph 6-57 RECEIVE-CONTROL Paragraph 6-64 7. Data Division Data Categories and Data Descriptions 7-2 Record Description Entries 7-2 Independent Data Item Description Entries File Section 7-3 File Description Entries 7-5 Sort-Merge File Description Entries 7-30 Data Description Entries 7-32 7-3 HP COBOL Manual for TNS and TNS/R Programs —522555-006 iii 7. Data Division (continued) Contents 7. Data Division (continued) Working-Storage Section 7-33 Data Description Entries 7-34 Initializing Data Items 7-36 Size Limits 7-36 Checkpointing 7-36 Extended-Storage Section 7-37 Data Description Entries and Initializing Data Items 7-37 Addressing 7-38 Size Limits 7-38 Checkpointing 7-38 Linkage Section 7-38 Data Description Entries and Initializing Data Items 7-39 ACCESS MODE Clause 7-39 CALL Statement and USING Phrase 7-40 Index-Names 7-42 Absent Linkage Section 7-42 Descriptions of Records (Levels 01-49) 7-43 General Considerations 7-44 FILLER Keyword 7-48 REDEFINES Clause 7-48 EXTERNAL Clause 7-52 GLOBAL Clause 7-53 PICTURE Clause 7-54 USAGE Clause 7-69 SIGN Clause 7-78 OCCURS Clause for Fixed-Size Tables 7-79 OCCURS Clause for Variable-Size Tables 7-83 SYNCHRONIZED Clause 7-86 JUSTIFIED Clause 7-87 BLANK WHEN ZERO Clause 7-88 VALUE Clause 7-89 Descriptions That Rename Items (Level 66) 7-91 Descriptions of Noncontiguous Elementary Items (Level 77) 7-93 Descriptions of Condition-Names for Values (Level 88) 7-95 HP COBOL Manual for TNS and TNS/R Programs —522555-006 iv 8. Procedure Division Contents 8. Procedure Division Procedure Division Components and Syntax 8-2 Statements 8-4 Sentences 8-10 Paragraphs 8-11 Sections 8-13 Procedures 8-14 Declaratives Portion 8-15 Execution of the Procedure Division 8-16 Statement Execution 8-16 Sentence Execution 8-17 Paragraph Execution 8-17 Section Execution 8-18 Procedure Execution 8-20 Declaratives Portion Execution 8-20 Common Semantic Rules 8-21 Operand Identification 8-21 Overlapping Operands 8-22 Common Phrases 8-22 CORRESPONDING Phrase 8-22 ROUNDED Phrase 8-23 SIZE ERROR Phrase 8-23 FROM Phrase 8-27 INTO Phrase 8-27 Input-Output 8-28 I-O Status Code 8-28 Diagnosing Input-Output Errors 8-33 Recovering from Input-Output Errors 8-39 Timed Input and Output 8-41 Arithmetic Operations 8-42 Common Features of Arithmetic Statements 8-43 Arithmetic Expressions 8-45 Arithmetic Precision 8-48 Conditional Expressions 8-53 Simple Conditions 8-53 Complex Conditions 8-64 Abbreviated Combined Relation Conditions 8-66 Condition Evaluation Rules 8-68 Concatenation Expressions 8-69 HP COBOL Manual for TNS and TNS/R Programs —522555-006 v 9. Procedure Division Verbs Contents 9. Procedure Division Verbs ACCEPT 9-1 ACCEPT With Mnemonic-Name 9-1 ACCEPT With DATE, DAY, DAY-OF-WEEK, or TIME Phrase ADD 9-9 ADD TO 9-9 ADD GIVING 9-12 ADD CORRESPONDING 9-14 ALTER 9-16 CALL 9-18 CANCEL 9-32 CHECKPOINT 9-34 CLOSE 9-37 CLOSE for Sequential and Line Sequential Files 9-37 CLOSE for Relative, Indexed, and Queue Files 9-40 COMPUTE 9-41 CONTINUE 9-44 COPY 9-44 DELETE 9-45 DISPLAY 9-47 DIVIDE 9-50 DIVIDE INTO 9-51 DIVIDE GIVING 9-53 DIVIDE GIVING REMAINDER 9-55 ENTER 9-58 ENTER COBOL 9-67 EVALUATE 9-67 EXIT 9-76 GO TO 9-81 Unconditional GO TO 9-81 Conditional GO TO 9-82 IF 9-83 Delimited-Scope Form 9-83 Conditional Form 9-86 INITIALIZE 9-91 9-6 HP COBOL Manual for TNS and TNS/R Programs —522555-006 vi 9. Procedure Division Verbs (continued) Contents 9. Procedure Division Verbs (continued) INSPECT 9-95 INSPECT TALLYING 9-95 INSPECT REPLACING 9-103 INSPECT TALLYING REPLACING 9-107 INSPECT CONVERTING 9-113 LOCKFILE 9-115 MERGE 9-119 MOVE 9-128 MOVE TO 9-128 MOVE CORRESPONDING 9-132 MULTIPLY 9-132 MULTIPLY BY 9-133 MULTIPLY GIVING 9-136 OPEN 9-138 PERFORM 9-157 Unconditional PERFORM 9-157 PERFORM TIMES 9-162 PERFORM UNTIL 9-164 PERFORM VARYING 9-166 READ 9-177 READ for Sequential or Dynamic Access 9-178 READ for Line Sequential Files 9-193 READ for Random or Dynamic Access 9-195 RELEASE 9-200 REPLACE 9-201 RETURN 9-201 REWRITE 9-202 REWRITE for Sequential, Relative, Indexed, and Queue Files REWRITE for Line Sequential Files 9-208 SEARCH 9-209 SEARCH VARYING 9-209 SEARCH ALL 9-214 SET 9-219 SET TO 9-219 SET UP or SET DOWN 9-225 SORT 9-227 START 9-237 STARTBACKUP 9-252 HP COBOL Manual for TNS and TNS/R Programs —522555-006 vii 9-202 9. Procedure Division Verbs (continued) Contents 9. Procedure Division Verbs (continued) STOP 9-256 STRING 9-257 SUBTRACT 9-262 SUBTRACT FROM 9-263 SUBTRACT GIVING 9-265 SUBTRACT CORRESPONDING 9-267 UNLOCKFILE 9-269 UNLOCKRECORD 9-270 UNSTRING 9-271 USE 9-283 USE DEBUGGING 9-284 USE AFTER EXCEPTION 9-288 WRITE 9-292 WRITE for Sequential Files 9-292 WRITE for Line Sequential Files 9-300 WRITE for Relative, Indexed, and Queue Files 9-301 10. Source Text Manipulation COPY Statement 10-2 REPLACING Phrase 10-7 COPY Libraries 10-11 Specifying Library Names Library Format 10-12 REPLACE Statement 10-14 10-11 11. Program Compilation Compiler Input 11-2 Main Programs 11-3 Calling and Called Programs 11-4 How an HP COBOL Program Calls a Non-COBOL Program 11-4 Compilation Units 11-5 Compilation Details 11-9 Processes Involved in Compilation 11-9 Temporary File Placement 11-11 CALL and ENTER Statement Processing: Overview 11-12 CALL and ENTER Statement Processing: Detailed Explanation 11-16 #RECEIVE Blocks 11-24 HP COBOL Manual for TNS and TNS/R Programs —522555-006 viii 11. Program Compilation (continued) Contents 11. Program Compilation (continued) Compiler Output 11-25 Listing Creation 11-26 Object File Creation 11-27 Manipulating Object Files 11-28 Compilation Statistics 11-29 Completion Codes 11-33 Running the Compiler 11-33 PARAM Commands 11-34 Predefined SEARCH DEFINEs 11-36 Starting a Compilation 11-38 Terminating a Compilation 11-44 Compiler Directives 11-44 Where Compiler Directives Are Allowed 11-45 Categories of Compiler Directives 11-47 ANSI 11-53 BLANK and NOBLANK 11-54 CALL-SHARED 11-55 CANCEL and NOCANCEL 11-56 CHECK 11-56 CODE and NOCODE 11-58 COLUMNS 11-59 COMPACT and NOCOMPACT 11-60 COMPILE 11-61 CONSULT and NOCONSULT 11-62 CROSSREF and NOCROSSREF 11-63 DIAGNOSE-74 and NODIAGNOSE-74 11-66 DIAGNOSE-85 and NODIAGNOSE-85 11-70 DIAGNOSEALL and NODIAGNOSEALL 11-71 ENDIF 11-71 ENDUNIT 11-72 ENV 11-72 ERRORFILE 11-75 ERRORS 11-76 FIPS and NOFIPS 11-76 FLOAT and NOFLOAT 11-78 FMAP 11-78 HEADING 11-79 HEAP 11-80 HP COBOL Manual for TNS and TNS/R Programs —522555-006 ix 11. Program Compilation (continued) Contents 11. Program Compilation (continued) Compiler Directives (continued) HIGHPIN 11-80 HIGHREQUESTERS 11-83 IICODE and NOICODE 11-83 IF and IFNOT 11-84 INNERLIST and NOINNERLIST 11-87 INSPECT and NOINSPECT 11-88 LARGEDATA 11-88 LD 11-91 LESS-CODE 11-91 LIBRARY 11-93 LINES 11-94 LIST and NOLIST 11-95 LMAP and NOLMAP 11-96 MAIN 11-98 MAP and NOMAP 11-99 NLD 11-99 NONSTOP 11-100 NON-SHARED 11-101 OPTIMIZE 11-102 PERFORM-TRACE 11-103 PORT and NOPORT 11-104 RESETTOG 11-106 RUNNABLE 11-107 RUNNAMED 11-108 SAVE 11-109 SAVEABEND and NOSAVEABEND 11-111 SEARCH and NOSEARCH 11-112 SECTION 11-114 SETTOG 11-115 SHARED 11-116 SHOWCOPY and NOSHOWCOPY 11-117 SHOWFILE and NOSHOWFILE 11-118 SOURCE 11-119 SQL and NOSQL 11-122 SQLMEM 11-124 SUBSET 11-125 SUBTYPE 11-128 HP COBOL Manual for TNS and TNS/R Programs —522555-006 x 11. Program Compilation (continued) Contents 11. Program Compilation (continued) Compiler Directives (continued) SUPPRESS and NOSUPPRESS 11-129 SYMBOLS and NOSYMBOLS 11-130 SYNTAX 11-131 TANDEM 11-132 TRAP2 and NOTRAP2 11-132 TRAP2-74 and NOTRAP2-74 11-134 UL 11-135 WARN and NOWARN 11-136 12. Program Execution RUN or RUND Command 12-2 ASSIGN Command 12-4 PARAM Command 12-9 CLEAR Command 12-17 DEFINEs 12-19 DEFINE and ASSIGN 12-19 Controlling the Propagation of DEFINEs 12-20 DEFINE Names 12-20 DEFINE Attributes 12-21 ADD DEFINE Command 12-23 Initial State 12-24 Status of Internal Entities During Program Execution 12-25 Status of External Entities During Program Execution 12-25 Called Program Termination 12-26 13. Libraries and Utility Routines Memory Areas 13-6 Linkfiles as Libraries 13-8 System Library 13-8 TNS User Library 13-8 User Library 13-9 Building a User Library 13-10 Specifying a User Library 13-10 Dynamic-Link Libraries (DLLs) 13-11 Building a DLL From a Single Source File Building a DLL from Multiple Source Files Specifying a DLL 13-19 13-11 13-15 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xi Contents 13. Libraries and Utility Routines (continued) 13. Libraries and Utility Routines (continued) Files of Dummy Routines 13-23 CBL85UTL Overview 13-23 FastSort Interface Overview 13-25 Establishing Parameters With FastSort Interface Routines 13-25 Establishing Parameters With =_SORT_DEFAULTS DEFINE 13-26 COBOLLIB Overview 13-26 COBOLLIB Routines in User Code Space 13-28 COBOLLIB Routines in User Library Space 13-28 COBOLLIB Routines in a Special TNS User Library 13-28 COBOLLIB Routines in System Code Space 13-29 ZCOBSRL Overview 13-29 CLULIB Overview 13-30 Saved Message Utility (SMU) Overview 13-31 Checkpoint Lists for Process Pairs 13-35 Defined Portions of Saved Messages 13-36 ZCRESRL Overview 13-37 CBL85UTL and ZCOBSRL Routines 13-38 COBOL85^ARMTRAP 13-39 COBOL85^COMPLETION and COBOL_COMPLETION_ 13-40 COBOL_CONTROL_ 13-43 COBOL_GETENV_ 13-45 COBOL_PUTENV_ 13-46 COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ 13-46 COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ 13-49 COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ 13-51 COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ 13-55 COBOL_SET_MAX_RECORD_ 13-66 COBOL_SETMODE_ 13-67 COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ 13-70 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xii 13. Libraries and Utility Routines (continued) Contents 13. Libraries and Utility Routines (continued) COBOLLIB, CLULIB, and ZCOBSRL Routines 13-85 COBOLASSIGN 13-86 COBOL_ASSIGN_ 13-89 COBOLFILEINFO 13-91 COBOL_FILE_INFO_ 13-93 COBOLSPOOLOPEN 13-95 CREATEPROCESS 13-101 Saved Message Utility (SMU) Routines 13-105 ALTERPARAMTEXT 13-106 CHECKLOGICALNAME 13-108 CHECKMESSAGE 13-110 DELETEASSIGN 13-111 DELETEPARAM 13-114 DELETESTARTUP 13-116 GETASSIGNTEXT 13-118 GETASSIGNVALUE 13-120 GETBACKUPCPU 13-122 GETPARAMTEXT 13-123 GETSTARTUPTEXT 13-125 PUTASSIGNTEXT 13-127 PUTASSIGNVALUE 13-131 PUTPARAMTEXT 13-133 PUTSTARTUPTEXT 13-136 Guardian Environment Level 3 Spooling Routines 13-139 14. Intrinsic Functions Intrinsic Function Types 14-3 Alphanumeric Intrinsic Functions 14-3 Numeric Intrinsic Functions 14-4 Integer Intrinsic Functions 14-5 Variable-Type Intrinsic Functions 14-6 Argument Types 14-6 ACOS Function 14-8 ANNUITY Function 14-9 ASIN Function 14-11 ATAN Function 14-12 CHAR Function 14-13 COS Function 14-15 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xiii 14. Intrinsic Functions (continued) Contents 14. Intrinsic Functions (continued) CURRENT-DATE Function 14-16 DATE-OF-INTEGER Function 14-17 DAY-OF-INTEGER Function 14-18 FACTORIAL Function 14-19 INTEGER Function 14-20 INTEGER-OF-DATE Function 14-21 INTEGER-OF-DAY Function 14-23 INTEGER-PART Function 14-24 LENGTH Function 14-25 LOG Function 14-26 LOG10 Function 14-27 LOWER-CASE Function 14-28 MAX Function 14-29 MEAN Function 14-31 MEDIAN Function 14-32 MIDRANGE Function 14-34 MIN Function 14-35 MOD Function 14-37 NUMVAL Function 14-38 NUMVAL-C Function 14-40 ORD Function 14-43 ORD-MAX Function 14-43 ORD-MIN Function 14-45 PRESENT-VALUE Function 14-47 RANDOM Function 14-49 RANGE Function 14-50 REM Function 14-52 REVERSE Function 14-53 SIN Function 14-54 SQRT Function 14-55 STANDARD-DEVIATION Function 14-56 SUM Function 14-58 TAN Function 14-60 UPPER-CASE Function 14-61 VARIANCE Function 14-62 WHEN-COMPILED Function 14-63 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xiv 15. Debugging Tools Contents 15. Debugging Tools Standard COBOL Debugging Tools Run-Time Debuggers 15-4 Visual Inspect 15-4 Inspect 15-5 Debug 15-5 Debugger Selection 15-6 CROSSREF Utility Program 15-8 FIXERRS Macro 15-10 15-1 16. ANSI Reference Format Sequence Number Area 16-1 Indicator Area 16-2 Compiler Directive 16-2 Ordinary Comment 16-2 Comment for Top of Page 16-2 Debugging Line 16-2 Continuation Line 16-3 Area A 16-4 Area B 16-4 Identification Field 16-4 17. HP Extensions to ISO COBOL Source Program Organization and Format Language Elements 17-2 Data Fundamentals 17-2 Environment Division 17-3 Data Division 17-3 Procedure Division Verbs 17-4 17-1 18. HP COBOL CRE Support Introducing the CRE 18-2 Compiler Directives 18-3 Volume Names 18-3 Shared File Operations 18-4 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xv Contents 18. HP COBOL CRE Support (continued) 18. HP COBOL CRE Support (continued) $RECEIVE Processing 18-4 EXTERNAL Clause 18-5 MESSAGE SOURCE Clause 18-5 REPORT Clause 18-5 Message Format 18-6 Message Replies 18-6 Arithmetic Overflow Processing 18-6 TNS HP COBOL Programs in TNS User Libraries 18-6 CHECKPOINT Access to Extended-Storage Section 18-6 CBL85UTL Routines 18-7 COBOLLIB Routines 18-8 COBOLASSIGN 18-8 COBOLFILEINFO 18-8 COBOLSPOOLOPEN 18-8 19. Using HP COBOL in the OSS Environment Running the COBOL85 Compiler 19-2 Running the NMCOBOL Compiler 19-3 Running HP COBOL Programs 19-4 Calling OSS Functions From HP COBOL Programs 19-4 Mixed-Language Programs 19-5 TNS Programs 19-5 Native Programs 19-6 Changing Default Pathnames and Disk Volume 19-6 Files in the OSS Environment 19-8 OSS Pathnames 19-8 OSS Pathnames in HP COBOL Source Programs 19-10 OSS Files in HP COBOL Source Programs 19-11 #IN and #OUT 19-11 Line Sequential Files 19-11 File-Control Entries 19-12 File Description Entries 19-14 I-O-CONTROL Paragraph 19-15 OPEN Statement 19-17 READ Statement 19-20 REWRITE Statement 19-21 WRITE Statement 19-22 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xvi 19. Using HP COBOL in the OSS Environment (continued) Contents 19. Using HP COBOL in the OSS Environment (continued) Features Unavailable in the OSS Environment 19-23 ASSIGN Commands 19-23 PARAM Commands 19-23 Compiler Directives 19-24 Process Pairs 19-24 Features That Operate Differently in the OSS Environment ACCEPT and DISPLAY Statements 19-24 Utility Routines 19-25 19-24 20. HP COBOL Limits Size 20-1 Number 20-4 Callability 20-7 External Names 20-7 Ranges of Values 20-7 Ignored Elements 20-8 21. Reserved Words All Reserved Words 21-1 HP Reserved Words 21-11 Part II. Programming in HP COBOL 22. Creating and Compiling HP COBOL Source Programs Using the TACL Command Log 22-2 Displaying Previous Commands 22-2 Reexecuting Previous Commands 22-3 Editing and Reexecuting Previous Commands 22-4 Creating or Altering an HP COBOL Source Program 22-5 EDIT Files 22-5 Reference Format 22-6 EDIT Editor 22-7 TEDIT Editor 22-8 HP Tandem Extensions for Codewright (TEC) 22-11 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xvii Contents 22. Creating and Compiling HP COBOL Source Programs (continued) 22. Creating and Compiling HP COBOL Source Programs (continued) Compiling an HP COBOL Source Program 22-13 Running the Compiler 22-13 Naming the Object File 22-16 Specifying the Default COPY Library 22-18 Specifying Compiler Directives 22-18 Specifying Subvolumes to Be Searched for Unqualified Files 22-19 Changing the Compilation Environment 22-20 Improving Compilation Speed 22-22 Launching Compilations to Run Unattended 22-22 Using COPY and SOURCE Libraries 22-22 Creating or Altering a COPY or SOURCE Library 22-24 Using an HP Editor 22-24 Using Data Definition Language (DDL) 22-25 Including Text From a COPY Library 22-29 Including Text From a SOURCE Library 22-34 Replacing Text-Words in an HP COBOL Source Program 22-36 Replacing Substrings 22-37 Replacing Text-Words From COPY Libraries 22-38 Replacing Text-Words From SOURCE Libraries 22-39 Understanding and Controlling the Compiler Listing 22-39 Compilation Banner 22-41 Source Program Listing 22-42 Diagnostic Messages 22-49 Symbol Table Listing 22-53 Octal Code Listing 22-54 Symbolic Code Listing 22-55 Cross-Reference Listing 22-63 Load Maps 22-63 Compilation Summary 22-64 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xviii Contents 23. Calling Other Programs and Routines 23. Calling Other Programs and Routines Run-Time Environment 23-2 Calling Other COBOL Programs 23-3 Separately Compiled HP COBOL Programs 23-3 Nested HP COBOL Programs 23-4 Common Programs 23-5 Initial Programs 23-5 Static Calls 23-5 Dynamic Calls 23-6 Calling Non-COBOL Routines 23-7 ENTER Statement 23-7 X/Open CALL Statement 23-9 Functions (Routines That Return Values) 23-9 Operating System Routines 23-10 HP COBOL Run-Time Routines 23-15 COBOL Utility Routines 23-15 ENFORM Programs 23-15 Restrictions on Calling Non-COBOL Routines 23-16 Passing Parameters 23-19 TNS Addressing Modes 23-20 Native Addressing Modes 23-20 What HP COBOL Can Pass by Content 23-21 What HP COBOL Can Pass by Reference 23-23 What HP COBOL Can Pass by Value 23-23 Passing Parameters to COBOL Programs 23-24 Passing Parameters to Non-COBOL Routines 23-25 24. Issues Related to Binding and Linking Concepts and Terms 24-1 Code and Data Blocks 24-1 Binding or Linking 24-4 Loadfiles, Linkfiles, and Processes 24-8 Fixup 24-8 Binding or Linking HP COBOL Programs 24-9 Binding or Linking Automatically 24-10 Binding or Linking Programs to Be Called Dynamically Binding With BIND 24-14 Binding or Linking Mixed-Language Programs 24-16 Accelerating TNS HP COBOL Programs 24-16 24-14 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xix 24. Issues Related to Binding and Linking (continued) Contents 24. Issues Related to Binding and Linking (continued) Designing Programs With Large Amounts of Code 24-17 Separate Programs 24-18 Separate Processes 24-19 TNS User Library 24-19 Designing Programs With Large Amounts of Data 24-21 Extended-Storage Section 24-21 LESS-CODE Directive 24-22 COBOL Segmentation 24-23 25. Executing and Debugging HP COBOL Programs Preparing to Execute an HP COBOL Program 25-1 Adding DEFINEs 25-2 Overriding File Assignments Made at Compilation Time 25-3 Specifying Characteristics of Files That a Program Creates 25-4 Enabling Debugging Declaratives 25-4 Overriding the NONSTOP Directive 25-5 Specifying a Default Input-Output Device 25-5 Providing for an Unavailable Printer 25-6 Turning On External Switches 25-6 Requesting a Debugger Instead of ABEND 25-6 Specifying Waited Input-Output 25-7 Using OBEY Files to Prepare for Execution 25-7 Finding Out What Preparation Commands Are Already Active 25-8 Changing or Clearing Unwanted Preparation Commands 25-9 Executing an HP COBOL Program 25-9 Starting an HP COBOL Program From a TACL Prompt 25-10 Specifying Default Input and Output Devices 25-10 Specifying the Home Terminal 25-11 Naming the New Process 25-12 Running the New Process in the Background 25-13 Run-Time Errors 25-13 Getting a Program to Enter Debugging Mode 25-15 Before Execution 25-15 Programmatically 25-15 Forcefully 25-15 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xx 26. Input and Output Concepts Contents 26. Input and Output Concepts Files 26-1 System File Names 26-2 COBOL File Names 26-4 Associating COBOL File Names With System File Names Prereading File Records 26-10 Processes Handled as Files 26-10 Intercepting Operating System Messages 26-10 26-5 27. Tape Input and Output Reading and Writing Tape Files 27-1 Preventing Prereading 27-1 Saving Tape and Time 27-2 Unlabeled Tape Files 27-3 Labeled Tape Files 27-8 Tape Files of Types Other Than HP 27-12 Adding DEFINEs for Tape Files 27-15 Unlabeled Tape Files 27-16 Labeled Tape Files 27-18 Executing HP COBOL Programs That Use Tape Files Mount Messages 27-24 Run-Time Errors 27-26 27-24 28. Disk Input and Output Common Disk File Topics 28-1 Allocation 28-2 Partitioned Files 28-2 Purging Files or Their Data 28-2 Locking 28-3 Ownership and Security 28-3 Fixed-Length and Variable-Length Records 28-6 Exclusion Modes 28-6 Time Limits 28-7 Reading Files From Called Programs 28-7 Sharing Files Among HP COBOL Programs 28-8 Sharing Files Among Different-Language Modules 28-8 Modification 28-9 Maximum Number of Files 28-9 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxi 28. Disk Input and Output (continued) Contents 28. Disk Input and Output (continued) Types of HP Disk Files 28-9 Unstructured (Sequential) Files 28-9 Structured Files 28-10 Creating and Using HP COBOL Sequential Files 28-14 Entry-Sequenced Files 28-14 Unstructured Files 28-15 EDIT Files 28-16 Creating and Using HP COBOL Relative Files 28-16 Creating and Using HP COBOL Indexed Files 28-17 Creating and Using Queue Files 28-19 Creating a Queue File 28-19 Opening a Queue File 28-19 Reading a Queue File 28-20 Writing to a Queue File 28-20 Establishing Starting Points in Files 28-20 Key of Reference 28-21 Alternate Record Keys 28-22 Positioning 28-23 Repositioning to New Record With Same Alternate Key 28-26 Optimizing Disk File Processing 28-31 Unstructured Files 28-31 Structured Files 28-31 Files With Alternate Keys 28-35 Partitioned Files 28-37 Optimizing Disk File Storage 28-37 Avoiding Deadlock 28-38 Locking and Unlocking Files and Records 28-38 Setting Time Limits on Input-Output Operations 28-39 Using Enscribe and Operating System Routines 28-40 Physical File Names 28-41 Obtaining File Numbers and Other File Attributes 28-41 Determining Whether Two COBOL File Names Specify the Same Physical File 28-42 Purging a File From an HP COBOL Program 28-43 Purging the Contents of a File From an HP COBOL Program 28-44 Renaming a File From an HP COBOL Program 28-44 Creating a File Having Alternate Keys From an HP COBOL Program 28-45 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxii 29. Terminal Input and Output Contents 29. Terminal Input and Output Using ACCEPT and DISPLAY With a Terminal 29-2 Guardian Environment 29-2 OSS Environment 29-4 Using a Terminal as a File 29-4 Prompting the Terminal Operator for Input 29-6 Sharing a Terminal 29-7 Terminal Associated With a Command Interpreter 29-8 Terminal Not Associated With a Command Interpreter 29-8 Non-COBOL Modules 29-8 Getting Break Ownership 29-8 Transferring Break Ownership 29-9 Communicating With an Operator or Process 29-10 Writing to a Console 29-11 Writing to a Terminal or Printer 29-12 Reading From a Terminal or Process 29-12 Reading and Writing Numeric Data 29-13 Logging Program Activity Information to a Terminal 29-14 30. Printer and Spooler Output Using a Printer Directly 30-1 Understanding Spoolers 30-2 Spooler Components 30-2 Jobs 30-4 Using a Spooler 30-7 Spooling Compiler Listings 30-8 Spooling Program Output 30-8 Using PERUSE 30-11 Using SPOOLCOM 30-15 Controlling Vertical Spacing in a Printed Report 30-18 Skipping Lines 30-19 Overprinting Lines 30-19 Skipping to a Printer Control Tape Channel Punch 30-19 Skipping to a New Page 30-20 Formatting Pages of a Printed Report 30-20 Logging Program Activity Information to a Printer 30-22 DISPLAY 30-22 WRITE 30-22 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxiii 31. Process Initiation, Communication, and Management Contents 31. Process Initiation, Communication, and Management Memory and Virtual Memory 31-2 Initiating a Process From an HP COBOL Program 31-3 Communicating With a Process 31-6 $RECEIVE 31-6 Process Names 31-12 Example of Simple Interprocess Communication 31-13 RECEIVE-CONTROL Paragraph 31-16 At-End Condition 31-17 Summary of $RECEIVE Rules 31-17 Simple Server Example 31-18 Managing a Process 31-22 Determining the Process Handle 31-22 Determining the Node (System Number) 31-23 Identifying the Message Source 31-24 Determining the Status 31-26 Identifying the Creator 31-33 Monitoring Descendants’ Completion 31-35 Changing the Creator ID 31-39 Suspending a Process 31-39 32. Fault-Tolerant Processes NonStop Operating System 32-2 Introduction to the Fault-Tolerant Facility 32-2 Introduction to TMF 32-3 Choosing the Fault-Tolerant Facility or TMF 32-3 Fault-Tolerant Facility 32-3 Process Pairs 32-4 Checkpointing 32-6 Using the Fault-Tolerant Facility 32-9 Designing Programs for the Fault-Tolerant Facility 32-13 Debugging Programs That Use the Fault-Tolerant Facility 32-14 TMF 32-14 Concepts 32-15 Designing Programs for the TMF Subsystem 32-18 The TMF Subsystem and Requester Screen Transactions 32-19 The TMF Subsystem for Batch Jobs 32-19 Debugging Programs That Use the TMF Subsystem 32-20 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxiv Contents 33. Migrating TNS Programs to Native Programs 33. Migrating TNS Programs to Native Programs Reasons to Migrate 33-2 Migrating HP COBOL Programs 33-3 Data Alignment 33-6 Misalignment Tracing Facility 33-7 Misalignment Handling 33-8 Causes of Misalignment in HP COBOL Programs 33-10 Source Program Changes 33-13 General Migration Tasks 33-13 Removal Required 33-13 Possible Changes Required 33-15 Removal Optional 33-18 New Features (Optional) 33-20 Development and Management Changes 33-21 Maintaining Common Source Code 33-23 Using the Inspect and Visual Inspect Debuggers 33-23 34. Native COBOL Cross Compiler on PC Cross Compiler Features 34-2 NonStop COBOL for TNS/R (ETK) 34-3 Tandem COBOL (TDS) 34-4 nmcobol (PC Command Line) 34-4 Linking 34-7 Debugging 34-7 ETK and TDS Platforms 34-7 Command-Line Platform 34-8 RUNV 34-8 Tools and Utilities 34-10 NonStop ar Utility 34-10 TACL DEFINE Tool (ETK and TDS) 34-10 PC-to-NonStop-Host Transfer Tools 34-11 Documentation 34-11 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxv 35. Commands Contents Part III. Syntax Summary 35. Commands Guardian Environment 35-1 Before Running the Compiler (Optional) 35-1 Running the COBOL85 Compiler 35-2 Running the NMCOBOL Compiler 35-3 Running the Native Cross Compiler Under Visual Inspect Before Running the Compiled Program (Optional) 35-5 Running the Compiled Program 35-9 OSS Environment 35-9 Before Running the Compiler (Optional) 35-10 Running the cobol (COBOL85) Compiler 35-11 Running the nmcobol Compiler 35-11 Running the Compiled Program 35-12 nmcobol (PC Command Line) 35-13 35-4 36. Compiler Directives ANSI 36-4 BLANK and NOBLANK 36-4 CALL-SHARED 36-5 CANCEL and NOCANCEL 36-5 CHECK 36-6 CODE and NOCODE 36-7 COLUMNS 36-8 COMPACT and NOCOMPACT 36-8 COMPILE 36-9 CONSULT and NOCONSULT 36-9 CROSSREF and NOCROSSREF 36-10 DIAGNOSE-74 and NODIAGNOSE-74 36-11 DIAGNOSE-85 and NODIAGNOSE-85 36-11 DIAGNOSEALL and NODIAGNOSEALL 36-12 ENDIF 36-12 ENDUNIT 36-12 ENV 36-13 ERRORFILE 36-13 ERRORS 36-13 FIPS and NOFIPS 36-14 FLOAT and NOFLOAT 36-15 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxvi 36. Compiler Directives (continued) Contents 36. Compiler Directives (continued) FMAP 36-15 HEADING 36-16 HEAP 36-16 HIGHPIN 36-17 HIGHREQUESTERS 36-18 ICODE and NOICODE 36-18 IF and IFNOT 36-19 INNERLIST and NOINNERLIST 36-19 INSPECT and NOINSPECT 36-20 LARGEDATA 36-20 LD 36-21 LESS-CODE 36-21 LIBRARY 36-23 LINES 36-23 LIST and NOLIST 36-24 LMAP and NOLMAP 36-25 MAIN 36-26 MAP and NOMAP 36-26 NLD 36-27 NONSTOP 36-27 NON-SHARED 36-28 OPTIMIZE 36-29 PERFORM-TRACE 36-30 PORT and NOPORT 36-30 RESETTOG 36-31 RUNNABLE 36-32 RUNNAMED 36-33 SAVE 36-34 SAVEABEND and NOSAVEABEND 36-35 SEARCH and NOSEARCH 36-36 SECTION 36-36 SETTOG 36-37 SHARED 36-38 SHOWCOPY and NOSHOWCOPY 36-38 SHOWFILE and NOSHOWFILE 36-39 SOURCE 36-40 SQL and NOSQL 36-41 SQLMEM 36-42 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxvii 36. Compiler Directives (continued) Contents 36. Compiler Directives (continued) SUBSET 36-43 SUBTYPE 36-44 SUPPRESS and NOSUPPRESS 36-44 SYMBOLS and NOSYMBOLS 36-45 SYNTAX 36-46 TANDEM 36-46 TRAP2 and NOTRAP2 36-47 TRAP2-74 and NOTRAP2-74 36-48 UL 36-48 WARN and NOWARN 36-49 37. Source Program Organization and Format Separately Compiled Source Program Reference Format 37-2 TANDEM 37-2 ANSI 37-3 37-1 38. Language Elements and Expressions COBOL Character Set 38-1 Character-Strings 38-3 COBOL Word 38-3 Literals 38-3 PICTURE Character-Strings 38-6 Arithmetic Expressions 38-8 Conditional Expressions 38-9 Simple Relation Condition 38-9 Simple Class Condition 38-11 Simple Sign Condition 38-12 Negated Condition 38-12 Combined Condition 38-12 Abbreviated Combined Relation Condition Concatenation Expressions 38-13 38-12 39. Data References Qualified Condition-Name 39-1 Qualified Data-Name 39-1 Qualified Paragraph-Name 39-2 Qualified Text-Name 39-2 Qualified LINAGE-COUNTER 39-2 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxviii 39. Data References (continued) Contents 39. Data References (continued) Qualified Identifier 39-2 Subscripted Table Element 39-3 Reference Modifier 39-3 OSS Pathname for OSS File 39-3 OSS Pathname for Guardian File 39-4 40. Identification Division 41. Environment Division Configuration Section 41-1 SOURCE-COMPUTER Paragraph 41-2 OBJECT-COMPUTER Paragraph 41-2 SPECIAL-NAMES Paragraph 41-4 Input-Output Section 41-7 FILE-CONTROL Paragraph 41-8 I-O-CONTROL Paragraph 41-17 RECEIVE-CONTROL Paragraph 41-19 42. Data Division File Descriptions 42-3 Sequential File 42-3 Line Sequential File 42-7 Relative, Indexed, or Queue File 42-8 Sort-Merge File 42-8 Data Descriptions 42-9 Record Item (Levels 01 through 49) 42-10 Level-66 Item 42-13 Level-77 Item 42-13 Level-88 Item 42-14 Clause for Data Descriptions in the Linkage Section 42-14 43. Procedure Division ACCEPT With Mnemonic-Name 43-5 ACCEPT With DATE, DAY, DAY-OF-WEEK, or TIME Phrase ADD TO 43-6 ADD GIVING 43-7 ADD CORRESPONDING 43-8 ALTER 43-8 CALL 43-9 43-5 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxix 43. Procedure Division (continued) Contents 43. Procedure Division (continued) CANCEL 43-10 CHECKPOINT 43-11 CLOSE for Sequential and Line Sequential Files 43-11 CLOSE for Relative, Indexed, and Queue Files 43-12 COMPUTE 43-12 CONTINUE 43-12 COPY 43-13 DELETE 43-15 DISPLAY 43-15 DIVIDE INTO 43-16 DIVIDE GIVING 43-17 DIVIDE GIVING REMAINDER 43-18 ENTER 43-18 ENTER COBOL 43-19 EVALUATE 43-19 EXIT 43-21 Unconditional GO TO 43-21 Conditional GO TO 43-21 Delimited-Scope IF 43-21 Conditional IF 43-22 INITIALIZE 43-22 INSPECT TALLYING 43-23 INSPECT REPLACING 43-23 INSPECT TALLYING REPLACING 43-25 INSPECT CONVERTING 43-27 LOCKFILE 43-27 MERGE 43-28 MOVE TO 43-29 MOVE CORRESPONDING 43-29 MULTIPLY BY 43-30 MULTIPLY GIVING 43-31 OPEN 43-32 Unconditional PERFORM 43-35 PERFORM TIMES 43-35 PERFORM UNTIL 43-36 PERFORM VARYING 43-37 READ for Sequential or Dynamic Access 43-38 READ for Line Sequential Access 43-39 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxx 43. Procedure Division (continued) Contents 43. Procedure Division (continued) READ for Random or Dynamic Access 43-40 RELEASE 43-40 REPLACE 43-41 RETURN 43-42 REWRITE for Sequential, Relative, Indexed, and Queue Files REWRITE for Line Sequential Files 43-43 SEARCH VARYING 43-43 SEARCH ALL 43-44 SET TO for Pointer Data Items 43-45 SET TO for Nonpointer Data Items 43-45 SET UP or SET DOWN for Pointer Data Items 43-46 SET UP or SET DOWN for Nonpointer Data Items 43-46 SORT 43-46 START 43-48 STARTBACKUP 43-50 STOP 43-50 STRING 43-51 SUBTRACT FROM 43-52 SUBTRACT GIVING 43-53 SUBTRACT CORRESPONDING 43-54 UNLOCKFILE 43-54 UNLOCKRECORD 43-54 UNSTRING 43-55 USE DEBUGGING 43-56 USE AFTER EXCEPTION 43-57 WRITE for Sequential Files 43-57 WRITE for Line Sequential Files 43-59 WRITE for Relative, Indexed, and Queue Files 43-59 43-42 44. Intrinsic Function Calls ACOS 44-2 ANNUITY 44-2 ASIN 44-3 ATAN 44-3 CHAR 44-3 COS 44-3 CURRENT-DATE 44-3 DATE-OF-INTEGER 44-4 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxxi 44. Intrinsic Function Calls (continued) Contents 44. Intrinsic Function Calls (continued) DAY-OF-INTEGER 44-4 FACTORIAL 44-4 INTEGER 44-4 INTEGER-OF-DATE 44-4 INTEGER-OF-DAY 44-4 INTEGER-PART 44-5 LENGTH 44-5 LOG 44-5 LOG10 44-5 LOWER-CASE 44-5 MAX 44-5 MEAN 44-6 MEDIAN 44-6 MIDRANGE 44-6 MIN 44-6 MOD 44-6 NUMVAL 44-7 NUMVAL-C 44-8 ORD 44-9 ORD-MAX 44-9 ORD-MIN 44-9 PRESENT-VALUE 44-9 RANDOM 44-9 RANGE 44-10 REM 44-10 REVERSE 44-10 SIN 44-10 SQRT 44-10 STANDARD-DEVIATION 44-11 SUM 44-11 TAN 44-11 UPPER-CASE 44-11 VARIANCE 44-11 WHEN-COMPILED 44-12 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxxii 45. CBL85UTL and ZCOBSRL Routine Calls Contents 45. CBL85UTL and ZCOBSRL Routine Calls COBOL85^ARMTRAP 45-2 COBOL85^COMPLETION 45-2 COBOL_COMPLETION_ 45-3 COBOL_CONTROL_ 45-3 COBOL_GETENV_ 45-4 COBOL_PUTENV_ 45-4 COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ 45-4 COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ 45-5 COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ 45-6 COBOL_SET_MAX_RECORD_ 45-6 COBOL_SETMODE_ 45-7 COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ 45-7 For Spoolers and Printers 45-8 For System Log Files 45-9 For Partitioned Disk Files 45-9 For Tape Files in the CRE 45-10 46. COBOLLIB, CLULIB, and ZCRESRL Routine Calls SMU Routines 46-1 ALTERPARAMTEXT 46-3 CHECKLOGICALNAME 46-3 CHECKMESSAGE 46-4 DELETEASSIGN 46-4 DELETEPARAM 46-5 DELETESTARTUP 46-5 GETASSIGNTEXT 46-6 GETASSIGNVALUE 46-6 GETBACKUPCPU 46-7 GETPARAMTEXT 46-7 GETSTARTUPTEXT 46-8 PUTASSIGNTEXT 46-8 PUTASSIGNVALUE 46-9 PUTPARAMTEXT 46-9 PUTSTARTUPTEXT 46-10 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxxiii 45-5 46. COBOLLIB, CLULIB, and ZCRESRL Routine Calls (continued) Contents 46. COBOLLIB, CLULIB, and ZCRESRL Routine Calls (continued) Non-SMU Routines 46-10 COBOLASSIGN 46-11 COBOL_ASSIGN_ 46-11 COBOLFILEINFO 46-12 COBOL_FILE_INFO_ 46-12 COBOLSPOOLOPEN 46-13 CREATEPROCESS 46-14 Part IV. Error Message Summary 47. Compiler Diagnostic Messages Message Indicator Line 47-2 Warning Message Format 47-3 Error Message Format 47-3 Failure Message Format 47-3 Message List 47-4 Other Products’ Error Messages 47-95 NMCGEN 47-95 SCI 47-95 48. Run-Time Diagnostic Messages Sources of Run-Time Diagnostic Messages 48-1 Where Messages Are Reported 48-1 Standard Message Format—Non-CRE Environment Standard Message Format—CRE 48-5 Input-Output Error Messages 48-6 SORT Error Messages 48-6 Guardian Abnormal Termination Messages 48-7 Abend 48-7 Arithmetic Overflow 48-8 Stack Overflow 48-9 How to Use the Message List 48-10 Message List 48-15 48-2 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxxiv A. ASCII Character Set Contents Part V. Appendixes A. ASCII Character Set ASCII Character Set in Numeric Order A-1 ASCII Character Set in Alphabetic Order A-6 B. Data Type Correspondence Glossary Index Examples Example i. Example ii. Example 2-1. Example 2-2. Example 2-3. Example 3-1. Example 3-2. Example 3-3. Example 3-4. Example 3-5. Example 3-6. Example 4-1. Example 4-2. Example 4-3. Example 4-4. Example 4-5. Example 4-6. Example 4-7. Example 4-8. Example 4-9. Example 4-10. Example 5-1. Example 5-2. Example 5-3. Example 6-1. Example 6-2. Example 6-3. Code Example Without Ellipsis (...) lxx Code Example With Ellipsis lxx Continuation Line in Tandem Reference Format 2-5 Programs With Shared Data 2-19 Output From Programs With Shared Data 2-23 Qualified Names 3-15 Integer Decimal Numeric Literals 3-18 Noninteger Decimal Numeric Literals 3-18 Hexadecimal Numeric Literals 3-18 Nonnumeric Literals 3-19 Hexadecimal Nonnumeric Literals 3-20 Level Numbers 4-3 Logical Record 4-4 One-Dimensional Table With Fixed Number of Elements 4-13 One-Dimensional Table With Variable Number of Elements 4-13 Multidimensional Table 4-14 REDEFINES Clause 4-18 Subscripting for Tables 4-21 Reference Modifiers 4-24 Identifiers 4-25 Condition-Name 4-26 Identification Division With Obsolete Paragraphs 5-3 Identification Division With Comments 5-4 DATE-COMPILED Paragraph 5-6 ON STATUS Phrase 6-14 Defining a Class of Vowels 6-20 Defining a Class of Special Characters 6-20 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxxv Examples (continued) Contents Examples (continued) Example 6-4. Example 6-5. Example 6-6. Example 6-7. Example 6-8. Example 6-9. Example 6-10. Example 7-1. Example 7-2. Example 7-3. Example 7-4. Example 7-5. Example 7-6. Example 7-7. Example 7-8. Example 7-9. Example 7-10. Example 7-11. Example 7-12. Example 7-13. Example 7-14. Example 7-15. Example 7-16. Example 7-17. Example 7-18. Example 7-19. Example 7-20. Example 7-21. Example 7-22. Example 7-23. Example 8-1. Example 8-2. Example 8-3. Example 8-4. Example 8-5. Example 8-6. Example 8-7. Example 8-8. Defining a Class of Octal Numerics 6-21 FILE-CONTROL Paragraph for Sequential File 6-37 Relative File Used for Random Access 6-46 Indexed File With One Alternate Key 6-53 File-Control Entry for Sort-Merge File 6-56 MESSAGE SOURCE Phrase (Non-CRE) 6-72 MESSAGE SOURCE Phrase (CRE) 6-73 Level-77 Description Entries 7-3 File Description (FD) Entry 7-6 Variable-Length Record 7-21 LINAGE Clauses 7-25 Sort-Merge File Description Entry 7-32 Record Description Entries 7-35 Correspondence Between Formal and Actual Parameters 7-41 File Description Entry Followed by Record Description Entry 7-47 Record Description Entries as Data Declarations 7-47 FILLER Keyword 7-48 REDEFINES Clause 7-49 Alphabetic Data Items 7-61 Numeric Data Items 7-61 Alphanumeric Data Items 7-61 Alphanumeric Edited Data Items 7-62 Numeric Edited Data Items 7-62 Fixed-Size Table 7-83 Variable-Size Table 7-86 Fixed-Size Table as an Element of a Variable-Size Table 7-86 VALUE Clauses 7-90 Level-66 Data Description Entry 7-91 Condition-Names for Values (Level 88) 7-96 VALUE Clauses for a Level-88 Data Item 7-96 Procedure Division 8-3 Imperative Statement 8-6 Conditional Statement 8-7 Delimited-Scope Statement 8-7 Compiler-Directing Statement 8-8 Paragraph With One Sentence 8-11 Paragraph With Several Sentences 8-11 Procedure Division with a Declaratives Portion 8-16 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxxvi Examples (continued) Contents Examples (continued) Example 8-9. Example 8-10. Example 8-11. Example 8-12. Example 8-13. Example 8-14. Example 8-15. Example 9-1. Example 9-2. Example 9-3. Example 9-4. Example 9-5. Example 9-6. Example 9-7. Example 9-8. Example 9-9. Example 9-10. Example 9-11. Example 9-12. Example 9-13. Example 9-14. Example 9-15. Example 9-16. Example 9-17. Example 9-18. Example 9-19. Example 9-20. Example 9-21. Example 9-22. Example 9-23. Example 9-24. Example 9-25. Example 9-26. Example 9-27. Example 9-28. Example 9-29. CORRESPONDING Phrase 8-23 SIZE ERROR Phrase and TRAP2 Directive 8-25 Simple Relation Conditions 8-57 Conditional Variables 8-62 External Switches 8-62 Sign Conditions 8-63 Concatenation Expressions 8-70 ACCEPT Statement Reading From a Terminal 9-4 ACCEPT Statement Reading Alphanumeric Data 9-4 ACCEPT Statement Reading Numeric Data 9-5 ACCEPT Statements Reading Current Data and Time 9-8 ADD CORRESPONDING Statement 9-16 ALTER Statement 9-17 Alternative to ALTER Statement 9-17 Called Program That Calls Another Program 9-29 COMPUTE Statement 9-42 Combination of IF and COMPUTE Statements 9-43 CONTINUE Statement 9-44 DELETE Statement 9-47 DISPLAY Statement 9-48 DIVIDE INTO Statement With GIVING and REMAINDER Phrases 9-57 DIVIDE BY Statement With GIVING and REMAINDER Phrases 9-57 Calling a pTAL Routine That Does Not Ignore Trailing Spaces 9-65 HP COBOL Program Calling TAL Routine 9-66 HP COBOL Program Calling TAL Routine in Object File 9-66 EVALUATE Statement as “Case” Statement 9-70 EVALUATE Statement With Both Ranges and Discrete Values 9-70 EVALUATE Statement With Two Distinct Subjects 9-71 EVALUATE Statement as a Decision Table 9-71 EXIT PERFORM Statement 9-78 EXIT PERFORM CYCLE Statement 9-79 EXIT Statement in Nested In-Line PERFORM Statement 9-80 Three-Way Conditional GO TO Statement 9-83 Simple Conditional IF Statement 9-89 Delimited-Scope IF Statement 9-89 Simple Conditional IF ELSE Statement 9-89 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxxvii Examples (continued) Contents Examples (continued) Example 9-30. Example 9-31. Example 9-32. Example 9-33. Example 9-34. Example 9-35. Example 9-36. Example 9-37. Example 9-38. Example 9-39. Example 9-40. Example 9-41. Example 9-42. Example 9-43. Example 9-44. Example 9-45. Example 9-46. Example 9-47. Example 9-48. Example 9-49. Example 9-50. Example 9-51. Example 9-52. Example 9-53. Example 9-54. Example 9-55. Example 9-56. Example 9-57. Example 9-58. Example 9-59. Example 9-60. Example 9-61. Example 9-62. Example 9-63. Example 9-64. Delimited-Scope IF ELSE Statement 9-89 IF ELSE Statement Nested Within PERFORM Statement 9-89 Delimited-Scope IF ELSE Statement Nested Within PERFORM Statement 9-89 Nested Conditional IF Statements 9-90 Delimited-Scope IF Statement 9-90 INITIALIZE Statements 9-92 INITIALIZE Statement 9-93 INSPECT TALLYING With One Compare-String 9-100 INSPECT TALLYING With Multiple Compare-Strings 9-100 INSPECT Statement Converting Leading Spaces to Zeros 9-106 One INSPECT Statement, Several Replacements 9-107 INSPECT CONVERTING Statement 9-114 LOCKFILE Statement With TIME LIMIT Phrase 9-118 MERGE Statement 9-127 MOVE TO Statements 9-130 MULTIPLY BY Statement 9-135 MULTIPLY BY Statement With ROUNDED Phrase 9-135 MULTIPLY GIVING Statement 9-138 OPEN Statements 9-156 Unconditional PERFORM Statement With One Paragraph 9-161 Unconditional PERFORM Statement With Several Paragraphs 9-161 In-Line PERFORM Statement With Delimited-Scope Statements 9-162 PERFORM TIMES Statement 9-163 PERFORM TIMES Statement 9-163 PERFORM UNTIL Statement 9-166 PERFORM VARYING Statement Used to Display a List 9-176 PERFORM VARYING Statement Used to Build a Table 9-177 Reading a Sequential File 9-190 Reading a Dynamic Indexed File 9-191 Reading $RECEIVE With Timed Input-Output 9-192 Reading a Random Indexed File 9-200 REWRITE Statement for Indexed File 9-207 SEARCH VARYING Statement 9-214 SEARCH ALL Statement 9-219 Typical Use of Input and Output Procedures 9-236 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxxviii Examples (continued) Contents Examples (continued) Example 9-65. Example 9-66. Example 9-67. Example 9-68. Example 9-69. Example 9-70. Example 9-71. Example 9-72. Example 9-73. Example 9-74. Example 9-75. Example 9-76. Example 10-1. Example 10-2. Example 10-3. Example 11-1. Example 11-2. Example 11-3. Example 11-4. Example 11-5. Example 11-6. Example 11-7. Example 11-8. Example 11-9. Example 11-10. Example 11-11. Example 11-12. Example 11-13. Example 12-1. Example 12-2. Example 12-3. Example 12-4. Example 12-5. Example 12-6. Example 13-1. Example 13-2. START Statement for Indexed File 9-248 START Statement With GENERIC Phrase for Sequential File 9-249 START Statement With POSITION Phrase 9-250 STRING Statement 9-261 UNLOCKFILE Statement 9-270 UNSTRING Statement 9-281 UNSTRING Statement 9-281 DEBUG-ITEM Special Register 9-285 USE DEBUGGING Statement 9-287 USE AFTER EXCEPTION Statement 9-291 ADVANCING Phrase 9-299 INVALID KEY Phrase 9-305 COPY Statement 10-6 COPY Statement With REPLACING Phrases 10-11 REPLACE Statement 10-18 Main Program and Another Program 11-3 TNS HP COBOL Program Calling FORTRAN Program 11-5 Compilation Unit 11-6 Calling Programs That Are in a Separate File 11-8 For Step 1 of Finding the Called Program 11-18 For Step 2 of Finding the Called Program 11-18 Binder Statistics 11-29 COBOL85 Compiler Statistics 11-30 NMCOBOL Compiler Statistics 11-32 NMCOBOL Compiler and Linker Statistics 11-32 IF Directive 11-85 Nested IF and IFNOT Directive Scopes 11-85 Omitting Uncompiled Lines from Compiler Listing 11-86 RUN Commands 12-3 #TEMP 12-8 ASSIGN Command With Special COBOL Names 12-8 PARAM Command 12-16 CLEAR Command 12-18 DEFINE Names 12-21 Building a DLL From a Single Source File in One Step (Guardian) 13-12 Building a DLL From a Single Source File in Two Steps (Guardian) 13-13 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xxxix Examples (continued) Contents Examples (continued) Example 13-3. Example 13-4. Example 13-5. Example 13-6. Example 13-7. Example 13-8. Example 13-9. Example 13-10. Example 13-11. Example 13-12. Example 13-13. Example 13-14. Example 13-15. Example 13-16. Example 14-1. Example 14-2. Example 14-3. Example 14-4. Example 14-5. Example 14-6. Example 14-7. Example 14-8. Example 14-9. Example 14-10. Example 14-11. Example 14-12. Example 14-13. Example 14-14. Example 14-15. Example 14-16. Example 14-17. Example 14-18. Example 14-19. Example 14-20. Example 14-21. Example 14-22. Building a DLL From a Single Source File in One Step (OSS) 13-13 Building a DLL From a Single Source File in Two Steps (OSS) 13-14 Building a DLL From a Single Source File in One Step (PC) 13-15 Building a DLL From a Single Source File in Two Steps (PC) 13-15 Building a DLL From Multiple Source Files (Guardian) 13-16 Building a DLL From Multiple Source Files (OSS) 13-17 Building a DLL From Multiple Source Files (PC) 13-18 Specifying a DLL When the Compiler Calls the Linker (Guardian) 13-19 Specifying a DLL When You Compile and Then Link (Guardian) 13-20 Specifying a DLL When the Compiler Calls the Linker (OSS) 13-20 Specifying a DLL When You Compile and Then Link (OSS) 13-21 Specifying a DLL When the Compiler Calls the Linker (PC) 13-21 Specifying a DLL When You Compile and Then Link (PC) 13-22 COBOLASSIGN Routine 13-88 ACOS Function 14-8 ANNUITY Function 14-10 ASIN Function 14-11 ATAN Function 14-12 CHAR Function Without ALPHABET Clause 14-13 CHAR Function With ALPHABET Clause 14-14 COS Function 14-15 CURRENT-DATE Function 14-16 DATE-OF-INTEGER Function 14-17 DAY-OF-INTEGER Function 14-18 FACTORIAL Function 14-19 INTEGER Function 14-20 INTEGER-OF-DATE Function 14-21 INTEGER-OF-DATE Function 14-22 INTEGER-OF-DAY Function 14-23 INTEGER-PART Function 14-24 LENGTH Function 14-25 LOG Function 14-26 LOG10 Function 14-27 LOWER-CASE Function 14-28 MAX Function 14-30 MEAN Function 14-32 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xl Examples (continued) Contents Examples (continued) Example 14-23. Example 14-24. Example 14-25. Example 14-26. Example 14-27. Example 14-28. Example 14-29. Example 14-30. Example 14-31. Example 14-32. Example 14-33. Example 14-34. Example 14-35. Example 14-36. Example 14-37. Example 14-38. Example 14-39. Example 14-40. Example 14-41. Example 14-42. Example 14-43. Example 14-44. Example 15-1. Example 15-2. Example 15-3. Example 16-1. Example 19-1. Example 19-2. Example 19-3. Example 22-1. Example 22-2. Example 22-3. Example 22-4. Example 22-5. Example 22-6. Example 22-7. Example 22-8. Example 22-9. MEDIAN Function 14-33 MIDRANGE Function 14-34 MIN Function 14-36 MOD Function 14-37 NUMVAL Function 14-39 NUMVAL-C Function 14-42 ORD Function 14-43 ORD-MAX Function 14-44 ORD-MIN Function 14-46 PRESENT-VALUE Function 14-48 RANDOM Function 14-49 RANGE Function 14-51 REM Function 14-52 REVERSE Function 14-53 SIN Function 14-54 SQRT Function 14-55 STANDARD-DEVIATION Function 14-57 SUM Function 14-59 TAN Function 14-60 UPPER-CASE Function 14-61 VARIANCE Function 14-63 WHEN-COMPILED Function 14-64 Use of the DEBUG-ITEM Special Register 15-3 CROSSREF Utility Program 15-9 Setting the Default COPY Library 15-10 Continuation of Nonnumeric Literal in ANSI Format 16-3 OSS Pathnames for OSS Files 19-9 OSS Pathnames for Guardian Files 19-10 “GUARDIAN #DYNAMIC” in a File-Control Entry 19-25 TEDIT Banner 22-9 COPY or SOURCE Library 22-23 Input to the DDL Compiler 22-26 COPY Library Produced by the DDL Compiler 22-27 FUP Command File Produced by the DDL Compiler 22-29 Replacing Substrings 22-32 Copying Into Debugging Lines 22-33 Including Text From a Source File 22-34 Replacing Text-Words in an HP COBOL Source Program 22-36 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xli Examples (continued) Contents Examples (continued) Example 22-10. Example 22-11. Example 22-12. Example 22-13. Example 22-14. Example 22-15. Example 22-16. Example 22-17. Example 22-18. Example 22-19. Example 22-20. Example 22-21. Example 22-22. Example 22-23. Example 22-24. Example 22-25. Example 22-26. Example 22-27. Example 22-28. Example 23-1. Example 23-2. Example 23-3. Example 23-4. Replacing Substrings in an HP COBOL Source Program 22-37 Replacing Text-Words From a COPY Library 22-38 Replacing Text-Words From a SOURCE Library 22-39 COBOL85 Compilation Banner 22-41 NMCOBOL Compilation Banner 22-42 Diagnostic Reported Against a Copied Line 22-45 ANSI Format COPY Expansion 22-46 Warning Message 22-50 Error Message 22-50 Failure Message 22-51 Symbol Table Listing (COBOL85 Compiler) 22-53 Symbol Table Listing (NMCOBOL Compiler) 22-54 Octal Code Listing 22-54 Symbolic Code Listing (COBOL85 Compiler) 22-55 Symbolic Code Listing (NMCOBOL Compiler) 22-57 Cross-Reference Listing 22-63 Load-Map (ALPHA) 22-64 COBOL85 Compilation and BINSERV Summary 22-65 NMCOBOL Compilation Summary 22-66 CALL Identifier Statement 23-6 HP COBOL and HP C Programs Sharing Data 23-17 Record Containing a Table 23-22 TAL/pTAL Structures for Passing Parameters to COBOL Program 23-25 Example 23-5. Using Reference Parameters to Pass Integers to C Routine 23-28 Example 23-6. Using External Declarations to Pass Integers to C Routine 23-28 Example 23-7. Passing a String to a C Routine 23-29 Example 23-8. Passing Parameters to a FORTRAN Routine 23-30 Example 23-9. Passing Parameters to a Pascal routine 23-32 Example 23-10. Passing Parameters to a TAL Routine 23-34 Example 24-1. Interactive BIND Session 24-15 Example 24-2. OBEY File Equivalent of Example 24-1 24-15 Example 25-1. DEFINE Names 25-3 Example 25-2. ASSIGN Command 25-4 Example 26-1. COBOL File Names 26-4 Example 27-1. One File on One Tape 27-4 Example 27-2. Several Files on One Tape 27-5 Example 27-3. Multitape File 27-7 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xlii Examples (continued) Contents Examples (continued) Example 27-4. Example 27-5. Example 27-6. Example 27-7. Example 27-8. Example 27-9. Example 27-10. Example 27-11. Example 27-12. Example 27-13. Example 28-1. Example 28-2. Example 28-3. Example 28-4. Example 28-5. Example 28-6. Example 28-7. Example 28-8. Example 28-9. Example 28-10. Example 28-11. Example 28-12. Example 28-13. Example 28-14. Example 29-1. Example 29-2. Example 29-3. Example 29-4. Example 29-5. Example 29-6. Example 30-1. Example 30-2. Example 30-3. Example 30-4. Labeled Tape File 27-10 Converting a COBOL95 Program to Use Labeled Tape Files 27-11 Copying an EBCDIC File to a New ASCII File 27-13 Copying an EBCDIC File to an Existing ASCII File 27-13 Copying an EBCDIC File to an Existing ASCII File 27-13 DEFINE for Unlabeled Tape File With Variable-Length Records 27-18 DEFINE for Unlabeled Tape File With Fixed-Length Records 27-18 DEFINE for Labeled Tape File With Variable-Length Records and Labels to Be Bypassed 27-23 DEFINE for Labeled Tape File With Variable-Length Records and Standard IBM Labels 27-23 DEFINE for Labeled Tape File With Fixed-Length Records and Standard ASCII Labels 27-24 File Accessible Only to Owner and Only Locally 28-5 File Accessible Only to Owner 28-5 File Readable and Executable to Owner’s User Group 28-5 File Readable to Any User 28-5 Setting Default File Security to “UUUU” 28-5 Setting Default File Security to “CUCU” 28-5 Relative File Without Alternate Keys 28-17 Indexed File Without Alternate Keys 28-18 Creating a Queue File With a Timestamp and a User Key 28-19 Key of Reference 28-21 Generic Positioning 28-25 Use of START With the POSITION Phrase 28-27 Purging a File From an HP COBOL Program 28-43 Dynamic File Assignment 28-47 ACCEPT and DISPLAY Statements With a Terminal 29-3 Using a Terminal as a File 29-5 READ Statement With PROMPT Phrase 29-6 Transferring Break Ownership 29-10 Using DISPLAY Statements to Write to a Console 29-11 Reading and Writing Numeric Data 29-13 Level-1 Spooling 30-8 Level-2 Spooling 30-10 PERUSE Output 30-12 END-OF-PAGE Phrase 30-21 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xliii Examples (continued) Contents Examples (continued) Example 31-1. Example 31-2. Example 31-3. Example 31-4. Example 31-5. Example 31-6. Example 31-7. Example 31-8. Example 31-9. Example 31-10. Example 31-11. Example 31-12. Example 31-13. Example 31-14. Example 31-15. Example 31-16. Example 31-17. Example 32-1. Example 33-1. Example 47-1. Example 47-2. Example 47-3. Example 47-4. Example 48-1. Example 48-2. Example 48-3. Example 48-4. CREATEPROCESS Routine 31-4 Requester Code 31-8 Server Code 31-8 Requester Code 31-10 Server Code 31-11 Report Produced by PPD Command 31-12 PITCHER Code 31-14 CATCHER Code 31-15 Simple Server 31-18 PROCESSHANDLE_GETMINE_ and PROCESSHANDLE_DECOMPOSE_ Procedures 31-23 Determining a Process’s Node (System Number) 31-23 MESSAGE-SOURCE Clause 31-25 PROCESS_GETINFO_ Routine 31-28 Reporting Processes With Program’s Accessor ID 31-31 Identifying a Process’s Creator 31-34 Monitoring Completion of Descendant Processes 31-36 Suspending a Process 31-39 Key Parts of Fault-Tolerant HP COBOL Program 32-12 Misalignment 33-11 Message Indicator Line (COBOL85 Compiler) 47-2 Message Indicator Line (NMCOBOL Compiler) 47-2 NMCGEN Run-Time Error Message 47-95 SCI Run-Time Error Message 47-95 Standard Run-Time Diagnostic Message (Non-CRE Environment) 48-3 Input-Output Error Message (Non-CRE Environment) 48-6 Input-Output Error Message (CRE) 48-6 Using noft to Find the MCB Pointer in a Native Object File 48-21 Figures Figure 2-1. Figure 2-2. Figure 3-1. Figure 3-2. Figure 3-3. Figure 6-1. Figure 7-1. Tandem Reference Format 2-3 Directly Contained Programs and Indirectly Contained Programs Language Element Relationships 3-1 COBOL Character Set 3-2 COBOL Words in a Source Program 3-7 Reply Table 6-71 LINAGE Clause Layout 7-26 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xliv 2-10 Figures (continued) Contents Figures (continued) Figure 7-2. Figure 7-3. Figure 8-1. Figure 8-2. Figure 9-1. Figure 9-2. Figure 9-3. Figure 9-4. Figure 9-5. Figure 9-6. Figure 9-7. Figure 9-8. Figure 9-9. Figure 9-10. Figure 9-11. Figure 11-1. Figure 11-2. Figure 11-3. Figure 11-4. Figure 11-5. Figure 13-1. Figure 13-2. Figure 13-3. Figure 15-1. Figure 15-2. Figure 15-3. Figure 16-1. Figure 21-1. Figure 22-1. Figure 22-2. Figure 22-3. Figure 22-4. Precedence Rules for PICTURE Symbols 7-59 Example of COMPUTATIONAL-3/PACKED-DECIMAL Storage 7-72 Relationship of Statements, Sentences, Paragraphs, and Sections 8-1 Statement Examples 8-4 ACCEPT Statement Collecting Alphanumeric Data 9-5 ACCEPT Statement Collecting Numeric Data 9-6 Comparison Phase of EVALUATE Statement 9-74 Execution Phase of the EVALUATE Statement 9-75 How the Delimited-Scope IF Statement Works 9-85 How the Conditional IF Statement Works 9-88 Execution of a PERFORM VARYING Statement With a TEST BEFORE Phrase and Without an AFTER Phrase List 9-170 Execution of a PERFORM VARYING Statement With a TEST BEFORE Phrase and One AFTER Phrase 9-171 Execution of a PERFORM VARYING Statement With a TEST AFTER Phrase and Without an AFTER Phrase List 9-173 Execution of a PERFORM VARYING Statement With a TEST AFTER Phrase and One AFTER Phrase 9-174 Execution of a SEARCH VARYING Statement With WHEN Phrases 9-213 Compiler Input and Output 11-2 TNS Compilation Unit, Listing File, and Object File 11-7 TNS Compilation With Object-File Inclusion 11-8 COBOL85 Compilation of Single Program Unit 11-10 NMCOBOL Compilation of Single Program Unit (Non-PIC) 11-11 TNS Libraries and Their Utility Routines 13-1 Native SRLs and Their Utility Routines 13-2 Effect of Saved Message Utility (SMU) Routines 13-32 Definition of the DEBUG-ITEM Special Register 15-2 Debugger Selection for a TNS or Non-PIC Native Process 15-6 Debugger Selection for a PIC Native Process 15-7 ANSI Reference Format 16-1 How Lists of Reserved Words Are Related 21-1 Tandem Reference Format 22-6 ANSI Reference Format 22-6 DDL Input and Output 22-25 Source Program Listing Formats 22-42 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xlv Figures (continued) Contents Figures (continued) Figure 23-1. Figure 24-1. Figure 24-2. Figure 24-3. Figure 24-4. Figure 26-1. Figure 27-1. Figure 27-2. Figure 30-1. Figure 31-1. Figure 31-2. Figure 31-3. Figure 31-4. Figure 32-1. Figure 32-2. Figure 32-3. Figure 32-4. Figure 37-1. Figure 37-2. Figure 38-1. Figure 38-2. Directly Contained Programs and Indirectly Contained Programs Code and Data Blocks 24-2 Internal and External References 24-3 How External References Are Resolved 24-7 Run Unit Containing HP COBOL Code Blocks 24-18 MESSAGE SOURCE Format 26-11 Software Involved in Labeled-Tape Processing 27-9 DEFINE Names and COBOL File Names 27-19 LINAGE Clause Layout 30-20 Process Creation, Execution, and Termination 31-2 $RECEIVE as Separate Input and Output Files 31-7 $RECEIVE as Input/Output File 31-10 $RECEIVE From PITCHER to CATCHER 31-13 Process Pair 32-4 Activity of a Process Pair 32-5 Duplication in Takeover 32-8 PROGRAM-STATUS Data Item 32-10 Tandem Reference Format 37-2 ANSI Reference Format 37-3 COBOL Character Set 38-1 Precedence Rules for PICTURE Symbols 38-7 Tables Table i. Table 1-1. Table 1-2. Table 1-3. Table 2-1. Table 2-2. Table 2-3. Table 3-1. Table 3-2. Table 3-3. Table 3-4. Table 3-5. Table 3-6. Table 4-1. Table 4-2. HP Manuals to Which This Manual Refers lix Required HP COBOL Modules and Their Levels 1-2 Optional HP COBOL Modules and Their Levels 1-2 HP COBOL TNS and TSN/R Compilers 1-4 Source Program Components 2-2 Valid Indicator Area Characters (Tandem Reference Format) Scope of User-Defined Names 2-11 Alphanumeric Characters (for COBOL Words) 3-2 Punctuation Characters 3-3 Special Characters 3-3 Reserved Word Categories 3-9 Figurative Constants 3-23 PICTURE Character-String Editing Characters 3-24 Data Levels, Classes, and Categories 4-1 File Organization 4-7 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xlvi 2-4 23-4 Tables (continued) Contents Tables (continued) Table 4-3. Table 4-4. Table 4-5. Table 4-6. Table 6-1. Table 6-2. Table 6-3. Table 6-4. Table 6-5. Table 6-6. Table 6-7. Table 6-8. Table 6-9. Table 6-10. Table 7-1. Table 7-2. Table 7-3. Table 7-4. Table 7-5. Table 7-6. Table 7-7. Table 8-1. Table 8-2. Table 8-3. Table 8-4. Table 8-5. Table 8-6. Table 8-7. Table 8-8. Table 8-9. Table 8-10. Relationship Between File Organization and Access Mode 4-8 File Open Modes 4-10 Exclusion Modes 4-10 Allocation for COMPUTATIONAL Data Items 4-14 How Alphabetic Class Tests Work With Default Character Set 6-8 Additional Characters Accepted by Alphabetic Class Tests With Nondefault Character Sets 6-9 Summary of File-Control Entry Clauses 6-24 Descriptions of File-Control Entry Clauses 6-25 Sequential Access 6-26 Random Access 6-26 Receive-Control Table Example 6-70 Message Types That the Program Generates (System) 6-74 Message Types That the Hardware Generates (Asynchronous) 6-74 REPORT Clause Message Types in the CRE 6-75 Data Categories 7-2 PICTURE Character-String Symbols 7-55 Types of Editing Performed 7-63 Sign Control Symbols 7-65 COMPUTATIONAL-3/PACKED-DECIMAL Digit Representation 7-71 COMPUTATIONAL-3/PACKED-DECIMAL Sign Digit Representation 7-71 Numeric Data Storage for the COMPUTATIONAL-3/PACKED-DECIMAL PICTURE Clause 7-71 Where Statements End 8-4 Statement Types 8-4 Imperative Verbs 8-5 Explicit Scope Terminators 8-7 Status Key 1 Values 8-29 Status Key 2 Values: Successful Completion 8-30 Status Key 2 Values: Unsuccessful Completion—At-End Condition 8-31 Status Key 2 Values: Unsuccessful Completion—Invalid-Key Condition 8-31 Status Key 2 Values: Unsuccessful Completion—Permanent Error Condition 8-31 Status Key 2 Values: Unsuccessful Completion—Logic Error Condition 8-32 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xlvii Tables (continued) Contents Tables (continued) Table 8-11. Table 8-12. Table 8-13. Table 8-14. Table 8-15. Table 8-16. Table 8-17. Table 8-18. Table 8-19. Table 8-20. Table 8-21. Table 9-1. Table 9-2. Table 9-3. Table 9-4. Table 9-5. Table 9-6. Table 9-7. Table 9-8. Table 9-9. Table 9-10. Table 9-11. Table 11-1. Table 11-2. Table 11-3. Table 11-4. Table 11-5. Table 11-6. Table 11-7. Table 11-8. Table 11-9. Table 11-10. Table 11-11. Table 11-12. Status Key 2 Values: Unsuccessful Completion—Conditions Defined by HP 8-33 I-O Status Codes Augmented by GUARDIAN-ERR 8-35 Arithmetic Operators 8-46 Hierarchy of Operators 8-47 Precedence in Arithmetic Expressions 8-47 Operator-Operand Combinations 8-48 Logical Operators 8-64 Conditions, Logical Operators, and Parentheses 8-65 Abbreviated Combined Relation Conditions 8-67 Maximum Length of Result of Concatenation Expression 8-70 Class of Result of Concatenation Expression 8-70 CLOSE Statements for Sequential Tape File 9-39 EXIT Statement Restrictions and Effects 9-76 Summary of Legal Moves 9-129 I-O Status Codes for Unsuccessful Open Operations 9-145 I-O Statements You Can Use in Different Open Modes 9-148 Open Modes for Files Assigned to Processes 9-149 Open Modes for Files Assigned to Terminals 9-150 Open Modes for Structured Disk Files Not Present at Run Time 9-152 Open Modes for Structured Disk Files Present at Run Time 9-153 Valid SET TO Combinations 9-223 Using the POSITION and KEY Phrases 9-248 Statements for Calling Programs 11-4 Resolution of External References (COBOL85 Compiler With No Search List Defined) 11-19 Resolution of External References (COBOL85 Compiler With Search List Defined) 11-20 Resolution of External References (NMCOBOL Compiler) 11-21 How Final Values of #RECEIVE Arguments Are Chosen 11-24 Meaning of Binder Statistics 11-29 Meaning of COBOL85 Statistics Messages 11-31 Meaning of COBOL85 Statistics 11-31 Completion Codes 11-33 PARAM Commands Accepted by Compiler 11-34 How the PARAM SYMBOL-BLOCKS Command Affects Space Allocation 11-36 Source Text Manipulation Directives 11-47 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xlviii Tables (continued) Contents Tables (continued) Table 11-13. Table 11-14. Table 11-15. Table 11-17. Table 11-16. Table 11-18. Table 11-19. Table 11-20. Table 11-21. Table 12-1. Table 12-2. Table 13-1. Table 13-2. Table 13-3. Table 13-4. Table 13-5. Table 13-6. Table 13-7. Table 13-8. Table 13-9. Table 13-10. Table 13-11. Table 13-12. Table 13-13. Table 13-14. Table 13-15. Table 13-16. Table 13-17. Table 13-18. Table 13-19. Table 14-1. Table 14-2. Table 14-3. Table 14-4. Table 14-5. Input Format Control Directives 11-47 Listing Control Directives 11-48 Code-Generation Control Directives 11-49 Miscellaneous Control Directives 11-51 Resolution and Binding Control Directives 11-51 ENDUNIT Directive 11-52 CHECK Levels 11-57 Effects of ENV Directive Options 11-73 ENV Directive and TNS Program Compatibility 11-74 Differences Between DEFINE and ASSIGN 12-19 DEFINE Attributes 12-21 All TNS and TNS/R Utility Routines 13-3 Memory Area Characteristics 13-6 Linker Options That Export Program Names 13-11 Files of Dummy Routines 13-23 CBL85UTL Routines 13-24 FastSort Interface Routines 13-25 Where Versions of COBOLLIB Routines Are 13-27 COBOLLIB Routines 13-27 ZCOBSRL Routines 13-29 CLULIB Routines 13-30 Saved Message Utility (SMU) Routines 13-32 Message Operated Upon by Saved Message Utility (SMU) Routines 13-33 Portions of the ASSIGN Message 13-36 Portions of the Startup Message 13-36 Portions of the PARAM Message 13-36 CBL85UTL and ZCOBSRL Routines 13-38 Relationship Between param-id, subsort-number, and paramtext 13-53 Non-SMU COBOLLIB Routines 13-85 Guardian Environment Level 3 Spooling Routines 13-139 Alphanumeric Intrinsic Functions 14-3 Numeric Intrinsic Functions 14-4 Integer Intrinsic Functions 14-5 Variable-Type Intrinsic Functions 14-6 How Argument Type Determines Variable-Type Intrinsic Function Type 14-6 HP COBOL Manual for TNS and TNS/R Programs —522555-006 xlix Tables (continued) Contents Tables (continued) Table 14-6. Table 16-1. Table 18-1. Table 18-2. Table 19-1. Table 19-2. Table 22-1. Table 22-2. Table 22-3. Table 23-1. Table 23-2. Table 23-3. Table 25-1. Table 26-1. Table 27-1. Table 27-2. Table 27-3. Table 27-4. Table 27-5. Table 27-6. Table 27-7. Table 27-8. Table 28-1. Table 28-2. Table 28-3. Table 28-4. Table 28-5. Table 30-1. Table 30-2. Table 30-3. Table 32-1. Argument Types 14-7 Valid Indicator Area Characters (ANSI Reference Format) 16-2 Run-Time Environments 18-2 Old and New Utility Routine Names 18-7 Environment Variables 19-7 Analogous PARAM Commands and OSS Environment Variables 19-23 Compiler Listing Parts and the Directives That Control Them 22-40 Diagnostic Messages in the Compiler Listing 22-49 Compiler Directives That Produce Optional Warnings 22-50 Effect of Mode and Environment on Calling Non-COBOL Programs 23-1 Run-Time Environments for TNS Languages 23-2 HP COBOL and TAL or pTAL Parameter Correspondence 23-11 Conditions Requiring Pre-Execution Preparation 25-1 Special Names for System Files 26-5 Mount Messages 27-6 Effect of LABELS Attribute and LABEL RECORDS Clause on Unlabeled Tape File 27-17 Correspondence Between RECORD CONTAINS Clause and RECFORM Attribute Value 27-17 Effect of LABELS Attribute and LABEL RECORDS Clause on Labeled Tape File 27-20 Correspondence Between RECORD CONTAINS Clause and RECFORM Attribute Value 27-21 Corresponding Open Modes and USE Attribute Values 27-22 Effect of LABELS Attribute on Mount Messages 27-24 Run-Time Errors Specific to Tape File Use 27-26 Security Attributes for Disk Files1 28-4 Exclusion Modes and Their Meanings 28-7 Corresponding HP and HP COBOL Disk File Terms 28-10 Comparison of Structured File Characteristics 28-11 Enscribe File Positioning Modes 28-24 Guardian Environment Routines for Level 3 Spooling 30-11 PERUSE Operations and Commands (Partial List) 30-13 SPOOLCOM Operations and Commands (Partial List) 30-15 Values for PROGRAM-STATUS When STARTBACKUP Has Option 0, 1, or 2 32-10 HP COBOL Manual for TNS and TNS/R Programs —522555-006 l Tables (continued) Contents Tables (continued) Table 32-2. Table 33-1. Table 34-1. Table 35-1. Table 37-1. Table 37-2. Table 38-1. Table 38-2. Table 38-3. Table 38-4. Table 38-5. Table 38-6. Table 38-7. Table 38-8. Table 38-9. Table 38-10. Table 38-11. Table 45-1. Table 46-1. Table 46-2. Table 47-1. Table 47-2. Table 48-1. Table A-1. Table A-2. Table B-1. Table B-2. Table B-3. Table B-4. Table B-5. Table B-6. Table B-7. Values for PROGRAM-STATUS When STARTBACKUP Has Option 3 32-11 TNS Misalignment Handling Methods 33-9 COBOL Cross Compiler Platforms 34-1 Environment Variables 35-10 Valid Indicator Field Characters (Tandem Reference Format) 37-2 Valid Indicator Area Characters (ANSI Reference Format) 37-3 Alphanumeric Characters (for COBOL Words) 38-2 Punctuation Characters 38-2 Special Characters 38-2 Figurative Constants 38-5 PICTURE Character-String Editing Characters 38-6 Arithmetic Operators 38-8 Hierarchy of Operators 38-8 Precedence in Arithmetic Expressions 38-9 Operator-Operand Combinations 38-9 Maximum Length of Result of Concatenation Expression 38-13 Class of Result of Concatenation Expression 38-13 CBL85UTL and ZCOBSRL Routines 45-1 Saved Message Utility (SMU) Routines 46-1 Non-SMU COBOLLIB Routines 46-10 Warning, Error, and Failure Characteristics 47-1 Problem Discovery Time, Message Indicator Line Contents, and Problem Location 47-2 COBOL Message Mapping 48-11 ASCII Character Set in Numeric Order A-1 ASCII Character Set in Alphabetic Order A-6 Integer Types, Part 1 B-1 Integer Types, Part 2 B-3 Floating, Fixed, and Complex Types B-4 Character Types B-5 Structured, Logical, Set, and File Types B-6 Pointer Types B-7 Address Types1 B-8 HP COBOL Manual for TNS and TNS/R Programs —522555-006 li Contents HP COBOL Manual for TNS and TNS/R Programs —522555-006 lii What’s New in This Manual Manual Information HP COBOL Manual for TNS and TNS/R Programs Abstract This publication describes the HP implementation of the 1985 version of the COBOL language. It includes information on the COBOL85 and NMCOBOL compilers (T9257 and T8107, respectively) and program execution, task-oriented information to help an experienced COBOL programmer use HP COBOL for NonStop™ systems, and summaries of compiler and run-time error messages. Product Version COBOL85 D32, D42, D44, D46 NMCOBOL D44, D46 Tandem Development Suite (TDS) PC COBOL D45, G06 HP Enterprise Toolkit—NonStop Edition (ETK) PC COBOL G06, H01 Supported Release Updates (RVUs) This publication supports D46.00, G06.00, H06.03 and all subsequent D-series, G-series, and H-series RVUs until otherwise indicated by its replacement publication. Part Number Published 522555-006 July 2005 HP COBOL Manual for TNS and TNS/R Programs —522555-006 liii New and Changed Information What’s New in This Manual Document History Part Number Product Version Published 522555-001 COBOL85 D32, D42, D44, D46; NMCOBOL D44.01, D46; PC COBOL D45, G06.06 February 2002 522555-002 COBOL85 D32, D42, D44, D46; NMCOBOL D44.01, D46; TDS PC COBOL D45, G06.06; ETK PC COBOL G06.06, G06.15, G06.18, G06.20 May 2003 522555-003 COBOL85 D32, D42, D44, D46; NMCOBOL D44.01, D46; TDS PC COBOL D45, G06.06; ETK PC COBOL G06.06, G06.15, G06.18, G06.20 April 2004 522555-006 COBOL85 D32, D42, D44, D46; NMCOBOL D44.01, D46; TDS PC COBOL D45, G06.06, H06.03; ETK PC COBOL G06.06, G06.15, G06.18, G06.20, H06.03 July 2005 New and Changed Information • • • New Changed Deleted New • • • • • • • NMCOBOL Compiler and Linker Statistics Example 22-21, Symbol Table Listing (NMCOBOL Compiler) Example 22-21, Symbol Table Listing (NMCOBOL Compiler) Native Addressing Modes CRE example in Guardian Abnormal Termination Messages Example 48-3, Input-Output Error Message (CRE) Glossary has some new entries Changed Throughout the manual (not marked by change bars): • • • The changes in COBOL Name Conventions apply “COBOL85 run-time routines” was changed to “HP COBOL or CRE run-time routines” (for the first occurrence) and “run-time routines” (everywhere else) “SQL” was changed to either “SQL/MP” or “SQL/MP and SQL/MX,” whichever was accurate HP COBOL Manual for TNS and TNS/R Programs —522555-006 liv What’s New in This Manual • • • Changed “executable object file” was changed to “loadfile” “nonexecutable object file” was changed to “linkfile” Miscellaneous format changes Change bars identify important changes to content in the following topics. (Minor changes are marked by change bars but not listed here.) • • • • • • • • • • • • • • • • • • • • • • • • • HP COBOL Language HP COBOL Compilers for TNS and TNS/R Programs (formerly “COBOL85 and NMCOBOL Compilers”) Guardian and OSS Environments Combining Separately Compiled Source Programs Data Alignment in Receiving Items Data Alignment in Memory Using Indexes Instead of Subscripts Using Indexes Instead of Subscripts Storage Allocation For an Initial Program MESSAGE SOURCE Phrase Size Limits (Working-Storage Section) Size Limits (Extended-Storage Section) Table 8-3, Imperative Verbs CALL ENTER OPEN: Nonexistent Files Figure 9-11, Execution of a SEARCH VARYING Statement With WHEN Phrases How an HP COBOL Program Calls a Non-COBOL Program How the Compiler Resolves Unqualified References now applies to both compilers Table 11-10, PARAM Commands Accepted by Compiler PARAM SYMBOL-BLOCKS Where Compiler Directives Are Allowed BLANK and NOBLANK INSPECT and NOINSPECT SAVEABEND and NOSAVEABEND HP COBOL Manual for TNS and TNS/R Programs —522555-006 lv What’s New in This Manual • • • • • • SHARED SQL and NOSQL RUN or RUND Command PARAM Command COBOL85^ARMTRAP The description of library-reference in: ° ° ° COBOL85^COMPLETION and COBOL_COMPLETION_ ° ° COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ ° COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ ° COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_: COBOL_CONTROL_ COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ ° ° ° • • • • • • • • • • Changed ° ° Printers or Spoolers System Log Files Partitioned Disk Files COBOLFILEINFO COBOL_FILE_INFO_ Section 15, Debugging Tools Arithmetic Overflow Processing Compiler Space Allocation Example 22-20, Symbol Table Listing (COBOL85 Compiler) Fixup Form Name Introduction to TMF Migrating HP COBOL Programs Removal Required Section 41, Environment Division and Section 42, Data Division have exchanged places HP COBOL Manual for TNS and TNS/R Programs —522555-006 lvi What’s New in This Manual • • • • Deleted Other Products’ Error Messages moved from Section 48, Run-Time Diagnostic Messages, to Section 47, Compiler Diagnostic Messages Arithmetic Overflow Stack Overflow Glossary has some changed entries Deleted • From Section 19, Using HP COBOL in the OSS Environment and Section 35, Commands: ° ° cobol Utility Flags nmcobol Utility Flags These flags are described in the Open System Services Shell and Utilities Reference Manual. • • • From Features Unavailable in the OSS Environment: Utility Routines From Section 21, Reserved Words: New COBOL85 Reserved Words (additions to COBOL 74) Former Section 35, Converting COBOL 74 Programs to COBOL85 HP COBOL Manual for TNS and TNS/R Programs —522555-006 lvii What’s New in This Manual HP COBOL Manual for TNS and TNS/R Programs —522555-006 lviii Deleted About This Manual This manual is a complete reference book for experienced COBOL programmers who want to use HP COBOL for NonStop systems (HP COBOL). It explains every feature of the HP COBOL programming language. To understand its explanations, you must have some experience with structured (1974 or 1985) COBOL. If you do not, read an introductory text first. Topics: • • • Manuals to Which This Manual Refers Acknowledgment Notation Conventions Manuals to Which This Manual Refers Table i. HP Manuals to Which This Manual Refers (page 1 of 6) Manual Description Accelerator Manual Explains how to improve performance of TNS HP COBOL programs running on TNS/R systems (migrating them to TNS/R native mode is preferable) Accelerator Manual Data Alignment Addendum Documents the data alignment requirements of the Accelerator. Binder Manual Explains how to use the stand-alone Binder product to bind compilation units (or modules) that were compiled with the COBOL85 compiler C/C++ Programmer’s Guide Contains information you need about HP C for NonStop systems if you plan to call HP C routines from HP COBOL COBOL Manual for TNS/E Programs Describes and explains how to use the ECOBOL compiler CRE Programmer’s Guide Explains how to use the Common RunTime Environment (CRE) for running mixed-language programs written for the D-series operating system CROSSREF Manual Explains how to use the stand-alone CROSSREF product to collect crossreference information for programs compiled with the COBOL85 compiler HP COBOL Manual for TNS and TNS/R Programs —522555-006 lix Manuals to Which This Manual Refers About This Manual Table i. HP Manuals to Which This Manual Refers (page 2 of 6) Manual Description Data Definition Language (DDL) Reference Manual Describes the Data Definition Language (DDL), with which you can create COPY and SOURCE libraries for your HP COBOL program Debug Manual Explains how to debug programs using the Debug machine-level debugger DLL Programmer’s Guide for TNS/R Systems Explains position-independent code (PIC) and dynamic-link libraries (DLLs). EDIT User’s Guide and Reference Manual Explains how to create and modify source files EMS Manual Describes the Event Management Service (EMS). The misalignment tracing facility generates EMS events (see Misalignment Tracing Facility). ENABLE User’s Guide Explains how to use the ENABLE utility to build a file-maintenance application that allows you to modify a disk file ENFORM User’s Guide Explains how to use the ENFORM language to query an online database Enscribe Programmer’s Guide Explains how to use queue files. Expand Network Management and Troubleshooting Guide Describes the Expand network, which you must understand if your system is connected to other systems by this means and you want to create partitioned disk files FastSort Manual Describes the FastSort interface routines that give your HP COBOL program access to the utility program FastSort File Utility Program (FUP) Reference Manual Describes the Guardian File Utility Program (FUP), which you can use on files that you use with the COBOL85 or NMCOBOL compiler FORTRAN Reference Manual Contains information you need about HP FORTRAN for NonStop systems if you plan to call HP FORTRAN routines HP COBOL programs Guardian Application Conversion Guide Explains how to convert C-series procedures to use the extended features of the D-series operating system HP COBOL Manual for TNS and TNS/R Programs —522555-006 lx Manuals to Which This Manual Refers About This Manual Table i. HP Manuals to Which This Manual Refers (page 3 of 6) Manual Description Guardian Native C Library Calls Reference Manual Contains information you need about HP C for NonStop systems if you plan to call HP C routines from HP COBOL programs Guardian Procedure Calls Reference Manual Describes Guardian file name syntax and the syntax and programming considerations for using system procedures Guardian Procedure Errors and Messages Manual Describes error codes, error lists, system messages, and trap numbers for system procedures Guardian Programmer’s Guide Explains how to use the programmatic interface of the operating system Guardian User’s Guide Explains how to run loadfiles (the RUN command) and how to create and modify indexed (key-sequenced) files Inspect Manual Explains how to debug programs using theInspect source-level and machinelevel interactive debugger Kernel-Managed Swap Facility (KMSF) Manual Explains how to use the Kernel-Managed Swap Facility (KMSF) to configure and manage swap volumes ld Manual Explains how to use the ld utility to link and change the attributes of TNS/R PIC object files NetBatch Manual Explains how to use the NetBatch job management system, which is useful for launching compilations to run unattended nld Manual Explains how to use the nld utility to link and change the attributes of TNS/R nonPIC object files and how the ar utility works noft Manual Explains how to use the noft utility to display TNS/R object files (PIC and nonPIC) Open System Services Programmer’s Guide Describes how to write applications in HP C for the HP NonStop Open System Services (OSS) environment, focusing on how OSS differs from a standard UNIX programming environment (intended for application and system programmers) HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxi Manuals to Which This Manual Refers About This Manual Table i. HP Manuals to Which This Manual Refers (page 4 of 6) Manual Description Open System Services Shell and Utilities Reference Manual Describes the syntax and semantics of each command that you can enter interactively to access the OSS command interpreter (the OSS shell), and utilities and other functions that perform general-purpose and programdevelopment operations (intended for all audiences) Open System Services System Calls Reference Manual Describes all OSS system calls (file system and kernel functions), their syntax, required external data structures, resulting operations, and source file (header) locations for all literals and symbolic definitions (intended for system and application programmers) Pathway/TS SCREEN COBOL Reference Manual Describes the SCREEN COBOL language (HP COBOL is often used to implement servers that works with SCREEN COBOL (TCP) requesters to make up a Pathway/TS application) Pathway/TS TCP and Terminal Programming Guide Explains how to write SCREEN COBOL requesters in the Pathway environment PS TEXT EDIT and PS TEXT FORMAT User’s Guide Explains how to create and modify source files PS TEXT EDIT Reference Manual Describes the PS TEXT EDIT editor, which you can use to create and modify source files pTAL Conversion Guide Explains how to convert TAL programs to pTAL, which you must do to any TAL programs that your TNS/R HP COBOL programs call pTAL Reference Manual Describes the pTAL language, one of the TNS/R languages in which you can rewrite FORTRAN or Pascal programs that you want your TNS/R HP COBOL programs to call SCF Reference Manual for the Kernel Subsystem Describes the Subsystem Control Facility (SCF), whose user interface you can use to control tracing (see Misalignment Tracing Facility). Spooler Programmer’s Guide Explains how to use the spooler utility that collects and routes printer output HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxii Manuals to Which This Manual Refers About This Manual Table i. HP Manuals to Which This Manual Refers (page 5 of 6) Manual Description Spooler Utilities Reference Manual Explains spoolers, which can be given Guardian file names and used with HP COBOL programs SQL/MP Programming Manual for COBOL Describes the programmatic interface to HP NonStop SQL/MP for COBOL. You need it if your HP COBOL program contains embedded SQL/MP statements. SQL/MP Reference Manual Describes HP NonStop SQL/MP. You might need it if your HP COBOL program contains embedded SQL/MP statements. SQL/MX Programming Manual for C and COBOL Describes the programmatic interface to HP NonStop SQL/MX for HP C and HP COBOL. You need it if your HP COBOL program contains embedded SQL/MX statements. TACL Reference Manual Describes the HP Tandem Advanced Command Language (TACL), which you need to execute HP COBOL programs from a TACL prompt TAL Programmer’s Guide Contains information you need about the HP Transaction Application Language (TAL) if you plan to call TAL routines from TNS HP COBOL programs TAL Programmer’s Guide Data Alignment Addendum Describes the data alignment requirements of TAL TAL Reference Manual Contains information you need about TAL if you plan to call TAL routines from TNS HP COBOL programs TNS/R Native Application Migration Guide Contains information you need about migrating called TAL and TNS HP C programs to pTAL and TNS/R HP C, respectively TNS/E Native Application Conversion Guide Introduces the TNS/E native development and execution environments and explains how to convert exising TNS programs to TNS/E native applications. HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxiii Acknowledgment About This Manual Table i. HP Manuals to Which This Manual Refers (page 6 of 6) Manual Description TS/MP Pathsend and Server Programming Manual Explains how to write servers and Pathsend requesters in the Pathway environment TS/MP System Management Manual Explains the configuration and operation of servers in the Pathway environment (HP COBOL is often used to implement servers that function as parts of a Pathway applications, using the HP NonStop TS/MP software) Acknowledgment 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 herewith. The authors and copyright holders of the copyrighted material used herein 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. F 28-8013, copyrighted 1959 by IBM; FACT, DSI 27A5260-2760, copyrighted 1960 by MinneapolisHoneywell 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. HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxiv Notation Conventions About This Manual Notation Conventions This manual uses these conventions throughout: • • • • • • • • “Compiler” means both the COBOL85 and NMCOBOL compilers unless otherwise stated “Linker” means the nld and ld utilities unless otherwise stated COBOL Name Conventions Hypertext Links Syntax Diagram Conventions Range Convention Example Conventions Change Bar Notation COBOL Name Conventions This manual uses these COBOL names, and this is what they mean: Name Meaning COBOL The implementation of the 1985 ISO/ANSI Standard COBOL language HP COBOL HP COBOL for NonStop systems, the HP implementation of COBOL with HP extensions COBOL85 The HP compiler for the HP COBOL language that produces TNS objects NMCOBOL The HP compiler for the HP COBOL language that produces TNS/R objects Hypertext Links Blue underline is used to indicate a hypertext link within text. By clicking a passage of text with a blue underline, you are taken to the location described. For example: This requirement is described under Backup DAM Volumes and Physical Disk Drives on page 3-2. HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxv Syntax Diagram Conventions About This Manual Syntax Diagram Conventions This manual presents syntax in railroad diagrams. Here is a generic railroad diagram: KEYWORD item1 item3 item2 , item4 «item5» VST406.vsd To use a railroad diagram, follow the direction of the arrows and specify syntactic items as indicated by the diagram pieces: Diagram Piece KEYWORD Meaning Type KEYWORD as shown. You can type letters in uppercase or lowercase. VST412.vsd item Replace item with a value that fits its description, which follows the syntax diagram. VST413.vsd , Type content (punctuation mark, symbol, or letter) as shown. You can type a letter in uppercase or lowercase. VST414.vsd «item» The 1985 COBOL standard classifies item as obsolete, so you are advised not to use it. (An obsolete keyword is marked the same way; that is, «KEYWORD».) HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxvi Syntax Diagram Conventions About This Manual Some examples of the meanings of simple diagrams are: Diagram Piece Meaning Choose item1 or item2. item1 item2 VST407.vsd Choose item1, item2, or neither. item1 item2 VST408.vsd Specify item one or more times, separating occurrences with commas. item , VST409.vsd Specify item at most n times. item n VST742.vsd Note. To refer to a particular railroad diagram or figure when giving feedback to HP, use the number at the bottom right corner of that railroad diagram or figure (for example, VST742.vsd). HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxvii Syntax Diagram Conventions About This Manual Spacing rules are: • If the arrow between two diagram pieces is labelled “ns,” put no spaces between the syntactic items that they represent. For example: ns volume $ VST420.vsd means that you type: $NEWVOL not $ NEWVOL • An “ns” on the top line of a choice structure applies to the lower lines in the choice structure as well. For example: ns " ns COBOL85^RETURN^SORT^ERRORS " COBOL_RETURN_SORT_ERRORS_ VST635.vsd means that you type one of: "COBOL85^RETURN^SORT^ERRORS" "COBOL_RETURN_SORT_ERRORS_" • If two diagram pieces are not separated by a separator character (such as a comma, semicolon, or parenthesis), separate the syntactic items that they represent by at least one space or a new line. For example: MULTIPLY integer1 integer2 VST410.vsd means that you type: MULTIPLY 3 4 not MULTIPLY34 HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxviii Range Convention About This Manual • If two diagram pieces are separated by a separator character, separating the syntactic items that they represent by spaces is optional. For example: MULTIPLY integer1 , integer2 VST411.vsd means that you type: MULTIPLY 3,4 or MULTIPLY 3, 4 • If a diagram piece is immediately followed by a period, putting spaces between the syntactic item and the period is optional. For example: END PROGRAM program-name . VST374.vsd means that you can type: END PROGRAM SORT. or END PROGRAM SORT . • Explicit spacing rules given for individual railroad diagrams override the aforementioned rules. Note. Except in literals and PICTURE clauses, HP COBOL treats the comma (,) and semicolon (;) as equivalents. Range Convention Ranges include their endpoints unless otherwise noted. For example, “x is in the range from 0 through 32,767” means that x is greater than or equal to 0 and less than or equal to 32,767. HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxix Example Conventions About This Manual Example Conventions In examples, a modified ellipsis (...) indicates an omission. The code in Example i can be abbreviated as shown in Example ii. Example i. Code Example Without Ellipsis (...) WORKING-STORAGE SECTION. 01 MONTH-NAME-TABLE. 05 FILLER PICTURE X(9) VALUE "January". 05 FILLER PICTURE X(9) VALUE "February". 05 FILLER PICTURE X(9) VALUE "March". 05 FILLER PICTURE X(9) VALUE "April". 05 FILLER PICTURE X(9) VALUE "May". 05 FILLER PICTURE X(9) VALUE "June". 05 FILLER PICTURE X(9) VALUE "July". 05 FILLER PICTURE X(9) VALUE "August". 05 FILLER PICTURE X(9) VALUE "September". 05 FILLER PICTURE X(9) VALUE "October". 05 FILLER PICTURE X(9) VALUE "November". 05 FILLER PICTURE X(9) VALUE "December". 01 MONTH-NAMES REDEFINES MONTH-NAME-TABLE. 05 MONTH-NAME OCCURS 12 TIMES PICTURE X(9). Example ii. Code Example With Ellipsis WORKING-STORAGE SECTION. 01 MONTH-NAME-TABLE. 05 FILLER PICTURE X(9) VALUE "January". 05 FILLER PICTURE X(9) VALUE "February". ... 05 FILLER PICTURE X(9) VALUE "December". 01 MONTH-NAMES REDEFINES MONTH-NAME-TABLE. 05 MONTH-NAME OCCURS 12 TIMES PICTURE X(9). In examples with user input, user input is shown in bold type and it is assumed that the user presses Return after typing the input. For instance, in the example: ENTER RUN CODE ?123 CODE RECEIVED: 123.00 the system displays ENTER RUN CODE on one line and prompts the user with a question mark (?)on the next line, the user types 123 and presses Return, and the system displays CODE RECEIVED: 123.00. Change Bar Notation A change bar (as shown to the right of this paragraph) indicates a substantive difference between this edition of the manual and the preceding edition. Change bars highlight new or revised information. HP COBOL Manual for TNS and TNS/R Programs —522555-006 lxx Part I. Features of HP COBOL Title Section 1, Introduction Section 2, Source Program Organization and Format Section 3, Language Elements Section 4, Data Fundamentals Section 5, Identification Division Section 6, Environment Division Section 7, Data Division Section 8, Procedure Division Section 9, Procedure Division Verbs Section 10, Source Text Manipulation Section 11, Program Compilation Section 12, Program Execution Section 13, Libraries and Utility Routines Section 14, Intrinsic Functions Section 15, Debugging Tools Section 16, ANSI Reference Format Section 17, HP Extensions to ISO COBOL Section 18, HP COBOL CRE Support Section 19, Using HP COBOL in the OSS Environment Section 20, HP COBOL Limits Section 21, Reserved Words HP COBOL Manual for TNS and TNS/R Programs —522555-006 Part I. Features of HP COBOL HP COBOL Manual for TNS and TNS/R Programs —522555-006 1 Introduction This manual describes the HP COBOL for NonStop systems (HP COBOL) language and explains how to use it to create TNS processes and TNS/R native processes. (The COBOL Manual for TNS/E Programs explains how to use the HP COBOL language to create TNS/E native processes.) Topics: • • • • • • • • HP COBOL Language Summary of Execution Modes HP COBOL Compilers for TNS and TNS/R Programs Guardian and OSS Environments Compiler Input Compiler Output Combining Separately Compiled Source Programs Executing Loadfiles HP COBOL Language The HP COBOL language, the implementation of the COBOL language by the HewlettPackard Company, conforms to the standard published by the International Organization for Standardization (ISO) and the American National Standards Institute (ANSI) in 1985. HP COBOL also provides extensions to the language that enable COBOL programs to act as servers, as in a Pathway application (which uses TS/MP), and to be fault tolerant. Standard COBOL is described in American National Standard for Information Systems Programming Language—COBOL, which has ANSI document number X3.23-1985 and ISO document number ISO 1989-1985, and the intrinsic function and correction amendments, ANSI X3.23a-1989 and ANSI X3.23b-1993, ISO 1989:1985/Amd.1:1992 and ISO 1989:1985/Amd.2:1994. HP offers high-level standard COBOL with HP extensions. HP COBOL Manual for TNS/E Programs —520347-003 1 -1 Embedded SQL/MP Introduction Table 1-1. Required HP COBOL Modules and Their Levels Module Level Nucleus 2 Sequential I-O 2 Relative I-O 2 Indexed I-O 2 Inter-Program Communication 2 Sort-Merge 1 Source Text Manipulation 2 Table 1-2. Optional HP COBOL Modules and Their Levels Module Level Segmentation* 2 (partial) Debug* 1 Intrinsic Function 1 Report Writer Null Communication Null * The 1985 COBOL standard classifies this module as obsolete, so you are advised not to use it. HP COBOL accepts the syntax for statements in all of these areas; however, certain statements do not apply to NonStop system environments. In such cases, HP COBOL treats these statements as comments after checking that the statements are syntactically correct. Embedded SQL/MP The HP COBOL embedded SQL/MP implementation conforms fully to the ANSI Database—Embedded NonStop SQL Standard (ANSI X3.168-1989), with the restrictions and extensions mentioned in SQL/MP Programming Manual for COBOL. SQL/MP is compatible with every HP COBOL compiler (see Table 1-3). Embedded SQL/MX The HP COBOL embedded SQL/MX implementation conforms to SQL:1999 standards as described in SQL/MX Reference Manual with the restrictions and extensions mentioned in SQL/MX Programming Manual for C and COBOL. SQL/MX is compatible with every HP COBOL compiler except COBOL85 (see Table 1-3). HP COBOL Manual for TNS/E Programs —520347-003 1 -2 Summary of Execution Modes Introduction Summary of Execution Modes TNS/Rsystems support three execution modes: TNS Mode Accelerated Mode TNS/R Native Mode Programs are generated by TNS compilers. Programs are generated by TNS compilers and then processed by the Accelerator. Programs are generated by TNS/R native compilers. Programs use TNS process and memory architecture. Programs use TNS process and memory architecture. Programs use TNS/R native process and memory architecture. Programs consist of TNS object code (TNS instructions). Programs consist of TNS object code (TNS instructions) and accelerated object code (equivalent Accelerator-generated RISC instructions). Programs consist of TNS/R native object code (RISC instructions). Millicode routines implement the TNS instructions on RISC processors. Programs execute RISC instructions directly on RISC processors and use TNS mode to execute instructions for which the Accelerator could not generate equivalent RISC instructions. Programs execute RISC instructions directly on RISC processors. Because of architectural differences between execution modes, you cannot mix TNS object code, accelerated object code, and native object code in one loadfile. A native program can contain only native object code. HP COBOL Manual for TNS/E Programs —520347-003 1 -3 HP COBOL Compilers for TNS and TNS/R Programs Introduction HP COBOL Compilers for TNS and TNS/R Programs For HP COBOL source programs, HP provides the compilers in Table 1-3. Table 1-3. HP COBOL TNS and TSN/R Compilers Compiler T Number Description COBOL85 T9257 Produces TNS object code, which is position-dependent code (non-PIC). Runs on TNS, TNS/R, and TNS/E systems. NMCOBOL* ** T8107 Produces native TNS/R object code, which is either non-PIC (the default) or positionindependent code (PIC). Runs on TNS/R systems. Native COBOL Cross Compiler for TNS/R Programs on PC** T0328 Enables you to build native TNS/R objects or NonStop systems applications on a PC. Runs on a PC. * The NMCOBOL compiler itself is a mixture of TNS and TNS/R programs. ** In this manual, “NMCOBOL compiler” means both of these compllers unless otherwise stated. Guardian and OSS Environments The NonStop operating system offers two operating environments, the Guardian environment and the OSS environment. These OSS utilities call these compilers on these systems: OSS Utility Compiler Systems cobol COBOL85 TNS and TNS/R (but not TNS/E) nmcobol NMCOBOL TNS/R The OSS environment provides industry-standard application program interfaces (APIs) and utilities to enable you to port existing applications quickly and easily to NonStop systems. The NonStop operating system continues to support Guardian services. Most features of the HP COBOL language and library are available in the OSS environment, and most of them operate as they do in the Guardian environment. For more information on OSS, see Section 19, Using HP COBOL in the OSS Environment. In both the OSS and the Windows environments, the flag -Wsystype={guardian|oss} determines whether the native COBOL cross compiler creates loadfiles for the Guardian environment or for the OSS environment. The default is the Guardian environment. For more information on the native COBOL cross compiler, see Section 34, Native COBOL Cross Compiler. HP COBOL Manual for TNS/E Programs —520347-003 1 -4 Compiler Input Introduction Compiler Input The only required input to the compiler is: • • A source file containing the program text In some cases, compiler directives The optional input is: • • • One or more source library files from which the compiler can copy additional source text specified in COPY statements or SOURCE directives One or more user-specified object files that contain object code explicitly called by the program being compiled For the COBOL85 compiler: ° ° • The COBOL85 run-time object library file, C8LIB These COBOL external declarations files, which are used in resolving references to routines in the system library: File Contents COBOLEX0 Operating system routines for the latest RVU of the operating system COBOLEX1 Operating system routines for the next-to-latest RVU of the operating system COBOLEXT Operating system routines for the second-next-to-latest RVU of the operating system COBOLLIB Utility routines CBL85UTL Utility routines CLULIB Utility routines For the NMCOBOL compiler, these COBOL external declarations files, which are used in resolving references to routines in the system library: File Contents NMCOBEX0 Operating system routines for the latest RVU of the operating system NMCOBEX1 Operating system routines for the next-to-latest RVU of the operating system NMCOBEXT Operating system routines for the second-next-to-latest RVU of the operating system ZCOBSRL Utility routines ZCRESRL Utility routines HP COBOL Manual for TNS/E Programs —520347-003 1 -5 Compiler Output Introduction Compiler Output The output of the compiler is: • • A listing, including any compiler diagnostic messages (if the file for the listing is a disk file, the compiler creates an EDIT file unless the file already exists) An object file, if no compilation errors occurred If compilation errors occurred: • • The COBOL85 compiler produces a partial object file if any program units in the compilation compile without errors. The NMCOBOL compiler produces no object file. The COBOL85 compiler produces an object file that can be both executed and input to the Bind utility. The NMCOBOL compiler produces either an executable object file, a nonexecutable object file, a user library, or a dynamic-link library (DLL). Other differences between the two compilers are explained throughout the manual. For an overview of these differences, see Section 33, Migrating TNS/R Programs to TNS/RE Programs. HP COBOL Manual for TNS/E Programs —520347-003 1 -6 Combining Separately Compiled Source Programs Introduction Combining Separately Compiled Source Programs You can compile several source files separately and then combine their object code files into a single loadfile . The method you use depends on mode and operating environment, as this table shows: Mode Operating Environment Object Code Method For more information, see ... TNS Guardian Non-PIC Binder objectfile builder Binder Manual OSS Non-PIC cobol utility Mixed-Language Programs Guardian or OSS Non-PIC nld utility nld Manual PIC ld utility ld Manual Native In the Guardian environment: Loadfile TNS TNS/R Can contain object code from these compilers: • • • • • • • • COBOL85 HP C TAL Pascal NMCOBOL Native HP C Native HP C++ pTAL You can combine multiple object files into a single loadfile only if the multiple object files are either all TNS object files or all TNS/R native object files. You cannot combine TNS object files and TNS/R object files into a single loadfile. HP COBOL Manual for TNS/E Programs —520347-003 1 -7 Executing Loadfiles Introduction Executing Loadfiles Guardian Environment From ... Use ... For more information, see ... A terminal TACL command RUN or RUND RUN or RUND Command An executing program TS/MP transactionprocessing software TS/MP System Management Manual An executing COBOL process (execute the loadfile as a separate process) CREATEPROCESS routine (to create a low-PIN process) CLU_PROCESS_CREATE_ routine (to create a high-PIN process) CRE Programmer’s Guide OSS Environment From ... Use ... For more information, see ... A terminal Name of the executable file (type it and press the return key). The current directory must be in your search path. Running HP COBOL Programs An executing COBOL process (execute the loadfile as a separate process) OSS process create function fork() or tdm_fork(2) Open System Services Programmer’s Guide HP COBOL Manual for TNS/E Programs —520347-003 1 -8 2 Source Program Organization and Format The lines of a COBOL source program are organized into divisions. The program ends with an END PROGRAM statement. Individual lines must follow a reference format that the compiler accepts. Any line in a source program can contain a COPY statement, which tells the compiler to insert source text from a specified disk file, called a COPY library. A run unit can contain more than one source program. Programs in the same run unit can share resources with each other. The programs can be nested, which means that one program contains one or more other programs, which might in turn contain one or more other programs. A nested program can be common, which means that it can be called by any other program contained in the program that contains it. Nested programs are always in the same run unit; therefore, they can share resources. An initial program is one whose program state is initialized whenever any program in its run unit calls it. Topics: • • • • • • • • Source Program Components Reference Format for Source Program Lines COPY Libraries Nested Source Programs Common Programs Programs in the Same Run Unit Initial Programs How Programs Share Resources HP COBOL Manual for TNS and TNS/R Programs —522555-006 2 -1 Source Program Components Source Program Organization and Format Source Program Components The components of a COBOL source program must appear in the order shown in Table 2-1. Table 2-1. Source Program Components Component Required or Optional? Identification Division Required Purpose • • To specify the program name (required) Explained in Section 5 To specify your name, the date, and the program purpose (optional) Environment Division Optional To describe the program’s equipment and processing options and name the files it uses (you must change this information when you move a COBOL program to an HP system from another type of system) 6 Data Division Optional To define the data that the program uses (reserve data storage; define data formats, types, and structures; complete file descriptions) 7 Procedure Division Optional To specify the program activity (the data processing) 8 END PROGRAM statement Depends— see Purpose To mark the end of the program 2 If you submit only one program to the compiler at a time, the END PROGRAM statement is optional. If you compile several programs (one after another or nested), the END PROGRAM statement is required for each program except the one that ends last. You can use an ENDUNIT directive instead of an END PROGRAM statement. The END PROGRAM statement has this syntax: END PROGRAM program-name . VST374.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 2 -2 Reference Format for Source Program Lines Source Program Organization and Format program-name is a COBOL word. It names the same program unit that the PROGRAM-ID does (see PROGRAM-ID Paragraph), for example: IDENTIFICATION DIVISION. PROGRAM-ID. MYPROG. ... END PROGRAM MYPROG. Reference Format for Source Program Lines Individual source program lines must follow a reference format that the compiler accepts. There are two choices of reference format: Tandem and ANSI. Tandem reference format, an HP extension to COBOL, is less restrictive than ANSI. The principal differences between the Tandem and ANSI formats are in: • • • Margin locations Permitted line lengths Absence of sequence number and identification field in Tandem reference format You can write an HP COBOL program completely in either format or in a mixture of both. The default is Tandem reference format. Unless you direct the compiler to accept the ANSI format, the compiler assumes the entire program is in Tandem reference format. (See ANSI and TANDEM.) The rest of this topic describes the Tandem reference format. For information on the ANSI reference format, see Section 16, ANSI Reference Format. Figure 2-1. Tandem Reference Format Margin: C Column: A 1 2 B 3 4 5 6 R 7 Area A 8 9 10 ... n* *n <= 132 Area B Indicator Area Line VST500.vsd Lines in Tandem reference format are not restricted to a fixed length and can have up to 132 characters (longer lines are truncated). The Tandem reference format has no identification field. You can supply comments for your program on separate lines. See Indicator Area. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2 -3 Indicator Area Source Program Organization and Format Topics: • • • Indicator Area Area A and Area B Restrictions Indicator Area The indicator area begins at margin C and ends at margin A, using only column 1. It can be empty, or it can contain a single character that describes the type of information on the line. Table 2-2. Valid Indicator Area Characters (Tandem Reference Format) Character Character Name Meaning and Topic Name ? Question mark Compiler Directive (?) * Asterisk Ordinary Comment (*) / Slash Comment for Top of Next Page (/) D Uppercase D Debugging Line (D or d) d Lowercase d Debugging Line (D or d) - Hyphen Continuation Line (-) Space Text Line Compiler Directive (?) A compiler directive has a question mark (?) in the indicator area. A compiler directive is an instruction to the compiler (for more information on compiler directives, see Compiler Directives). The compiler interprets any line that has a question mark in column 1 as a compiler directive. (This is true even when a program uses ANSI format, in which case the compiler handles the line as if it began with the indicator area. For details on ANSI format, see Section 16, ANSI Reference Format.) Ordinary Comment (*) An ordinary comment has an asterisk (*) in the indicator area. A comment can appear anywhere in a program. The compiler ignores it. Comment for Top of Next Page (/) A comment to be printed at the top of the next page has a slash (/) in the indicator area. Like an ordinary comment, this comment can appear anywhere in a program. The compiler advances to the top of the next page and prints the comment at the top of that page. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2 -4 Source Program Organization and Format Indicator Area Debugging Line (D or d) A debugging line has the letter D or d in the indicator area. If the program includes a DEBUGGING MODE clause, the debugging line is part of the program; otherwise, it is a comment. A debugging line cannot contain embedded SQL/MP or SQL/MX statements. For information on DEBUGGING MODE, see SOURCE-COMPUTER Paragraph. Continuation Line (-) A continuation line has a hyphen (-) in the indicator area. It is a continuation of the previous line. Always leave area A of a continuation line blank. In an HP COBOL source program, you can put a blank line between a continued line and its continuation line. Such a blank line has no effect on the continued line or its continuation (see Text Line). You can continue any word or literal. If you continue a numeric literal, a reserved word, or a user-defined word, the compiler ignores the trailing spaces of the previous line and initial spaces of the continuation line. The rules for continuing a nonnumeric literal in Tandem reference format are: • • The nonnumeric literal does not contain the trailing spaces of the previous line. The first nonblank character in area B of the continuation line must be a quotation mark. The continuation begins with the character immediately following that quotation mark. The rules for continuing a national literal in Tandem reference format are: • • The national literal does not contain the trailing spaces of the previous line. The first nonblank character in area B of the continuation line must be the letter N followed by a quotation mark. The continuation begins with the character immediately following the quotation mark. Example 2-1. Continuation Line in Tandem Reference Format ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 DISPLAY "THIS IS AN EXAMPLE OF CONTINUING A LITERAL " IN TANDEM REFERENCE FORMAT." Text Line The compiler handles any line that begins with a space character as a program text line. Note. If the character in the indicator area is not a question mark, asterisk, slash, the letter D (uppercase or lowercase), or a hyphen, the compiler issues a warning and handles the character as if it were a space. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2 -5 Source Program Organization and Format Area A and Area B If all characters between margin A and margin R are spaces, then the line is a blank line. Blank lines can occur anywhere in the source text and have no effect on either the syntax or semantics of source programs. If at least one character other than spaces occurs after margin A, that character begins a new lexical element. When a program text line is not continued (that is, when its successor text line does not contain a hyphen in its indicator area), the compiler assumes that a space follows the last nonblank character of the first line. If the final character is a period, comma, or semicolon, the assumed space completes the separator begun by that character; otherwise, the assumed space itself acts as a space separator. Area A and Area B HP COBOL ignores the distinction between area A and area B. The lexical elements of a source program can occur anywhere between margin A and margin R. The few exceptions to this are described in Restrictions. Restrictions You can format the text of a source program line freely except as noted in these topics: • • • • • Reserved Words Period Separators Embedded SQL/MP or SQL/MX Statements Comment-Entry Standard COBOL Practice Reserved Words Do not split these reserved words across program lines: • COPY For other restrictions on the format of the COPY statement body, see COPY Statement. • DATE-COMPILED If you split the reserved word DATE-COMPILED across program lines, the compiler handles the paragraph as a simple comment-entry and does not replace its contents with the date and time of compilation. • REPLACE HP COBOL Manual for TNS and TNS/R Programs —522555-006 2 -6 Source Program Organization and Format Restrictions Period Separators Do not put anything other than spaces after the period separator that follows one of these reserved word sequences: • • • DIVISION DECLARATIVES END DECLARATIVES Do not put anything other than spaces or a USE statement after the period separator that follow the reserved word SECTION. Embedded SQL/MP or SQL/MX Statements When COBOL statements and embedded SQL/MP or SQL/MX statements appear on the same line, these restrictions apply: • • The COBOL statements cannot be COPY or REPLACE statements. The COBOL statements must follow the embedded SQL/MP or SQL/MX statement terminator. Comment-Entry The restrictions on the comment-entry are: • • Following a comment-entry, the first keyword in the ensuing text (such as ENVIRONMENT DIVISION or another comment-entry) must begin on a program text line that has a space in the indicator area. This keyword must start in area A, and only space characters can precede the keyword. You cannot continue a comment-entry with the hyphen convention; however, you can implicitly continue it onto additional program text lines, provided that area A in such lines contains only space characters. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2 -7 Source Program Organization and Format Restrictions Standard COBOL Practice Observe these restrictions to conform to standard COBOL practice (HP COBOL does not enforce them). • • Verify that the special constructs DECLARATIVES and END DECLARATIVES (along with each one’s terminating period separator) are completely contained in a single program text line with a space character in the indicator area. Start them in area A and precede them only by space characters. Start each of these in area A of a program text line that has a space in its indicator area: ° ° The keyword or user-defined word naming a division, section, or paragraph The initial keyword of an END PROGRAM statement Any characters preceding these words must be space characters. • • • Start the level-numbers 01 and 77 and all level indicators (FD and SD) in area A of a program text line with a space character in the indicator area and precede them only by space characters. Other level-numbers can start in either area A or area B. When a lexical element that starts in area A of a program text line is followed by a separator, you can start the next element (if any) on that line at any point after the separator; otherwise, start all lexical elements other than those mentioned in the preceding rules in area B. Always start continuations of lexical elements in area B. Verify that both of the characters that comprise the pseudo-text separator, ==, appear on the same program text line. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2 -8 Source Program Organization and Format COPY Libraries COPY Libraries Any line in a source program can contain a COPY statement, which tells the COBOL compiler to insert source text from a specified disk file, called a COPY library. A COPY library is an EDIT or OSS ASCII file divided into one or more sections that begin with a SECTION directive. In the COPY library, you can specify the reference format of the line or lines to be copied. You can specify the name of a COPY library in the source program or in a command to compile the program: • • The COPY statement itself can include the phrase IN library-name (see COPY Statement). The command that initiates the compilation can specify a library-name for the compiler to use whenever a COPY statement does not include a library-name (see Starting a Compilation). If you do not specify a library-name in the compile command or in the COPY statement, the compiler uses the name COPYLIB. If you do not fully qualify library-name in the compile command or in the COPY statement, the compiler assumes the library file is on the current default volume or subvolume or both. For details on the COPY statement and COPY libraries, see COPY Statement. Nested Source Programs Source programs can be nested (that is, a source program can contain other source programs). One program can contain another program directly or indirectly. When a program directly or indirectly contains other programs, each program can use the same user-defined names for different objects. Topics: • • Directly Contained Programs and Indirectly Contained Programs Scope of User-Defined Names HP COBOL Manual for TNS and TNS/R Programs —522555-006 2 -9 Directly Contained Programs and Indirectly Contained Programs Source Program Organization and Format Directly Contained Programs and Indirectly Contained Programs One program can contain another program directly or indirectly. Suppose a program, L, contains another program, R. Program L directly contains program R when program L does not contain any other program that also contains program R. Program L indirectly contains program R if program L does contain any other program that contains program R. In Figure 2-2, all the programs are in the same run unit and: The program … Directly contains … And indirectly contains … Mane Aaa, Bbb Ccc, Ddd Aaa Nothing Nothing Bbb Ccc Ddd Ccc Ddd Nothing Ddd Nothing Nothing Sub Nothing Nothing Figure 2-2. Directly Contained Programs and Indirectly Contained Programs Program: Mane Program: Aaa Program: Bbb Program: Ccc One separately compiled program One run unit Program: Ddd Program: Sub Another separately compiled program VST501.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 10 Scope of User-Defined Names Source Program Organization and Format Scope of User-Defined Names When a program directly or indirectly contains other programs, each program can use identical user-defined names to name objects independent of the use of these userdefined names by other programs. If program X describes a data item named B, and program X includes another program Y, program Y can describe a different data item named B (or even a file connector named B). The B of program Y is entirely separate from the B of program X. The two Bs have different scopes. Table 2-3. Scope of User-Defined Names Type of User-Defined Name What Can Reference It Paragraph-name Section-name Statements and entries in the program that defines it Library-name Text-name Any COBOL program Alphabet-name Class-name Condition-name Mnemonic-name Symbolic character Statements and entries in either the program that contains the Configuration Section or programs that it contains (when the user-defined word is declared in a Configuration Section) Program-name Condition-name* Data-name File-name Record-name Index-name See these topics: • • • Program-Name Condition-Name, Data-Name, File-Name, and RecordName Index-Name * When not declared in the Configuration Section. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 11 Source Program Organization and Format Scope of User-Defined Names Program-Name The PROGRAM-ID paragraph of a program’s Identification Division declares that program’s program-name. Only the CALL and CANCEL statements and the END PROGRAM statement can refer to a program-name. The program-names allocated to programs constituting a run unit are not necessarily unique, but when two programs in a run unit are identically named, at least one of those two programs must be directly or indirectly contained within another separately compiled program that does not contain the other of those two programs. These rules regulate the scope of a program-name: • • • If the program-name, X, is that of a program that does not have the common attribute and is directly contained within another program, Y, then only statements included in Y can refer to X. If the program-name, V, is that of a program that does have the common attribute and is directly contained within another program, W, then any programs directly or indirectly contained within W can reference V; however, program V and any programs contained within V cannot refer to V (because V calling V is recursion, and because V cannot cancel itself). If the program-name, U, is that of a separately compiled program, then U can be referenced by statements included in any other program in the run unit, except programs it directly or indirectly contains. HP COBOL programs that are compiled at the same time but separated by the ENDUNIT directive or by an END PROGRAM statement are called separately compiled, as if they had been compiled by different executions of the compiler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 12 Source Program Organization and Format Scope of User-Defined Names Condition-Name, Data-Name, File-Name, and Record-Name When condition-names, data-names, file-names, and record-names are declared in a source program, only that program can refer to them except when one or more of the names is global and the program contains other programs. The requirements governing the uniqueness of the names allocated by a single program as condition-names, data-names, file-names, and record-names are explained in the topic COBOL Words. A program cannot reference any condition-name, data-name, file-name, or recordname declared in any program it contains. A program P that declares a global name can reference that name. Any program directly or indirectly contained in P can also reference the global name. When program B is directly contained within program A, both programs can declare a condition-name, data-name, file-name, or record-name using the same user-defined word. When program B refers to such a duplicated name, the compiler uses this sequence of rules to determine which object is being referenced: • • • The set of names the compiler uses to identify a referenced object consists of all names that are defined in program B and all global names that are defined in program A and in any programs that directly or indirectly contain program A. Using this set of names, the compiler applies the normal rules of qualification and any other rules for uniqueness of reference until it identifies one or more objects. If the compiler identifies only one object, that object is the reference object. If the compiler identifies more than one object, no more than one of them can have a name local to program B. If zero or one of the objects has a name local to program B, these rules apply: ° If the name is declared in program B, the object in program B is the referenced object. ° If the name is not declared in program B, and if program A is directly contained within another program, C, the referenced object is: ° ° The object in program A if the name is declared in program A and is global. The object in C if the name is not declared in program A or is not global in A, and is declared in C and is global in C; otherwise, the compiler applies this rule to further containing programs until it has found a single valid name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 13 Source Program Organization and Format Common Programs Index-Name If a data item is external and/or global and includes a table accessed with an index, that index is also external and/or global (respectively); therefore, the scope of an indexname is identical to that of the data-name that names the table whose index is named by that index-name, and the scope rules for data-names apply. Index-names cannot be qualified. Common Programs A common program is one that includes the COMMON clause in its Identification Division. A common program can be called by any program directly or indirectly contained in the program that directly contains the common program (except for the called program itself and the programs that it contains). In Example 2-2, if program Aaa includes the COMMON clause, the programs Bbb, Ccc, and Ddd can call it. Programs in the Same Run Unit A program and the programs that it contains are always in the same run unit, but separate programs (not contained in that program and not containing it) can also be in the same run unit. Initial Programs An initial program has an INITIAL clause in its Identification Division. An initial program’s program state is initialized whenever the program is called. If program X is an initial program, whenever a program calls X, the program state of X is the same as when X was first called in that run unit. During the process of initializing an initial program: • • • The program’s internal data items are initialized (see Initializing Data Items). Files with internal file connectors associated with the program are not in the open mode. The control mechanisms for all PERFORM and ALTER statements contained in the program are set to their initial states. The CANCEL and NOCANCEL directives, which determine whether a program is initialized the first time it is called after having been canceled by a CANCEL statement, do not affect initial programs. Initial programs are initialized every time they are called, whether or not they were cancelled. The LESS-CODE directive, which determines which parts of a program are initialized, and how, handles initial programs as special cases (see LESS-CODE). HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 14 Source Program Organization and Format How Programs Share Resources How Programs Share Resources A program can share resources with programs that it contains (directly or indirectly) and programs that are in the same run unit as it is. The resources that a program can share with programs that it contains are: • • • • record-names data-names condition-names file-names The program makes them accessible to the inner programs by declaring them to be global. This enables the inner programs to use the associated data items and file connectors without declaring them. (The opposite of global is local. Local names are only accessible to the program that declares them.) The resources that a program can share with programs in its run unit are: • • data items file connectors The program makes them accessible to the other programs by declaring them to be external. Any other program in the run unit can use them by likewise declaring them to be external. (The opposite of external is internal. Internal objects are only accessible to the program that declares them—or, if they have global names, to programs within that program—and only one program can declare them.) Topics: • • • • Global and Local Names External and Internal Objects Shared Data Shared Files HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 15 Source Program Organization and Format Global and Local Names Global and Local Names A data-name (which names a data item) or a file-name (which names a file connector) can be either global or local. Suppose that program X declares data-name Y, and program X contains program Z, which also declares data-name Y. When program Z references data-name Y, it is referencing the Y that it declared, not the Y that program X declared, whether program X declared its Y to be global or not. Some names are always global; other names are always local; and some names are either global or local, depending on specifications in the program that declares the names: Name It is global if a GLOBAL clause is in … Record-name its record description entry or the file description entry for the file-name associated with its record description entry (if the record-name is in the File Section) Data-name its record description entry Condition-name an entry to which its data description entry is subordinate (that is, if a data-name is declared global, all condition-names subordinate to it are automatically global) File-name its file description entry In some circumstances, a data description, file description, or record description entry cannot specify the GLOBAL clause (see GLOBAL Clause). If a data-name, file-name, or condition-name declared in a data description entry is not global, the name is local. Global names are inherited by contained programs. Suppose program OUTER declares a name X to be global and contains program INNER, which contains program INNERMOST. As long as program INNER does not define the name X explicitly, a reference to X in INNER refers to the X defined in OUTER. Also, as long as program INNERMOST does not define the name X and program INNER does not define X as a global name, a reference to X in INNERMOST refers to the X defined in OUTER. Global names, as well as local names, can be associated with external and internal objects. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 16 Source Program Organization and Format External and Internal Objects External and Internal Objects An external object is stored in an area that is associated with the run unit rather than with any particular program within the run unit. An internal object is stored in an area that is associated only with the program that describes the object. An external object can be referenced by any program in the run unit that describes the object. All such descriptions must be identical, or the results of the references are unpredictable. References to an external object from different programs are always to the same object. In a run unit, there is only one representation of an external object. External and internal objects can have either global or local names. Topics: • • • Data Records in Working and Extended-Storage File Connectors and Their Records Linkage Section Records Data Records in Working and Extended-Storage To give a data record described in the Working-Storage or Extended-Storage Section the external attribute, include the keyword EXTERNAL in its data description entry. Only record data description entries can include the EXTERNAL clause. Any data item described by a data description entry subordinate to an entry describing an external record also inherits the external attribute. If a record or data item does not have the external attribute, it is part of the internal data of the program that describes it. File Connectors and Their Records To give a file connector the external attribute, include the keyword EXTERNAL in its file description entry. When a file connector has the external attribute, the records and the data items of the file inherit the external attribute. If a file connector does not have the external attribute, it is internal to the program that describes the associated file-name. The data records described subordinately to either of these file description entries are internal to the program that describes the file-name unless the data records themselves are declared to be external: • • A file description entry that does not contain the EXTERNAL clause A sort-merge file description entry Any data items described subordinate to the data description entries for such records are also internal to the program that describes the file-name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 17 Source Program Organization and Format Shared Data Linkage Section Records Data records and any subordinate data items in the Linkage Section are representatives of data items defined in other programs. They are considered to be internal to the program describing them and are directly accessible only to that program; however, they are indirectly accessible to programs called by that program. Shared Data Two programs in a run unit can refer to common data in these circumstances: • • • Any program that has described an external data record can refer to the data content of that record. If program B is contained within program A, both programs can refer to data possessing the global attribute and described in either: ° ° The containing program A Any program that directly or indirectly contains A When a program passes a parameter value by reference, this establishes a common data item—a storage location that each program can access. The called program can refer to a data item in the calling program, using the same identifier or a different identifier. If several programs define a data item as external (causing its storage location to be a single location outside all programs) and they also define the data item as having a global name, then all such programs and all programs nested within each of them have access to the data item. Example 2-2 is a listing of a set of programs that share data through the global and external mechanisms. Example 2-3 shows the output produced by executing the programs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 18 Source Program Organization and Format Shared Data Example 2-2. Programs With Shared Data (page 1 of 4) * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * _______________________________________________________________________ | Program: Mane | | Data: w (local to Mane) | | y (global throughout Mane and its descendants) | | z (global throughout Mane and its descendants, and external) | | Can call: Aaa, Bbb because both are directly contained | | _________________________________________________________________ | | | Program: Aaa | | | | Data: none | | | | Can call: Bbb because Bbb is common | | | | Sub because Sub is separate unit | | | |_________________________________________________________________| | | | Program: Bbb (common) | | | | Data: w (external) | | | | x (global throughout Bbb) | | | | Can call: Ccc because Ccc is directly contained | | | | Sub because Sub is separate unit | | | | ____________________________________________________ | | | | | Program: Ccc | | | | | | Data: w (external) | | | | | | y (local to Ccc) | | | | | | Can call: Ddd because Ddd is directly contained | | | | | | Sub because Sub is separate unit | | | | | | ______________________________________________ | | | | | | | Program: Ddd | | | | | | | | Data: none | | | | | | | | Can call: Sub because Sub is separate unit | | | | | | | |______________________________________________| | | | | | |___________________________________________________| | | | |_________________________________________________________________| | |_______________________________________________________________________| | Program: Sub | | Data: w (external) | | x (local to Sub) | | y (global throughout Sub and any descendants) | | z (global throughout Sub and any descendants, and external) | | Can call: no other routines (calling Mane would be recursion) | |_______________________________________________________________________| Accessibility: Mane ---L / / / . . L . . L . ( ( ( ( L G / . = = = = Aaa --. . . . . . G . . G . Which Routines Can Access Which Data Names? ----Bbb Ccc Ddd Sub Item --- --- ----------------. . . . w of Mane L . . . w of Bbb . L . . w of Ccc . . . L w of Sub L G G . x of Bbb . . . L x of Sub G / G . y of Mane . L . . y of Ccc . . . L y of Sub G G G . z of Mane . . . L z of Sub access because it is locally defined) access because ancestor declared it global) can't access global because of local definition) can't access because no local or global definition)* HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 19 Source Program Organization and Format Shared Data Example 2-2. Programs With Shared Data (page 2 of 4) * Storage 1. W of Bbb, w of Ccc, and w of Sub all refer to one location * Allocation * 2. Z of Mane and z of Sub each refer to one location. * * 3. All other identifiers refer to unique locations. / ?main Mane IDENTIFICATION DIVISION. PROGRAM-ID. Mane. DATA DIVISION. WORKING-STORAGE SECTION. 01 w PICTURE 99 VALUE 3. 01 y PICTURE 99 GLOBAL VALUE 1. 01 z picture 99 GLOBAL EXTERNAL. PROCEDURE DIVISION. m. DISPLAY "Mane begin" MOVE 25 to z PERFORM show-me CALL Aaa PERFORM show-me CALL Bbb PERFORM show-me CALL Sub PERFORM show-me CALL Sub PERFORM show-me DISPLAY "Mane end" stop run . show-me. DISPLAY "in Mane, w=/" w "/ y=/" y "/ z=/" z "/" . IDENTIFICATION DIVISION. PROGRAM-ID. Aaa. PROCEDURE DIVISION. a. DISPLAY " Aaa begin" PERFORM show-me DISPLAY " Aaa adding 2 to y" ADD 2 TO y PERFORM show-me CALL Bbb PERFORM show-me DISPLAY " Aaa end" EXIT PROGRAM . show-me. DISPLAY " y (global from Mane)=/" y "/" " z (global from Mane)=/" z "/" . END PROGRAM Aaa. IDENTIFICATION DIVISION. PROGRAM-ID. Bbb COMMON. DATA DIVISION. WORKING-STORAGE SECTION. 01 x PICTURE 99 GLOBAL VALUE 0. 01 w PICTURE 99 EXTERNAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 20 Source Program Organization and Format Example 2-2. Programs With Shared Data (page 3 of 4) PROCEDURE DIVISION. b. MOVE 1 TO w DISPLAY " Bbb begin" PERFORM show-me DISPLAY " Bbb adding 3 to w and to x" ADD 3 to w x PERFORM show-me CALL Ccc PERFORM show-me DISPLAY " Bbb end" EXIT PROGRAM . show-me. DISPLAY " in Bbb, w (ext)=/" w "/" " x (global in Bbb)=/" x "/" " y (global from Aaa)=/" y "/" . IDENTIFICATION DIVISION. PROGRAM-ID. Ccc. DATA DIVISION. WORKING-STORAGE SECTION. 01 w PICTURE 99 EXTERNAL. 01 y PICTURE 99 VALUE 0. PROCEDURE DIVISION. c. DISPLAY " Ccc begin" PERFORM show-me DISPLAY " Ccc adding 4 to w, x, and y" ADD 4 to w x y PERFORM show-me CALL Ddd DISPLAY " Ccc end" EXIT PROGRAM . show-me. DISPLAY " in Ccc, w (ext)=/" w "/" " x (global from Bbb)=/" x "/" " y (local in Ccc)=/" y "/" . IDENTIFICATION DIVISION. PROGRAM-ID. Ddd. DATA DIVISION. PROCEDURE DIVISION. d. DISPLAY " Ddd begin" DISPLAY " in Ddd, x (global from Bbb)=/" x "/" " y (global from Mane)=/" y "/" MOVE 17 to z DISPLAY " Ddd changing z to 17" DISPLAY " in Ddd, z (global from Mane)=/" z "/" DISPLAY " Ddd end" . END PROGRAM Ddd. END PROGRAM Ccc. END PROGRAM Bbb. END PROGRAM Mane. ?ENDUNIT HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 21 Shared Data Source Program Organization and Format Example 2-2. Programs With Shared Data (page 4 of 4) IDENTIFICATION DIVISION. PROGRAM-ID. Sub. DATA DIVISION. WORKING-STORAGE SECTION. 01 y PICTURE 99 GLOBAL VALUE 2. 01 w PICTURE 99 EXTERNAL. 01 x PICTURE 99 VALUE 0. 01 z PICTURE 99 EXTERNAL. PROCEDURE DIVISION. s. DISPLAY " Sub begin" PERFORM show-me DISPLAY " Sub moving 5 to w" MOVE 5 to w PERFORM show-me IF x = 0 DISPLAY " Sub adding 5 to w, x, y, and z" ADD 5 to w x y z PERFORM show-me END-IF DISPLAY " Sub end" EXIT PROGRAM . show-me. DISPLAY " in Sub, w (ext)=/" w "/ x (local)=/" x "/" " y (local)=/" y "/ z (ext)=/" z "/" . END PROGRAM Sub. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 22 Shared Data Source Program Organization and Format Shared Data Example 2-3. Output From Programs With Shared Data Mane begin in Mane, w=/03/ y=/01/ z=/25/ Aaa begin y (global from Mane)=/01/ z (global from Mane)=/25/ Aaa adding 2 to y y (global from Mane)=/03/ z (global from Mane)=/25/ Bbb begin in Bbb, w (ext)=/01/ x (global in Bbb)=/00/ y (global from Aaa)=/03/ Bbb adding 3 to w and to x in Bbb, w (ext)=/04/ x (global in Bbb)=/03/ y (global from Aaa)=/03/ Ccc begin in Ccc, w (ext)=/04/ x (global from Bbb)=/03/ y (local in Ccc)=/00/ Ccc adding 4 to w, x, and y in Ccc, w (ext)=/08/ x (global from Bbb)=/07/ y (local in Ccc)=/04/ Ddd begin in Ddd, x (global from Bbb)=/07/ y (global from Mane)=/03/ Ddd changing z to 17 in Ddd, z (global from Mane)=/17/ Ddd end Ccc end in Bbb, w (ext)=/08/ x (global in Bbb)=/07/ y (global from Aaa)=/03/ Bbb end y (global from Mane)=/03/ z (global from Mane)=/17/ Aaa end in Mane, w=/03/ y=/03/ z=/17/ Bbb begin in Bbb, w (ext)=/01/ x (global in Bbb)=/07/ y (global from Aaa)=/03/ Bbb adding 3 to w and to x in Bbb, w (ext)=/04/ x (global in Bbb)=/10/ y (global from Aaa)=/03/ Ccc begin in Ccc, w (ext)=/04/ x (global from Bbb)=/10/ y (local in Ccc)=/04/ Ccc adding 4 to w, x, and y in Ccc, w (ext)=/08/ x (global from Bbb)=/14/ y (local in Ccc)=/08/ Ddd begin in Ddd, x (global from Bbb)=/14/ y (global from Mane)=/03/ Ddd changing z to 17 in Ddd, z (global from Mane)=/17/ Ddd end Ccc end in Bbb, w (ext)=/08/ x (global in Bbb)=/14/ y (global from Aaa)=/03/ Bbb end in Mane, w=/03/ y=/03/ z=/17/ Sub begin in Sub, w (ext)=/08/ x (local)=/00/ y (local)=/02/ z (ext)=/17/ Sub moving 5 to w in Sub, w (ext)=/05/ x (local)=/00/ y (local)=/02/ z (ext)=/17/ Sub adding 5 to w, x, y, and z in Sub, w (ext)=/10/ x (local)=/05/ y (local)=/07/ z (ext)=/22/ Sub end in Mane, w=/03/ y=/03/ z=/22/ Sub begin in Sub, w (ext)=/10/ x (local)=/05/ y (local)=/07/ z (ext)=/22/ Sub moving 5 to w in Sub, w (ext)=/05/ x (local)=/05/ y (local)=/07/ z (ext)=/22/ Sub end in Mane, w=/03/ y=/03/ z=/22/ Mane end HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 23 Source Program Organization and Format Shared Files Shared Files Two programs in a run unit can refer to common file connectors in these circumstances: • • Any program that has described an external file connector can refer to that file connector. If program G is contained within program H, both programs can refer to a common file connector. They do so by referring to an associated global file-name (or associated global record-name, in the case of the WRITE and REWRITE statements) described in either: ° ° The containing program H Any program that directly or indirectly contains H If several programs define a file connector as external (causing its storage location to be a single location outside all programs) and they also define the file connector as having a global name, then all such programs and all programs nested within each of them have access to the file connector. HP COBOL Manual for TNS and TNS/R Programs —522555-006 2- 24 3 Language Elements The smallest unit of the COBOL language is a character. You use most characters to form character-strings, and you use a few punctuation characters to form separators. The text of a source program consists of character-strings delimited by separators. Most character-strings and all separators consist of one or more characters from the COBOL character set, which is a subset of the ASCII character set. The characterstrings that are exceptions to this rule are comments and nonnumeric literals, which can contain any of 256 characters (although ASCII characters are recommended). Figure 3-1. Language Element Relationships Source Program Character-Strings COBOL Character Set Punctuation Characters ASCII Character Set 256-Character Set VST502.vsd Topics: • • • COBOL Character Set Punctuation Characters Character-Strings HP COBOL Manual for TNS and TNS/R Programs —522555-006 3 -1 COBOL Character Set Language Elements COBOL Character Set The COBOL character set is a subset of the ASCII character set (which is listed in Appendix A, ASCII Character Set). The COBOL character set has 78 characters; the ASCII character set has 128. Figure 3-2. COBOL Character Set COBOL Character Set Alphanumeric Characters (for COBOL words) Letters (A – Z a–z) Digits (0 – 9) Hyphen (–) Punctuation Characters Special Characters VST503.vsd Table 3-1. Alphanumeric Characters (for COBOL Words) Characters Name of Character Set 0 through 9 Digits A through Z Uppercase letters a through z Lowercase letters - Hyphen or minus sign HP COBOL Manual for TNS and TNS/R Programs —522555-006 3 -2 COBOL Character Set Language Elements Table 3-2. Punctuation Characters Character Name of Character Space , Comma ; Semicolon : Colon . Period " Quotation mark ( Left parenthesis ) Right parenthesis = Equal sign Table 3-3. Special Characters Character Name of Character + Plus sign - Hyphen or minus sign * Asterisk / Stroke or slash $ Currency sign > Greater than sign < Less than sign Except in nonnumeric literals, the compiler handles lowercase letters as equivalent to the corresponding uppercase letters. You can use characters that are not in the COBOL character set in your COBOL source programs in these cases: • • • A character other than the dollar sign ($) can represent the currency symbol in PICTURE clauses (see SPECIAL-NAMES Paragraph) A question mark (?) precedes a compiler directive (see Indicator Area) Comment-entries, comment lines, and nonnumeric literals can contain any characters in the computer’s character set (but some control characters adversely affect the compiler listing) HP COBOL Manual for TNS and TNS/R Programs —522555-006 3 -3 Punctuation Characters Language Elements Punctuation Characters Punctuation characters belong to the COBOL character set and are listed in Table 3-2. In a COBOL source program, you can use a punctuation character in these contexts: • • • • Separators Comments Nonnumeric and National Literals Numeric Literals and PICTURE Character-Strings Separators A separator is one or more consecutive punctuation characters used to separate character-strings, sentences, or special clauses or to delimit other characters in expressions. The punctuation characters that can be used as separators are: • • • • • • • Space Comma or Semicolon Colon Period Quotation Marks Parentheses Equal Sign Every character-string must be followed by a sequence of one or more separators. The syntactic definition of the COBOL language specifies when a sequence can or must contain any of the period, parentheses, colon, or pseudo-text separators. A space separator can always immediately precede or follow any other separator, except where the reference format rules specify otherwise (see Reference Format for Source Program Lines). Note. The rules for using the punctuation characters as separators do not apply within comments, nonnumeric literals, numeric literals, or PICTURE character-strings) Space A space character is a separator. Anywhere that a space is used as a separator or a part of a separator, more than one space can be used. The compiler handles all spaces immediately following a comma, semicolon, or period separator as part of that separator and not as a distinct space separator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3 -4 Separators Language Elements Comma or Semicolon A comma (,) or semicolon (;) that immediately precedes one or more spaces acts as a comma separator or semicolon separator, respectively. Except where explicitly prohibited, you can use comma and semicolon separators anywhere that the specifications permit or require space separators. Colon The colon (:) is a separator that COBOL uses to distinguish a reference modifier from a subscript. The colon marks the end of the leftmost character position portion of the reference modifier. It is required when shown in a syntax diagram. Period A period (.) that immediately precedes one or more spaces acts as a period separator. Period separators are required in certain places by the syntactic definition of COBOL. They cannot appear anywhere else. Each sentence within the Identification and Procedure divisions and each entry within the Environment and Data divisions must end with a period separator. Quotation Marks Quotation marks in balanced pairs enclose nonnumeric literals. You must precede the beginning quotation mark (") with a space and follow the ending quotation mark with a separator space, comma, semicolon, period, or right parenthesis. Except where a literal continues across several lines, each delimiting quotation mark acts as a separator. Within a simple nonnumeric literal, two consecutive quotation marks represent one quotation mark. Parentheses The punctuation characters left parenthesis [(] and right parenthesis [)] serve individually as separators. Parenthesis separators can appear only in balanced pairs delimiting subscripts, reference modifiers, arithmetic expressions, or conditions. The opening member of each balanced pair must be a left parenthesis separator; the closing member must be a right parenthesis separator. Equal Sign The pseudo-text delimiter (==) is a separator. It can only appear in balanced pairs delimiting pseudo-text. An opening pseudo-text separator must be immediately preceded by a space. A closing pseudo-text separator must be immediately followed by a space, comma, semicolon, or period separator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3 -5 Comments Language Elements Comments All characters appearing within a comment-entry or comment line are a part of that entity and are never interpreted as separators in that context. Nonnumeric and National Literals Characters appearing within a character-string that represents a nonnumeric or national literal are components of its value and are never interpreted as separators. Numeric Literals and PICTURE Character-Strings Several punctuation characters (comma, period, left parenthesis, right parenthesis) are also defined as characters available for the formation of numeric literals and PICTURE character-strings. They are not separators in these contexts but instead represent a part of that language element; however, an exception exists if the apparent last character of such a character-string is a period or comma immediately followed by a space. In this case, the period or comma is always interpreted as part of the separator following the character-string, and not as the last character of the numeric literal or PICTURE character-string. Character-Strings A character-string consists of one or more characters that form: • • • • COBOL Words Literals PICTURE Character-Strings Comments Most character-strings are limited to certain characters, but nonnumeric literals (except for hexadecimal literals beginning with X ) and comments can contain any characters. Character-strings and separators form the text of COBOL source programs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3 -6 COBOL Words Language Elements COBOL Words char-1 ns char-n ns VST741.vsd char-1 char-n If the COBOL word is a level-number or segment-number, then char-1 is a digit. If the COBOL word is a section-name or paragraph-name, then these rules apply: • • • • char-1 is a letter (uppercase or lowercase) or a digit. char-n is a letter (uppercase or lowercase), a digit, or a hyphen (-). The last character cannot be a hyphen. The maximum length of the word is 30 characters. If the COBOL word is not a level-number, segment-number, section-name, or paragraph-name, these rules apply: • • • • • • char-1 is a letter (uppercase or lowercase) or a digit. If char-1 is the only character in the word, then it must be a letter. char-n is a letter (uppercase or lowercase), a digit, or a hyphen (-). At least one character must be either a letter or a hyphen. The last character cannot be a hyphen. The maximum length of the word is 30 characters. Figure 3-3. COBOL Words in a Source Program COBOL Words in a Source Program Reserved Words User-Defined Names System-Names VST505.vsd The same COBOL word can be used as a system-name and as a user-defined name within a source program. The class of a specific occurrence of the word is determined by context. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3 -7 COBOL Words Language Elements With the exception described in the preceding paragraph, every name that you reference in a COBOL program must be unique, either because no other name has the same spelling (including hyphenation), or because the name is part of a hierarchy of names (such as a data-name defined within a record). In the latter case, you can qualify the name with one or more of the higher-level names. You must specify enough higher-level names to make the name unique, but you need not specify all levels. The most significant name in a hierarchy must have unique spelling, because you cannot qualify it. Topics: • • • • Reserved Words User-Defined Names System-Names Qualified Names HP COBOL Manual for TNS and TNS/R Programs —522555-006 3 -8 COBOL Words Language Elements Reserved Words A reserved word is a COBOL word that has a special meaning for the compiler. All reserved words appear in uppercase letters throughout this manual. (Some other words, such as product names, also appear in uppercase letters,) A reserved word can appear in the source program only where the language syntax requires or permits it. Every reserved word is unique and cannot be used or redefined for any purpose other than those described in this manual. Table 3-4. Reserved Word Categories Category Definition Examples Keywords Required elements of the language construct for which they are defined MOVE DIVIDE AND OR Optional words Elements of language constructs that you can use or omit, at your discretion (their presence or absence does not affect the meaning of the language construct for which they are defined) ON THEN Special registers Data items that the compiler generates automatically when the source program uses the associated language DEBUG-ITEM GUARDIAN-ERR LINAGE-COUNTER LINE-COUNTER* PAGE-COUNTER* PROGRAM-STATUS Figurative constants Words that name and reference constant values SPACE ZERO Special-character words Required arithmetic and relational operators, used in arithmetic expressions and relation conditions, respectively + * / ** = < > <= >= * LINE-COUNTER and PAGE-COUNTER are associated with the Report Writer and are not available in HP COBOL. For a list of all reserved words, see Section 21, Reserved Words. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3 -9 COBOL Words Language Elements User-Defined Names A user-defined name is a COBOL word that you compose for your own use. You cannot use a reserved word for a user-defined name. You can compose words for these types of items: alphabet-name index-name paragraph-name segment-number class-name level-number program-name symbolic-character data-reference library-name routine-name text-name file-name mnemonic-name section-name In general, each user-defined name in each category must identify a unique entity within the source program. Exceptions: • • • • • • Level-numbers and segment-numbers have no uniqueness constraints. Using an all-digit word as a section-name or paragraph-name does not interfere with its concurrent use as a level-number or a segment-number. The same paragraph-name can identify two or more paragraphs if each paragraph appears in a different section of the Procedure Division. Using a word as a library-name does not interfere with its concurrent use as the name of an entity in another category (this is an HP extension to COBOL, which does not permit a library-name to duplicate the name of another entity); however, library-names must be unique among themselves. Using a word as a text-name does not interfere with its concurrent use as the name of an entity in another category. The same text-name can identify two or more library texts if each text appears in a different library. The category data-reference includes record-names, data-names, and conditionnames. The same user-defined name can identify two or more entities in any combination of these subcategories; however, a program cannot reference the entities identified by a duplicated name unless the contexts of their definitions permit sufficient qualification to construct a unique reference to each of them (see Qualified Names). System-Names Although COBOL does not define any specific system-names, it includes several syntactic definitions that require them. COBOL limits the forms of system-names to those permitted for user-defined names. HP COBOL relaxes this restriction. The use of each particular system-name is limited to contexts appropriate for its category. The few minor restrictions on duplicate usages of system-names are discussed in SPECIALNAMES Paragraph. In HP COBOL, system-names are either resource names or file names in the form used by the operating system. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 10 COBOL Words Language Elements The types of system-names are: • Resource names A resource name is a mnemonic-name that identifies part of the environment: Resource Name (mnemonic-name) Environment Part Identified CONSOLE Operator console MYTERM Home terminal CHANNEL-1 through CHANNEL-15 Carriage-control tape channels SWITCH-1 through SWITCH-15 External switches DANSK-NORSK DEUTSCH ESPANOL FRANCAIS-QW FRANCAIS-AZ SVENSK-SUOMI UK USASCII Native character sets For more information on resource names, see SPECIAL-NAMES Paragraph. • Operating system file names The NonStop operating system supports two file systems: the Guardian file system and the Open System Services (OSS) file system. A Guardian file name identifies one of these: ° ° ° ° ° Disk file Input or output device (such as a line printer) Process (such as a requester) Spooler collector Special file name (such as a temporary disk file) For details on Guardian file names, see the Guardian Procedure Calls Reference Manual. An OSS file name identifies one of these: ° ° Disk file Special file name (such as a temporary disk file) For details on OSS file names, see Files in the OSS Environment. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 11 COBOL Words Language Elements • Special names for operating system files A special name is a substitute (in the source program) for a certain operating system file: Operating System File Special Name Guardian OSS #IN The file named in the IN parameter of startup message of current process. The default input device (FD 0)— do not use it in SELECT clauses or the SPECIAL-NAMES paragraph as you can in the Guardian environment. #OUT The file named in the OUT parameter of startup message of current process. The default output device (FD 1)—do not use it in SELECT clauses or the SPECIAL-NAMES paragraph as you can in the Guardian environment. #TERM Home terminal of current process. #TEMP Temporary disk file on default volume. Created during execution of an OPEN statement, purged during execution of a CLOSE statement. You cannot specify a volume name for #TEMP. The volume used for #TEMP is the current default volume. If you want a temporary file on another volume, either specify only the volume name or specify a TACL ASSIGN command with only the volume name, for example: ASSIGN a-file, $vol #DYNAMIC File name specified with the run-time library routine COBOLASSIGN or COBOL_ASSIGN_ during the execution of the current process. Legal only in the SELECT clause of a file-control entry. If you use #DYNAMIC as the file name in an ASSIGN command, TACL accepts it, but does not make the file dynamically assignable, and the file becomes unusable because it has an invalid name. For more information on spooler collectors, see the Spooler Utilities Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 12 COBOL Words Language Elements Qualified Names Every name that you reference in a COBOL program must be unique, either because no other name has the same spelling (including hyphenation) or because the name is part of a hierarchy of names (such as a data-name defined within a record). In the latter case, you can qualify the name with one or more of the higher-level names. You must specify enough higher-level names to make the name unique, but you need not specify all levels. The most significant name in a hierarchy must have unique spelling, because you cannot qualify it. Qualified Condition-Name: condition-name OF conditional-variable-name IN mnemonic-name VST001.vsd Qualified Data-Name: OF data-name data-name IN file-name OF IN VST002.vsd Qualified Paragraph-Name: OF paragraph-name section-name IN VST003.vsd Qualified Text-Name: text-name OF library-name IN VST004.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 13 COBOL Words Language Elements Qualified LINAGE COUNTER: LINAGE-COUNTER OF file-name IN VST005.vsd Within the Data Division, you can use file-names from file description (FD) or sortmerge file description (SD) entries and data-names from data description entries for qualification. Within the levels of qualification, file-names (names associated with level indicators FD and SD) are most significant, then data-names for level-01 items, and then data names for level-02 items, and so on to level-49 items. The name of a conditional variable can qualify any of its condition-names. These rules apply to qualification of names: • • • • • • Each qualifier must be at a higher level than the previous one and stay within the same structure of the name it qualifies. The same name cannot occur at different levels in a structure; otherwise, the name could qualify itself. A data-name used as a qualifier cannot be subscripted; all subscripts that apply to a qualified data-name appear after all qualifiers. A name can be qualified even though it does not need qualification. If there is more than one combination of qualifiers that make a name unique, then any one of them will do, including complete qualification (naming all qualifiers). HP COBOL permits a name to be qualified completely, with a name from every level of its structure. If a data-name or a condition-name is assigned to more than one element in a source program, the data-name or condition-name must be qualified each time it is referred to in the Procedure, Environment, and Data divisions (except in the REDEFINES clause where, by context, qualification is unnecessary). The name of a data-item can be used as the lowest level qualifier for any of its associated condition-names. If a word defined as a status condition-name is assigned to more than one element in a source program, the condition-name must be qualified by the mnemonic-name of its external switch each time it is mentioned in the Procedure Division. The qualification of status condition-names is an HP COBOL extension. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 14 COBOL Words Language Elements • A word can be defined as a paragraph-name more than once in a source program. If more than one paragraph in the same section of a source program has the same name, no statement anywhere in the program can refer to any of those paragraphs by name. If two or more sections of a source program each contains a paragraph with the same paragraph-name, unqualified references to that paragraph-name are acceptable only within such sections—all other references must be qualified. For example, suppose sections S1 and S2 contain paragraphs named P. All references to P in other sections must be qualified as P OF S1 or P OF S2. Without such qualification, they cause the compiler to report an ambiguous reference. Unqualified references made within S1 to P are assumed to refer to P OF S1, and unqualified references made within S2 to P are assumed to refer to P OF S2. Statements in S1 can refer to P OF S2 and statements in S2 can refer to P OF S1. The word SECTION is not part of a section-name when used to qualify a paragraph-name. • • If a text-name is not a member of the default COPY library, it must be qualified by its library-name each time a COPY statement mentions it. If more than one file description entry in a program contains a LINAGE clause, the special register LINAGE-COUNTER must be qualified by its file-name each time the Procedure Division mentions it. In Example 3-1, all data-names except PREFIX are unique. Example 3-1. Qualified Names FD TRANSACTION-FILE ... 01 TRANSACTION-REC. 03 ITEM-NO. 05 PREFIX X(2). 05 CODE X(3). 03 QUANTITY S9(8). ... 01 MASTER-REC. 03 CODE-NO. 05 PREFIX X(2). 05 SUFFIX X(3). 03 DESCRIPTION X(70). Qualification is necessary to refer to either PREFIX item. For example, any of these sentences would move the contents of one PREFIX to the other PREFIX: MOVE PREFIX OF ITEM-NO MOVE PREFIX IN ITEM-NO MOVE PREFIX OF TRANSACTION-REC TO PREFIX OF CODE-NO. TO PREFIX OF MASTER-REC. TO PREFIX IN CODE-NO. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 15 Literals Language Elements It is possible to define a collection of program elements such that even complete qualification fails to establish uniqueness for some of their names. In this case, your program can never reference these elements. To avoid this situation, follow these rules: • • • • • • Do not define two identical data-names subordinate to a data structure unless their references can be made unique through qualification by intermediate data structure names. Do not define two identical record-names subordinate to any file-name. Independent data items (level-77 items) and record items that are not files must have unique names if they are to be referenced. Do not associate two identical condition-names with the same data item. If a word used as a condition-name is also used to identify another program element, then it can be referenced if and only if the associated data item can be referenced. Do not define two identical status condition-names within the same system-name clause of the SPECIAL-NAMES paragraph. If a word used as a condition-name in such a clause is also used to identify another program element, then the clause must also include a unique mnemonic-name to serve as a reference qualifier. Do not put two identical paragraph-names in the same section. If a word used as a paragraph-name is also used to identify another program element, then it can be referenced if and only if its section can be referenced. Sections must have unique names if they are to be referenced. Do not locate two identical text-names in the same COPY library. Literals A literal is a character-string that has a value implied by either of these: • • An ordered set of characters that compose the literal A figurative constant (a special type of reserved word) Topics: • • • • Numeric literals ° ° Decimal Numeric Literals Hexadecimal Numeric Literals Nonnumeric literals ° ° Simple Nonnumeric Literals Hexadecimal Nonnumeric Literals National Literals Figurative Constants HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 16 Literals Language Elements Decimal Numeric Literals A decimal numeric literal is a character-string that has the value of the sequence of its digits. ns digits ns + dp - ns digits dp ns digits VST743.vsd digits is a string of one to 18 digits. The total number of digits in a decimal numeric literal cannot exceed 18. dp is a decimal point. It is a period (“.”) unless the program contains the DECIMAL POINT COMMA phrase in the SPECIAL-NAMES paragraph, in which case it is a comma (“,”). Decimal numeric literals follow these rules: • • • • • When a decimal numeric literal appears in a context where its value is assumed to be a sequence of characters, its size is equal to the number of digits in its representation. A sign character (+ or -) has no effect on the size of a literal. Absence of a sign signifies a positive number. COBOL does not permit the decimal point as the rightmost (last) character; HP COBOL relaxes this restriction somewhat: ° If the apparent last character of a numeric literal qualifies as a decimal point and the immediately following character is not a space (but is a semicolon, comma, or right parenthesis), the compiler interprets that last character as the decimal point. ° If the apparent last character qualifies as a decimal point but the immediately following character is a space, the compiler interprets that last character and the space together as the separator that follows the literal. The compiler interprets a decimal point as an assumed decimal point; that is, the character is not present in the value even if the context of the literal implies that the value is represented as a sequence of characters. A decimal numeric literal that has no decimal point is an integer. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 17 Literals Language Elements Example 3-2. Integer Decimal Numeric Literals +601 -234116 0 15 1234. , (an integer followed by a period separator and a comma separator) Example 3-3. Noninteger Decimal Numeric Literals +601.1 89.6 0.0051 -.1 1234., (a noninteger followed by a comma separator) Hexadecimal Numeric Literals ns H ns ns " hex-digit ns hex-digit " ns VST612.vsd hex-digit is one of the characters 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, a, b, c, d, e, f. The maximum number of hex-digits in a hexadecimal numeric literal is 16 (eight pairs). A hexadecimal numeric literal is considered an unsigned integer. It can appear anywhere that a decimal numeric literal can appear. Example 3-4. Hexadecimal Numeric Literals H"00" H"0F" H"0123456789ABCDEF" H"1003c55b" HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 18 Literals Language Elements Simple Nonnumeric Literals A simple nonnumeric literal is a character-string that has the value of the sequence of its characters. " char " VST744.vsd char is an alphanumeric character or a quotation mark ("). If char is a quotation mark, it must be immediately followed by another quotation mark. Each pair of quotation marks represents a single embedded quotation mark. A simple nonnumeric literal can have at most 160 characters, excluding the delimiting quotation marks. Simple nonnumeric literals follows these rules: • • • • • • The literal must be both preceded and followed by at least one separator. The delimiting quotation marks are part of the character-string that represents the literal; they are not part of the value of the literal. HP COBOL accepts only the double quotation mark ("), not the apostrophe ('), as a quotation mark. The literal does not include the second of two consecutive quotation marks that represent a single, embedded one. All other characters in the literal represent themselves as a part of the literal’s value and have no other interpretation. Lowercase letters are not equivalent to their uppercase counterparts. Punctuation characters are not interpreted as separators. The value of a literal is the ordered sequence of characters in its representation (excluding the delimiting quotation marks and interpreting a pair of contained quotation marks as a single quotation mark character). The literal represents a data item of the alphanumeric category whose value is the value of the literal. Example 3-5. Nonnumeric Literals "THIS IS A NONNUMERIC LITERAL" "This is ANOTHER one. "" IS ONE EMBEDDED QUOTATION MARK" "You don't need to double apostrophes." ". , ; : ( ) == are not separators in literals." HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 19 Literals Language Elements Hexadecimal Nonnumeric Literals ns X ns ns hex-digit " ns hex-digit ns " VST613.vsd hex-digit is one of the characters 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, a, b, c, d, e, f. A hexadecimal nonnumeric literal can have at most 320 hexadecimal digits (160 pairs), excluding the delimiting quotation marks. A hexadecimal nonnumeric literal can appear anywhere that a simple nonnumeric literal can appear. Example 3-6. Hexadecimal Nonnumeric Literals X"00" X"0F" X"0123456789ABCDEF" X"1003c55b" National Literals A national literal is used for those spoken languages not represented by roman letters and Arabic numbers. An example is the Japanese Kanji alphabet. To use national literals, you must have a special terminal and a special keyboard. As with other types of literals, the character-string of a national literal has the value of the sequence of its characters. Each character is represented internally by 2 bytes. " char " N n VST745.vsd char is any character in the national character set, including a punctuation character. A national literal can have at most 160 characters, excluding the delimiting quotation marks. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 20 Literals Language Elements National literals follow these rules: • • • • • The letter N or n and the quotation marks are part of the character-string that represents the literal; they are not part of the value of the literal. HP COBOL accepts only the double quotation mark ("), not the apostrophe ('), as a quotation mark. The value of a national literal is the ordered sequence of characters in its representation, excluding the delimiting quotation marks. The maximum number of characters allowed on a line depends on the column in which the literal begins. The literal represents a data item of the national category whose value is the value of the literal. Punctuation characters appearing within a character-string that represents a national literal are components of its value and are never interpreted as separators. Each character is represented internally as 2 bytes. In general, you can use a national literal anywhere you can use a nonnumeric literal. Exceptions are: • • A national literal cannot be compared to a nonnumeric or numeric literal or to a data item not defined as national. Compare national literals only to other national literals or national data items. A national literal cannot be specified in these paragraphs, statements, phrases, or clauses: ° ° ° ° ° ° • SPECIAL-NAMES paragraph PADDING clause of the SELECT statement RECEIVE-CONTROL paragraph INITIALIZE statement when the REPLACING phrase is used INSPECT statement As literal-1 or literal-2 of the REPLACING phrase of a COPY statement If national literals and national data items are used for items in a STRING statement (delim-1, delim-2, result, or delim-store ), all the items must be national literals or national data items. Figurative Constants A figurative constant is a character-string that has a value the compiler generates from one of the reserved words in the first column of Table 3-5. The value it generates depends on the context in which the figurative constant appears. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 21 Literals Language Elements In general, you can use a figurative constant wherever the syntax rules of the language require or permit a literal. The exceptions to this rule are: • • • • When the literal must be a numeric literal, the only acceptable figurative constant is [ALL] ZERO[[E]S] (which generates the numeric value 0). The other forms of figurative constant always generate a nonnumeric value; therefore, such forms are not acceptable when the context requires a numeric value. There are certain contexts in which you cannot use figurative constants whose source form includes the word ALL. When this is the case, the usage considerations for that particular language element’s syntax mention the usage restriction. The COBOL language includes several constructs where a literal cannot be any figurative constant. When this is the case, the usage considerations for that particular language element’s syntax mention the usage restriction. When SPACE, QUOTE, or ZERO is applied to a national data item, the class of the figurative literal is national. The 2-byte value of the national character set that corresponds to SPACE, QUOTE, or ZERO when the program is compiled is used. For LOW-VALUES and HIGH-VALUES, the highest and lowest positions in the collating sequence are assumed. When a figurative constant represents a nonnumeric or national value, that value is a string of one or more characters. The compiler determines the length of the string according to these rules: • • • • When you associate a figurative constant with a data item (for example, by moving the figurative constant to the data item or by comparing them or using the figurative constant in a VALUE clause), the compiler repeats the figurative constant value character by character until its size equals or exceeds the size of the data item. The compiler then truncates the resultant string from the right end until it has the same number of character positions as the associated data item. This happens prior to and independently of the application of any JUSTIFIED clause for the data item. When you use a figurative constant whose source form does not include the word ALL with a DISPLAY, STRING, STOP, or UNSTRING statement, the compiler generates exactly one character. When you use a figurative constant whose source form does include the word ALL, there are two possibilities: ° If a nonnumeric or national literal follows the word ALL, the compiler generates a string having the length and value of the literal. ° If a nonnumeric or national literal does not follow the word ALL, the compiler generates a string of exactly one instance of the character represented by the reserved word (figurative constant) or the symbolic character that follows the word ALL. The length of a figurative constant in a concatenation expression is one. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 22 Literals Language Elements The result of associating a figurative constant that represents a nonnumeric value with a numeric or numeric-edited data item is defined only when the string the compiler generates from the figurative constant contains only digit characters. In this case, the generated nonnumeric value has the appearance of an integer whose length (in terms of the number of digits it contains) is the same as the length of the associated data item. Table 3-5. Figurative Constants Figurative Constant * What It Represents ZERO[[E]S] One or more of the character zero (0), depending on the context SPACE[S] One or more spaces, depending on the context HIGH-VALUE[S] One or more of the character that has the highest position in the program collating sequence, except in the SPECIAL-NAMES paragraph, where it represents the character that has the highest position in the ASCII character set (the 256th character, which is all binary ones) or in the national character set (default is hexadecimal FFFF) LOW-VALUE[S] One or more of the character that has the lowest position in the program collating sequence, except in the SPECIAL-NAMES paragraph, where it represents the character that has the lowest position in the ASCII character set (the first character, the NUL, which is all binary zeros) or in the national character set (default is hexadecimal 0000) QUOTE[S] One or more of the character quotation mark (") You cannot use either of these words instead of quotation marks to enclose a nonnumeric literal. symbolic-character One or more of the character specified as the value of symbolic-character in the SYMBOLIC CHARACTERS clause of the SPECIAL-NAMES paragraph ALL literal The value of literal must contain one or more of these: • • • • A nonnumeric literal A national literal A symbolic-character One of the other reserved words previously defined as figurative constants (except that you cannot precede an ALL literal form of figurative constant with another ALL) When literal is a nonnumeric literal or a national literal, this form implies repetition of the literal’s value to the extent required by the context. For the other cases, the word ALL is redundant and is used only for readability. * Singular and plural forms are equivalent and can be used interchangeably. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 23 PICTURE Character-Strings Language Elements PICTURE Character-Strings PICTURE character-strings (character-strings in the PICTURE clause) use the COBOL character set as described in PICTURE Clause. The editing characters in Table 3-6 specify the editing operations that a process performs on data when storing it in data items. The compiler recognizes these characters as editing characters only within PICTURE clauses. In all other places, these characters follow the rules for characterstrings and separators. Table 3-6. PICTURE Character-String Editing Characters Character Editing Operation B Space insertion Z Zero suppression 0 Zero + Plus - Minus CR Credit DB Debit * Check protect $ Dollar sign , Comma or decimal point . Period or decimal point / Slash Comments A comment-entry or a comment line can contain any combination of characters in the computer’s character set. Both types of comments are character-strings that serve only to document a program. A comment-entry follows a paragraph header in the Identification Division and can continue on additional lines. A comment line is any line anywhere in the source text that has a comment character in the indicator field. HP COBOL Manual for TNS and TNS/R Programs —522555-006 3- 24 4 Data Fundamentals Every data item in a COBOL program has a level, class and category. Data items are organized into data structures. How data is represented depends on the machine on which it executes. Not all data storage locations in a COBOL program are the same size. When you direct a COBOL program to store a value of a given size at a location of a different size, the process extends or truncates the value according to a set of alignment rules. Alignment considerations sometimes cause the compiler to allocate unused bytes between data items, which are called implicit FILLER data. COBOL provides several ways to refer to individual data items in a program. Topics: • • • • • • • Data Levels, Classes, and Categories Data Structures Data Representation Data Alignment in Receiving Items Data Alignment in Memory Implicit FILLER Bytes References to Data Items Data Levels, Classes, and Categories COBOL has two data levels: elementary item and data structure. An elementary item cannot be subdivided; a data structure can be subdivided (see Data Structures). Data items fall into the classes and categories shown in Table 4-1. The categories are used in PICTURE Clause. Table 4-1. Data Levels, Classes, and Categories Level of Item Class Category Elementary Alphabetic Alphabetic Numeric Numeric Alphanumeric Alphanumeric Alphanumeric Edited Numeric Edited National National Pointer Pointer Alphanumeric Alphanumeric Data structure HP COBOL Manual for TNS and TNS/R Programs —522555-006 4 -1 Data Structures Data Fundamentals Data Structures Data structures—records, files, and tables—are built from elementary items. Levelnumbers show the relationship of elementary data items to data structures. Although the structural forms are defined within a hierarchy, independent structures of any level are permitted. There is no requirement that all data be fully organized to the highest level. Furthermore, multiple structures can refer to the same or overlapping physical data. Topics: • • • • Level-Numbers Records Files Tables Level-Numbers Level-numbers show the relationship of elementary data items to data structures. Level-Number Describes ... 01 through 49 A record (whose level-number starts at 01) and its subordinate data items (whose level-numbers are higher, but not necessarily successive). 66 An elementary item or a data structure introduced by a RENAMES clause. Use level-66 entries to regroup data structures. 77 An entry in the Working-Storage, Extended-Storage, or Linkage section that describes noncontiguous elementary items. These items are not subdivided and are not subdivisions of other items. 88 Condition-name entries, which define a conditional variable to be tested, including a value or range of values assigned to that variable. A data structure includes all data items described after it and before the next item whose level-number is less than or equal to the level-number of that data structure. In Example 4-1, ADDRESS-RECORD includes everything before PERSONAL-RECORD, OFFICE-NUMBER includes everything before OFFICE-ADDRESS, and so on. All elementary or data structures immediately subordinate to a given data structure must have identical level-numbers greater than that of the data structure. In Example 4-1, OFFICE-NUMBER and OFFICE-ADDRESS are immediately subordinate to ADDRESS-RECORD, DISTRICT and REGION are immediately subordinate to OFFICE-NUMBER, and so on. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4 -2 Level-Numbers Data Fundamentals Example 4-1. Level Numbers FD * 01 * * * * 01 01 BRANCH-OFFICE-FILE LABEL RECORDS ARE OMITTED RECORD CONTAINS 100 CHARACTERS DATA RECORDS ARE ADDRESS-RECORD, PERSONNEL-RECORD, MISC-RECORD. A record follows. ADDRESS-RECORD. A data structure follows. 05 OFFICE-NUMBER. An elementary item follows. 10 DISTRICT PICTURE 99. Condition-names follow. 88 NEW-YORK VALUE 21. 88 TAMPA VALUE 43. 88 OMAHA VALUE 55. ... 10 REGION PICTURE 999. 05 OFFICE-ADDRESS. 10 STREET PICTURE X(25). 10 CITY PICTURE X(15). 10 STATE PICTURE X(2). 10 ZIP-CODE PICTURE 9(9). ... A record follows. PERSONNEL-RECORD. 05 OFFICE-MANAGER PICTURE X(35). 05 NO-OF-EMPLOYEES PICTURE 9(4). 05 TAX-GROUPS. 10 HOURLY. 15 PART-TIME PICTURE 99. 15 FULL-TIME PICTURE 99. 10 EXEMPT PICTURE 9(4). ... MISC-RECORD. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 4 -3 Records Data Fundamentals Records A record is a sequence of character positions. It can be an elementary data item or a data structure. Its data description entry determines its internal structure (see PICTURE Clause). Records can be of fixed length or variable length. COBOL programs manipulate logical records and physical records. Most of the data in a typical COBOL program is in records. When a program reads data from or writes data to a file, the unit of transmission is the record. Topics: • • • Physical Records and Logical Records Record Elements Record Length Note. In this manual, “record” means logical record unless “physical record” is specified. Physical Records and Logical Records COBOL programs manipulate physical records and logical records. A physical record is a physical unit of information whose size and recording mode is convenient to a particular computer for the storage of data on an input or output device (such as 80 characters for a terminal or 132 characters for a printer). The size of a physical record is hardware dependent and bears no direct relationship to the size of the file of information contained on a device. A physical record can contain one or several logical records, or a logical record can span several physical records. A logical record is a group of related information, uniquely identifiable, and handled as a unit. The number of logical records that can exist in a file is a characteristic of its supporting storage medium, possibly modified by instructions presented to the file system during the file’s creation. The logical records of a file have either a fixed size or a size that varies between a maximum and minimum size, depending on record type. A logical record is defined by a set of data description entries. Each entry has a levelnumber followed by a data-name and possibly a series of independent clauses. The level-numbers form a structure, dividing a record into smaller and smaller parts. Example 4-2. Logical Record 01 BIBLIOGRAPHY-RECORD. 03 AUTHOR-NAME. 05 LAST-NAME 05 FIRST-NAME 03 TITLE 03 PUBLICATION-INFO. 05 PUBLISHER. 07 PUB-NAME 07 PUB-LOCATION 05 PUBLICATION-YEAR PICTURE X(20). PICTURE X(20). PICTURE X(50). PICTURE X(20). PICTURE X(20). PICTURE 9999. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4 -4 Records Data Fundamentals The concept of logical records also applies to data outside files. You can group data into logical records in all sections of the Data Division. Once you describe the relationship between logical records and physical records, record manipulation is the responsibility of the HP COBOL or CRE run-time routines and the NonStop operating system. Record Elements In COBOL, the lowest subdivisions of a record (that is, those not further subdivided) are called elementary items. Consequently, a record is a series of elementary items, or the record itself can be an elementary item. In Example 4-2, the elementary items are: • • • • • • LAST-NAME FIRST-NAME TITLE PUB-NAME PUB-LOCATION PUBLICATION-YEAR A data structure is a sequence of one or more elementary items that you can refer to by a group name. Data structures in turn can be combined to make other data structures. An elementary item, then, can belong to more than one data structure. A record is a data structure that does not belong to any larger data structure. In Example 4-2, the data structures that contain more than one elementary item are: • • • • AUTHOR-NAME PUBLICATION-INFO PUBLISHER BIBLIOGRAPHY-RECORD Record Length The length of records can be fixed or variable. You specify the length in the file description entry that precedes any data description entries for the records (see File Section). If the file description entry includes a RECORD CONTAINS rec-1 TO rec-2 CHARACTERS or a RECORD IS VARYING IN SIZE FROM rec-1 TO rec-2 CHARACTERS clause, the record length is variable. If the file description entry has no RECORD CONTAINS clause, or if the clause is RECORD CONTAINS n CHARACTERS the record length is fixed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4 -5 Files Data Fundamentals When a file has the fixed-length record type attribute, every record contains the same number of character positions (bytes) and all input and output operations on the file process this fixed size. A program can specify more than one record description for the file, and some record descriptions can describe different numbers of character positions, but every record existing in the file still has the same fixed length. When a file has the variable-length record type attribute, different records can have different numbers of character positions. In this case the input and output operations on the file process whatever size is associated with a particular logical record. After a record retrieval operation, the source program has sole responsibility for determining which of the possible record formats or lengths apply. The logical record length associated with a variable-length record file is therefore a maximum that records cannot exceed, not a constant to which all records conform. The OCCURS clause with a DEPENDING ON phrase defines a variable-size table. For more information, see OCCURS Clause for Variable-Size Tables. Files A file is the highest structural form. Each file is a collection of records, ordered by the file’s organization or by record attributes (keys), and maintained upon some storage medium. Use of the record structure is not limited to files; individual records can exist independently of files. In COBOL, a file is a group of records. A file has both fixed attributes and dynamic attributes. Fixed attributes are determined when you create the file, and you cannot change them subsequently. Dynamic attributes can vary to some extent, depending on the logical specifications that source programs request when they access the file. Some attributes are language-specific. Regardless of file system or operating system, COBOL files have a certain logical structure (organization and access mode). The operating system provides an additional attribute of a file: an exclusion mode when the file is open. A COBOL program references a file by its file connector, which contains information about the file’s attributes. One component of the file connector is the file position indicator, which determines which record is the next one to be sequentially accessed. Topics: • • • • • • Organization Access Mode Open Mode Exclusion Mode File Connector File Position Indicator HP COBOL Manual for TNS and TNS/R Programs —522555-006 4 -6 Files Data Fundamentals Organization Organization, which specifies a file’s logical structure, is a fixed attribute that is established when you create the file and cannot be changed. Table 4-2. File Organization (page 1 of 2) Organization Description Sequential A sequential file is organized so that each record except the first has a unique predecessor record and each record except the last has a unique successor record. These relationships are established by the order in which the records are written and cannot be subsequently changed. The only alterations a program can make to an existing sequential file are record replacement (updating an existing record) and record creation (appending a new record following the last existing record). Under the NonStop operating system, COBOL sequential files are unstructured files or entry-sequenced files. Line Sequential A line sequential file (code 180) is a sequential file that is compatible with the system text editor of the OSS environment; therefore, it can also be called an OSS ASCII text file. A line sequential file differs from a sequential file in that each of its records ends with a line-feed character. For its other characteristics, see Line Sequential Files. Under the NonStop operating system, COBOL line sequential files are line sequential files. Relative A relative file is organized as a sequence of record areas, each capable of holding a logical record. The successive record areas are uniquely identified by successive integer values (called relative record numbers), beginning with one for the first record area. A program can select any record area for an operation by providing the value of its relative record number. Because a program can fill or empty individual record areas independently, without regard to the presence or absence of logical records in any of the other areas, any combination of record areas can be full or empty at any given time in the file’s existence. Under the NonStop operating system, COBOL relative files are relative files. Indexed An indexed file is organized as a set of records uniquely identified by the values of their prime record key, a data item defined within each logical record of the file. A program can select any record for an operation by providing the value of its prime record key. Under the NonStop operating system, COBOL indexed files are keysequenced files. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4 -7 Files Data Fundamentals Table 4-2. File Organization (page 2 of 2) Organization Description Queue A queue file is an indexed file (and therefore, a key-sequenced file) that can function as a queue. Processes can queue and dequeue records in a queue file. Queue files contain variable-length records that are accessed by values in designated key fields. Unlike other key-sequenced files, queue files have prime keys but cannot have alternate keys. The prime key for a queue file includes an 8-byte timestamp; you can add a user key if desired. The disk process inserts the timestamp when each record is inserted into the file, and maintains the timestamp during subsequent file operations. Access Mode The access mode of a file specifies the manner in which the records of the file are to be manipulated: sequential, random, or dynamic. Access mode is a dynamic attribute, described in the COBOL source program that specifies the manner in which the object program unit operates upon records in the file. The access modes available to a file depend on its organization. Table 4-3. Relationship Between File Organization and Access Mode (page 1 of 2) Access Mode File Organization Sequential Random Dynamic Sequential Line sequential Program can read records in the order they were created, one after the other. Program can write records one after another. Not available Not available If the file is in Tandem reference format and has alternate keys, the program can read it in more than one sequential order. * If the file is in Tandem reference format and has alternate keys, this characteristic also applies to the alternate keys. For a description of Tandem reference format, see Reference Format for Source Program Lines. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4 -8 Files Data Fundamentals Table 4-3. Relationship Between File Organization and Access Mode (page 2 of 2) Access Mode File Organization Sequential Random Dynamic Relative Program can select records in increasing order of relative record number (ignoring empty record areas).* Relative record numbers begin at 1. Program can select records from anywhere in the file by specifying relative record numbers. Records need not exist or have contiguous record numbers.* Program can select records sequentially (with READ NEXT statements) or randomly (with READ statements).* Indexed Program can select records in increasing order of prime or alternate record key value (record keys are fields within each record). If records with duplicate alternate key values exist, the order of retrieval is either by prime key or by date of entry. To specify that retrieval order is by date of entry, set a file attribute with FUP.* Program can select records from anywhere in the file.* Program can select records sequentially (with READ NEXT statements) or randomly (with READ statements).* Queue Program can select records in increasing order of prime record key value (record keys are fields within each record). To specify that retrieval order is by date of entry, set a file attribute with FUP. Program can select records from anywhere in the file. Program can select records sequentially (with READ NEXT statements) or randomly (with READ statements). * If the file is in Tandem reference format and has alternate keys, this characteristic also applies to the alternate keys. For a description of Tandem reference format, see Reference Format for Source Program Lines. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4 -9 Files Data Fundamentals Open Mode The open mode is a dynamic attribute of a file connector; it controls which file operations are permitted. In HP COBOL the status of a file connector always includes an open mode. Table 4-4. File Open Modes Mode File Operations Allowed Statements Allowed Locked None UNLOCKFILE Closed Execution of OPEN statement to associate file connector with OPEN its physical file Input Record retrieval operations READ CLOSE Output Record creation operations (deletes existing records upon opening file) WRITE CLOSE Extend Record creation operations (retains existing records upon opening file) WRITE CLOSE I-O Record retrieval, creation, deletion, and replacement operations (as allowed by file organization and access modes) READ WRITE REWRITE DELETE* CLOSE * Relative or indexed file only A file connector that is open in any mode can be closed by a CLOSE statement, which dissociates the file connector from the physical file and sets the open mode state to Closed or Locked (see CLOSE). An internal file connector that is open in any mode can be implicitly closed by a CANCEL statement (see CANCEL). Exclusion Mode In HP COBOL, you specify a file’s exclusion mode when you open it (see OPEN). Table 4-5. Exclusion Modes Mode Other Processes Can Read File Other Processes Can Write to File Shared Yes Yes Protected Yes No Exclusive No No HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 10 Files Data Fundamentals File Connector A COBOL program makes reference to files indirectly. It does not refer to a file by the file’s Guardian file name. Instead, it uses an ASSIGN clause in a file-control entry in the Input-Output Section of the Environment Division (possibly overridden at execution time by command interpreter commands) to associate the Guardian file name with a file connector, which is referred to throughout the remainder of the COBOL program through a COBOL file name. The file connector is an entity that exists at execution time and contains information about the file, such as its open mode, position, and so on. A file connector can be internal or external to a given COBOL program. Unless a file connector is explicitly described as external, it is internal. An internal file connector is associated with and only accessible to the specific program that describes it or to programs contained within that program. An external file connector is associated with the run unit and accessible to every program in the run unit that describes the file connector. The execution of an OPEN statement associates a physical file with a file connector. HP COBOL permits the simultaneous association of one physical file with more than one file connector in a run unit in certain cases. The execution of a CLOSE statement dissociates a physical file from a file connector. In this manual, “file” is often used as an abbreviation for “file connector” and “file name” as an abbreviation for “file referenced by file name.” The context determines the meaning in these cases. File Position Indicator The file position indicator is a conceptual component of a file connector, and its setting is a dynamic attribute of the connector. During sequential record retrieval operations, the setting of the file position indicator determines precisely which record is the next one to be accessed. Normally, the setting reflects: • • • • A record number for a sequential or line sequential file A relative record number for a relative file A prime record key value for an indexed or queue file An alternate record key value for a file with any organization Sometimes its setting indicates that: • • • The at-end condition exists (due to a prior unsuccessful execution of a READ statement for the file). No valid next record has been established. An optional file is not present. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 11 Tables Data Fundamentals The setting of the file position indicator is irrelevant when the open mode is Output or Extend or the access mode is Random, because no sequential record retrieval operations are permitted in these cases. Tables Note. This topic applies to tables in the Data Division, not to SQL/MP or SQL/MX tables. You can define a table by including an OCCURS clause in a data description entry. This clause specifies that the data item be repeated a stated number of times. The item is a table element, and the item’s name and description apply to each repetition of the element. A table is a data structure composed of one or more occurrences of a specified data item. The repeated data item is called a table element. The number of occurrences of a table element can be fixed or variable. If the element is a table itself, or if it contains other tables, the table to which the element belongs is multidimensional. Because table elements do not have individual names, you must reference a table element by the table name and its position in the table. Two methods for giving the position number are subscripting and indexing. For information on subscripting, see Subscripts. For information on indexing, see Using Indexes Instead of Subscripts. Topics explain how to declare: • • • One-Dimensional Tables With Fixed Number of Elements One-Dimensional Tables With Variable Number of Elements Multidimensional Tables One-Dimensional Tables With Fixed Number of Elements You can define a table by including an OCCURS clause in a data description entry. This clause specifies that the data item be repeated a stated number of times. The item is a table element, and the item’s name and description apply to each repetition of the element. For example, this entry defines a 1-dimensional table: 02 TOTAL OCCURS 20 TIMES ... Each reference to TOTAL must have exactly one subscript (except in SEARCH statements and some intrinsic functions, which do not allow subscripts). HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 12 Tables Data Fundamentals Example 4-3. One-Dimensional Table With Fixed Number of Elements WORKING-STORAGE SECTION. 01 MONTH-NAME-TABLE. 05 FILLER PICTURE X(9) VALUE "January". 05 FILLER PICTURE X(9) VALUE "February". 05 FILLER PICTURE X(9) VALUE "March". 05 FILLER PICTURE X(9) VALUE "April". 05 FILLER PICTURE X(9) VALUE "May". 05 FILLER PICTURE X(9) VALUE "June". 05 FILLER PICTURE X(9) VALUE "July". 05 FILLER PICTURE X(9) VALUE "August". 05 FILLER PICTURE X(9) VALUE "September". 05 FILLER PICTURE X(9) VALUE "October". 05 FILLER PICTURE X(9) VALUE "November". 05 FILLER PICTURE X(9) VALUE "December". 01 MONTH-NAMES REDEFINES MONTH-NAME-TABLE. 05 MONTH-NAME OCCURS 12 TIMES PICTURE X(9). One-Dimensional Tables With Variable Number of Elements You can specify a fixed or variable number of occurrences of a table element. An element of a table of the latter form is called a variable-occurrence data item. Because the number of elements in such a table can vary during the execution of a program, the size of each data structure that contains the table can also vary. Such data structures are said to have a variable size. Example 4-4. One-Dimensional Table With Variable Number of Elements WORKING-STORAGE SECTION. 01 ACTIVITY-TABLE-RECORD. 03 ACTIVITY-COUNT PICTURE 99. 03 ACTIVITY-TABLE OCCURS 10 TO 20 TIMES DEPENDING ON ACTIVITY-COUNT INDEXED BY SAVE-INX-1 SAVE-INX-2. 05 ACTIVITY-ENTRY PICTURE 999. Multidimensional Tables The elements of a table can be elementary items or groups of subordinate structures, some of which can also be tables. In Example 4-5, TOTAL-B is a table subordinate to the 1-dimensional table named TOTAL. This means TOTAL-B is a 2-dimensional table; each reference to TOTAL-B must have exactly two subscripts (except in SEARCH statements and some intrinsic functions, which do not allow subscripts). The first subscript specifies the element of the TOTAL table, and the second subscript specifies the element of the TOTAL-B table within that element of TOTAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 13 Data Representation Data Fundamentals Example 4-5. Multidimensional Table 02 TOTAL OCCURS 20 TIMES. 03 TOTAL-A ... 03 TOTAL-B OCCURS 3 TIMES ... A COBOL table can have a maximum of 7 dimensions. If the description of a data item T-B-S subordinate to TOTAL-B also has an OCCURS clause, T-B-S is a 3-dimensional table. The outermost table of a multidimensional table can be of variable size, but each subordinate table must be of fixed size. Data Representation To define a language independent of computer designs, COBOL describes the structure and representation of data in terms of a standard data format. This format represents numbers as integers and represents noninteger and nonnumeric data as strings of characters. The amount of computer storage space occupied by data is measured in character positions. A data item’s description determines how many character positions it has. How data is stored depends on the machine on which it executes. A character position in an HP computer system is a byte: an 8-bit quantity. Data items represented as strings of characters occupy one byte per character. HP COBOL has other data formats that do not maintain the values of data items in characters but use forms more suitable for certain operations. In such cases, the number of bytes into which a data item fits can differ from the number of characters that express the value of the item. Table 4-6. Allocation for COMPUTATIONAL Data Items PICTURE Size in Digits Byte Allocation 1 through 4 2 bytes 5 through 9 4 bytes 10 through 18 8 bytes When an arithmetic or MOVE statement stores a value in a COMPUTATIONAL item, the number of digits stored equals the number of 9 s in the item’s PICTURE clause. Because MOVE statements lack the SIZE ERROR phrase, they cannot detect the loss of high-order digits. In general, the set of bytes the compiler allocates for a record is simply the contiguous sequence of bytes necessary to accommodate its constituent elementary data items. In some cases, however, alignment considerations cause the compiler to allocate unused bytes between data items. These bytes are called implicit FILLER bytes (see Implicit FILLER Bytes). HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 14 Data Alignment in Receiving Items Data Fundamentals Data Alignment in Receiving Items Not all data storage locations in a COBOL program are the same size. When you direct a COBOL program to store a value of a given size at a location of a different size, the process extends or truncates the value according to alignment rules: Category of Receiving Item Standard Alignment Rule Numeric If the receiving data item is numeric, data is aligned by decimal point and zero-filled or truncated on either end of each value, as required. When you do not specify a decimal point in the data item’s description, the decimal point is assumed to be immediately after the rightmost character position. Numeric Edited If the receiving item is numeric edited, data is aligned by decimal point and zero-filled or truncated on either end of each value, as required, except where editing would replace leading zeros. Alphanumeric Alphanumeric Edited Alphabetic National If the receiving data item is alphanumeric, alphanumeric edited, alphabetic, or national, data is aligned at the leftmost character position and space-filled or truncated to the right of each value, as required. Standard data representation and alignment rules are not always appropriate, so these clauses and directive exist to override them: Clause or Directive Effect JUSTIFIED clause Right-justifies an alphanumeric data within a receiving data item (see JUSTIFIED Clause) SYNCHRONIZED clause Aligns an elementary data item on the most natural computer storage boundary (see SYNCHRONIZED Clause) PORT directive Aligns BINARY/COMPUTATIONAL data items on byte boundaries unless the SYNCHRONIZED clause applies to them, in which case standard alignment rules apply (see PORT and NOPORT) Data Alignment in Memory How a data item is aligned in memory is determined by: • • • • Its USAGE clause Whether its description includes the SYNCHRONIZED clause Whether the program is compiled with the PORT directive The machine on which the program executes For efficiency, a data item that is described as USAGE BINARY or USAGE COMPUTATIONAL is aligned on a 2-byte boundary. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 15 Implicit FILLER Bytes Data Fundamentals To improve the alignment of its subordinate items, a level-01 (record) or level-77 data item is aligned on a 2-byte boundary. For TNS processes, a word is 2 bytes (16 bits), so a data item that is aligned on a word boundary is aligned on a byte position that is divisible by 2. For TNS/R processes, a word is 4 bytes (32 bits), so a data item that is aligned on a word boundary is aligned on a byte position that is divisible by 4. The compiler aligns a data item according to its size if one of these conditions is true: • • • The data item is described as USAGE BINARY or USAGE COMPUTATIONAL and the PORT directive is not specified. The data item is described as USAGE NATIVE-n. The data item is described with a SYNCHRONIZED clause. A data item that is aligned according to its size is usually aligned on a character position that is divisible by 2. This is not a TNS/R word size, but this alignment preserves data compatibility. If the PORT directive is specified, BINARY/COMPUTATIONAL data items are not aligned on byte boundaries, and program execution can be much slower. The PORT directive does not affect NATIVE-n data items; they are always aligned on byte boundaries. If the PORT directive is not specified, then a data item is aligned on a 2-byte boundary unless it is described with the SYNCHRONIZED clause. If it is described with the SYNCHRONIZED clause, it is aligned on a 2-byte boundary if its size is less than 4 bytes, and on a 4-byte boundary if its size is 4 bytes or larger. Within a data structure, the compiler might align BINARY/COMPUTATIONAL data items by inserting implicit FILLER bytes. More information: Topics Sources USAGE clause USAGE Clause SYNCHRONIZED clause SYNCHRONIZED Clause PORT directive PORT and NOPORT Implicit filler bytes Implicit FILLER Bytes Implicit FILLER Bytes When an odd number of character positions precedes a 2-byte-aligned item within a record, the compiler inserts FILLER bytes before the item, completing allocation of the preceding 2 bytes. When the number of character positions preceding a 4-byte-aligned item within a record is not a multiple of 4, the compiler inserts the number of FILLER bytes needed to complete allocation of the preceding 4 bytes. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 16 Records Data Fundamentals These extra bytes are not part of the data item. If a data structure contains two items separated by implicit FILLER bytes, then these bytes are a part of that data structure; however, a data structure always begins with the first character position of its first elementary item, ignoring any FILLER bytes that were generated to align that item properly. The initial character positions of a data structure are never implicit FILLER bytes. Topics: • • • Records Tables REDEFINES Clause Records When a record contains implicit FILLER bytes, their character positions are included in the record’s allocation requirements, and they occupy space in external representations of the record. Tables When an elementary data item is described with an OCCURS clause, is subordinate to a data structure described with an OCCURS clause, or both, all occurrences of the data item must be aligned uniformly: 1. The first occurrence of the item is aligned to the required storage boundary. If the elementary item also begins a containing table’s first occurrence, that table’s first occurrence is defined to begin at the first character position of the item. 2. When the aligned item is itself a table, the first occurrence ends on the appropriate storage boundary and the remaining occurrences follow without additional FILLER bytes. 3. When the aligned item (or table of aligned items) belongs to a higher-level table, further adjustment can be necessary. If the elementary item is 2-byte-aligned and the containing group occurrence consists of an odd number of character positions, the compiler inserts one byte of FILLER after each group occurrence. The preceding steps are repeated for each higher-level table. FILLER bytes are not part of the containing occurrences themselves, but are included in data structures that contain the complete table. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 17 REDEFINES Clause Data Fundamentals REDEFINES Clause When a data structure that is the object of a REDEFINES clause contains implicit FILLER bytes, their character positions are included in the character positions redefined. Automatic or requested alignment of data items described by redefinition of a record’s character positions (through use of the REDEFINES clause) follows the rules described previously. When the first data item allocated by a redefinition requires 2byte or 4-byte alignment, the data item being redefined must begin on the appropriate boundary within its record. HP COBOL does not permit redefinitions that require insertion of implicit FILLER bytes before the first data item of the redefinition. Any bytes inserted at other places within the redefinition are counted when determining its size. In Example 4-6, MASTER appears to occupy this many bytes: (((2+1) * 5+1 ) * 5+1) * 5 = 405 bytes but it actually occupies this many bytes (((2+1+1) * 5+1+1) * 5+1+1) * 5 = 560 bytes due to the alignment requirement for the COMPUTATIONAL item. Example 4-6. REDEFINES Clause 01 MASTER. 02 TABLE-1 OCCURS 5 TIMES. 03 TABLE-2 OCCURS 5 TIMES. 04 TABLE-3 OCCURS 5 TIMES. 05 ITEM-A PIC 99 USAGE IS COMP. 05 ITEM-B PIC X. 04 ITEM-3 PIC X. 03 ITEM-2 PIC X. References to Data Items To refer to a data item, a statement in a COBOL program must contain a reference that uniquely identifies that data item. In some cases, data items do not have unique names; for example: • • All elements of a table share a single name. Items that have the same name can occur in different records. To make references unique, you can use qualifiers, subscripts, and reference modifiers. A data-name made unique by a combination of qualifiers, subscripts, and reference modifiers is called an identifier. If an item in a record is tested frequently by a program, assigning a condition-name to the item is a convenient way to refer to the item and show the significance of the item’s value. Assigning a condition-name to the item is also good programming practice. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 18 Qualifiers Data Fundamentals Topics: • • • • • Qualifiers Subscripts Reference Modifiers Identifiers Condition-Names Qualifiers When the name of a data element exists within a hierarchy of names, you must be able to make references to the name unique by mentioning one or more names defined at higher levels of the hierarchy. The higher-level names are called qualifiers. Although you must provide enough qualifiers to make the name unique, you need not include all levels. For more information on qualifiers, see Qualified Names. Subscripts A subscript, or set of subscripts, identifies an element in a table (created by an OCCURS clause). Whenever a statement in the Procedure Division refers to an individual table element or any item subordinate to a table element, that reference must include a subscript. If the data item belongs to a table nested within one or more other tables (because more than one OCCURS clause applies to the data-name), a reference to the data item must include a subscript corresponding to each table (except in SEARCH statements and some intrinsic functions, which do not allow subscripts). If a condition-name is associated with a data item for which subscripts are required, a reference to that condition-name must also include appropriate subscripts. Topics: • • • Subscript Syntax Number and Range of Subscripts Using Indexes Instead of Subscripts HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 19 Subscripts Data Fundamentals Subscript Syntax data-name ( ) subscript condition-name VST006.vsd data-name is either a data item described with an OCCURS clause or a data item subordinate to a data item described with an OCCURS clause. If data-name is qualified, the subscripts follow the qualifiers. condition-name is a level-88 item associated with either a data item described with an OCCURS clause or a data item subordinate to a data item described with an OCCURS clause. If condition-name is qualified, the subscripts follow the qualifiers. subscript integer qualified-name index-name + - offset VST007.vsd integer is a nonzero numeric literal. If it is signed, the sign must be positive. qualified-name is the identifier of an integer numeric data item. It can be qualified, but cannot have subscripts or reference modifiers. index-name is the index in the INDEXED phrase of the OCCURS clause that describes data-name. Its value is the occurrence number of an element in the associated table. The program must initialize the value of an index-name before using it in a subscript. offset is an unsigned integer numeric literal. Its value is added to (+) or subtracted from (-) the value of qualified-name or index-name. Example 4-7 shows subscripting for two 1-dimensional tables and a 2-dimensional table. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 20 Subscripts Data Fundamentals Example 4-7. Subscripting for Tables MOVE TOTAL OF REPORT-MARK (8) TO REPORT-TOTAL-8. MOVE MONTH-NAME (MONTH-NUMBER + 2) TO REPORT-MONTH. MOVE MATRIX (ROW COLUMN) TO OUTPUT-DISPLAY-LINE. Number and Range of Subscripts HP COBOL supports subscripting of up to 7 dimensions. The lowest legitimate subscript value is 1, which selects the first element of a table. The next sequential elements of the table are selected by subscripts whose values are 2, 3, and so on. The highest subscript value, in any particular case, is the maximum number of elements in the table. Any higher subscript is erroneous, and can cause an error. You can use the directive CHECK, with a level-number greater than 1, to include code in the resulting program to perform range checking during execution. If the program attempts to use a subscript that is out of range, the range checking routine reports a fatal error. If you do not include a CHECK directive, the compilation produces a program in which subscript-out-of-range errors go undetected. These undetected errors can cause corruption of other data, producing errors that can be difficult to locate, even with a symbolic debugger. Using Indexes Instead of Subscripts Using an index can be more efficient than using a qualified-name subscript because an index’s value is the actual byte-offset of a table item within the table. A qualified-name subscript’s value (expressed as an occurrence number) must first be converted to a byte-offset value, usually by a multiplication operation. To convert an index value to an occurrence number (or to do the reverse operation), use the SET statement to copy the occurrence number associated with an index-name to a data item (or the other way around). A data item described by a USAGE INDEX clause provides a place to store the value of an index (from an index-name) without converting it to an occurrence number. Use the SET statement to copy the value to or from the index data item. The value stored in this fashion is not an occurrence number and cannot be used with another table. The only statements that can initialize or modify an index are the SET, SEARCH (including SEARCH ALL), or PERFORM statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 21 Reference Modifiers Data Fundamentals Reference Modifiers Reference modifiers allow you to reference an arbitrary portion of a data item’s value, which is important in some applications. With reference modifiers, you define an elementary item by specifying a leftmost character position within a data item and a length for the new item. The unique data item created by reference modifiers can be used not only as a sending item, but also as a receiving item—you can store a new value into it. Topics: • • Reference Modifier Syntax Rules for Reference Modifiers Reference Modifier Syntax identifier ( leftmost-character-position : ) length VST008.vsd identifier is the name of a data item with USAGE DISPLAY. If it is qualified or subscripted, the reference modifier appears after the qualifiers or subscripts. leftmost-character-position is an arithmetic expression. Its value must be a positive nonzero integer less than or equal to the number of characters in identifier; it represents the leftmost character of the portion of identifier you are selecting. length is an arithmetic expression. Its value must be a positive, nonzero integer; it represents the size of the portion of identifier you are selecting. The value of the expression (leftmost-character-position + length ) - 1 must be less than or equal to the number of characters in identifier. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 22 Data Fundamentals Reference Modifiers If length is absent, the defined item begins with leftmost-characterposition and ends with the last character of identifier; thus the length of the defined item is (data-name-length - leftmost-character-position ) + 1 where data-name-length is the length of identifier. Rules for Reference Modifiers These rules for reference modifiers apply directly if the data item referenced by identifier is described as alphabetic or alphanumeric. If the data item is described as numeric, numeric edited, or alphanumeric edited, it is operated upon for purposes of reference modification as if it were redefined as an alphanumeric data item of the same size as the data item referenced by identifier. Any numeric item must be USAGE DISPLAY. If the data item is described as national, the leftmost-character-position and length variables refer to the 2-byte pairs representing the characters, not to individual bytes. In all other respects, these rules for reference modifiers given apply directly: • • • Reference modifiers for an operand are evaluated immediately after evaluation of any subscripts that are specified for that operand. If no subscripts are specified for the operand, the reference modifiers are evaluated at the time subscripting would be evaluated if subscripts had been specified. Each character of the data item referenced by identifier is assigned an ordinal number, incrementing by one from the leftmost position to the rightmost position. The leftmost position is assigned the ordinal number one. If identifier is described with a SIGN SEPARATE clause, the sign position within that data item is assigned an appropriate ordinal number. Reference modifiers create a unique data item, which is a substring of the data item referenced by identifier. The program handles this unique data item as an elementary data item without the JUSTIFIED clause. When identifier references an alphabetic data item, the unique data item has the class and category alphabetic. When identifier references a data item of any other category, the unique data item has the class and category alphanumeric. • The unique data item created by reference modifiers can be used not only as a sending item, but also as a receiving item—you can store a new value into it. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 23 Data Fundamentals Identifiers Example 4-8. Reference Modifiers A program contains these data descriptions: 01 SPREAD. 03 LTH PIC 99 VALUE 10. 03 MM. 05 FF PIC A(10) VALUE "MARGARINE ". 05 GG PIC $$9.99. The same program contains these statements: MOVE 3.15 TO GG DISPLAY MM DISPLAY MM (1:LTH) MOVE "GONE" TO MM (11:) DISPLAY MM Executing the program produces these display: MARGARINE $3.15 MARGARINE MARGARINE GONE Identifiers An identifier is a data-name made unique by a combination of qualifiers, subscripts, and reference modifiers. data-name OF qualified-name IN ( ( subscript ) leftmost-character-position : ) length VST009.vsd data-name is the name of a data item. If it has reference modifiers, it must be USAGE DISPLAY. If it is used as a subscript or qualifier itself, it can be qualified but not subscripted. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 24 Data Fundamentals Condition-Names qualified-name is defined in Qualified Names. subscript is defined in Subscript Syntax. leftmost-character-position is an arithmetic expression. Its value must be a positive nonzero integer less than or equal to the number of characters in data-name ; it represents the leftmost character of the portion of data-name you are selecting. length is an arithmetic expression. Its value must be a positive, nonzero integer; it represents the size of the portion of data-name you are selecting. The value of the expression (leftmost-character-position + length ) - 1 must be less than or equal to the number of characters in data-name. If length is absent, the defined item begins with leftmost-characterposition and ends with the last character of data-name ; thus the length of the defined item is (data-name-length -leftmost-character-position ) + 1 where data-name-length is the length of data-name. Example 4-9. Identifiers UNIQUE-IDENTIFIER ITEM-1 OF GROUP-A ELEMENT OF NAME-TABLE OF MASTER-RECORD (LAST-ACCESSES) PROD-NAME OF ITEM-X (ITEM-DEX) (1:15) Condition-Names Often an item in a record is tested frequently by a program. Assigning a conditionname to the item is a convenient way to refer to the item and show the significance of the item’s value. Every condition-name referred to in a COBOL program must be unique or capable of being made unique through qualifiers, subscripts, or a combination of qualifiers and subscripts. If you use qualifiers to make a condition-name unique, you can use the conditional variable as the first qualifier. You can also use the structure of names for the conditional variable as a qualifier. If references to a conditional variable require subscripting, then any of its condition-names also require subscripting. Example 4-10 defines a condition-name for the conditional variable USE-CODE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 25 Data Fundamentals Condition-Names Example 4-10. Condition-Name 01 INVENTORY. 02 PART-NUMBER OCCURS 100 03 PREFIX 03 USE-CODE 88 RESTRICTED-USE 03 SUPPLIER-SUFFIX TIMES. PICTURE 99. PICTURE 9. VALUE 1. PICTURE 99. This IF statement uses the condition-name RESTRICTED-USE to test the value of USE-CODE: IF RESTRICTED-USE IN PART-NUMBER (30) PERFORM REPORT-VIOLATION ELSE ... Using condition-names also makes it easier to modify the program. Suppose the table definition in Example 4-10 changes so that both 1 and 2 mean RESTRICTED-USE. Without the use of a condition-name, the program must examine and possibly change each instance of the testing of the value of USE-CODE. With the condition-name, only the data description entry needs changing: 88 RESTRICTED-USE VALUES ARE 1, 2. SET RESTRICTED-USE TO TRUE The SET statement sets USE-CODE to the value 1, the first value in the list. HP COBOL Manual for TNS and TNS/R Programs —522555-006 4- 26 5 Identification Division The Identification Division is required in a COBOL program. It has one required paragraph (PROGRAM-ID, which specifies the program name), and five optional paragraphs (which specify your name, the date, and the program purpose). The compiler handles the optional paragraphs as comments, except for the DATECOMPILED paragraph, whose presence causes the compiler to report the compilation time and date in the listing. Topics: • • • Identification Division Syntax PROGRAM-ID Paragraph DATE-COMPILED Paragraph Identification Division Syntax IDENTIFICATION DIVISION . PROGRAM-ID paragraph «AUTHOR paragraph» «INSTALLATION paragraph» «DATE-WRITTEN paragraph» «DATE-COMPILED paragraph» «SECURITY paragraph» VST010.vsd IDENTIFICATION DIVISION. is the division header. It must begin in area A, have a space in the indicator field, and be completely contained on a single program text line. If the order of the paragraphs differs from that shown, the compiler prints a warning message. If any paragraph is repeated, the compiler prints an error message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 5 -1 Identification Division Identification Division Syntax PROGRAM-ID paragraph is defined under PROGRAM-ID Paragraph. AUTHOR paragraph Note. The 1985 COBOL standard classifies the AUTHOR paragraph as obsolete, so you are advised not to use it. Instead, use a comment, as in Example 5-2. AUTHOR . comment-entry VST400.vsd comment-entry is any combination of characters from the ASCII character set. The first keyword following a comment-entry must start on a program text line that has a space character in its indicator field. This keyword must start in area A and be preceded by space characters only. A comment-entry cannot be continued with the hyphen convention; however, it can be implicitly continued onto additional program text lines if area A of those lines contains space characters only. The compiler ignores keywords and periods in comment-entry. The compiler copies comment-entry to the listing as is, except the one in the DATE-COMPILED paragraph (see DATE-COMPILED Paragraph). INSTALLATION paragraph Note. The 1985 COBOL standard classifies the INSTALLATION paragraph as obsolete, so you are advised not to use it. Instead, use a comment, as in Example 5-2. INSTALLATION . comment-entry VST401.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 5 -2 Identification Division Identification Division Syntax DATE-WRITTEN paragraph Note. The 1985 COBOL standard classifies the DATE-WRITTEN paragraph as obsolete, so you are advised not to use it. Instead, use a comment, as in Example 5-2. . DATE-WRITTEN comment-entry VST402.vsd DATE-COMPILED paragraph Note. The 1985 COBOL standard classifies the DATE-COMPILED paragraph as obsolete, so you are advised not to use it. Instead, use a comment, as in Example 5-2. . DATE-COMPILED comment-entry VST013.vsd SECURITY paragraph Note. The 1985 COBOL standard classifies the SECURITY paragraph as obsolete, so you are advised not to use it. Instead, use a comment, as in Example 5-2. SECURITY . comment-entry VST404.vsd Example 5-1. Identification Division With Obsolete Paragraphs IDENTIFICATION DIVISION. PROGRAM-ID. MYPROG AUTHOR. JANE DOE INSTALLATION. HEADQUARTERS DATE-WRITTEN. JANUARY 20, 1992 DATE-COMPILED. JANUARY 21, 1992 SECURITY. COMPANY CONFIDENTIAL HP COBOL Manual for TNS and TNS/R Programs —522555-006 5 -3 Identification Division PROGRAM-ID Paragraph Example 5-2. Identification Division With Comments * * * * * IDENTIFICATION DIVISION. PROGRAM-ID. MYPROG AUTHOR. JANE DOE INSTALLATION. HEADQUARTERS DATE-WRITTEN. JANUARY 20, 1992 DATE-COMPILED. JANUARY 21, 1992 SECURITY. COMPANY CONFIDENTIAL PROGRAM-ID Paragraph The required PROGRAM-ID paragraph names the COBOL program and (optionally) declares it to be an initial program, a common program, or both. The name that the PROGRAM-ID paragraph gives the program can differ from the filename of the source code file or that of the object file. It is the name by which the program is called by another COBOL program’s CALL statement. You can also use it to qualify a file-name in the TACL command ASSIGN. PROGRAM-ID . . program-name program-type IS PROGRAM VST011.vsd program-name is a COBOL word. It names the program unit. program-type INITIAL COMMON COMMON INITIAL VST012.vsd INITIAL makes the program an initial program, which means that the program is in the initial program state each time it is executed—that is, all internal program entities (data item values, file connectors, and so on) are in their initial states at the start of each execution of the program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 5 -4 Identification Division DATE-COMPILED Paragraph COMMON makes the program common, which means that the program must be contained within another program and can be called by any other program contained (directly or indirectly) in the same containing program, but not by the programs it contains. Usage Considerations: • • A Program Can Be Both Initial and Common Storage Allocation For an Initial Program For an initial program, all data items are allocated dynamically. When a program declares very large data items that do not have initial values assigned, including a NOBLANK directive in the compilation saves significant amounts of compilation time, object program storage space on disk, and run-time initialization time. If you must initialize such items to spaces, use VALUE clauses, INITIALIZE statements, or MOVE statements of the form: MOVE ALL SPACES TO x. • Qualification of a File-Name in an ASSIGN Command The program-name can also be used in the command interpreter ASSIGN command, where it serves to qualify a file-name. For example, suppose a COBOL program having the program-name “MAILING-LIST” contains the statement: SELECT IN-FILE ASSIGN TO "$WEST.CALIF.LIVEONES"... You can reassign the IN-FILE of that program by issuing the command interpreter command ASSIGN MAILING-LIST.IN-FILE, $MIDWST.OKLA.PROSPCTS before executing the object program. See the Guardian User’s Guide for more information about the ASSIGN command. DATE-COMPILED Paragraph Note. The 1985 COBOL standard classifies the DATE-COMPILED paragraph as obsolete, so you are advised not to use it. Instead, use a comment, as in Example 5-2. The DATE-COMPILED paragraph directs the compiler to report the compilation date and time in the listing, which the compiler already does by default. DATE-COMPILED . comment-entry VST013.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 5 -5 Identification Division DATE-COMPILED Paragraph DATE-COMPILED must begin in area A, have a space in the indicator field, be completely contained on a single program text line, and end with a period followed by a space. If you split the reserved word DATE-COMPILED across program lines, the compiler handles the paragraph as a simple comment-entry and does not replace its contents with the date and time of compilation. comment-entry is any combination of characters from the ASCII character set. The first keyword following a comment-entry must start on a program text line that has a space character in its indicator field. This keyword must start in area A and be preceded by space characters only. A comment-entry cannot be continued with the hyphen convention; however, it can be implicitly continued onto additional program text lines if area A of those lines contains space characters only. Except for checking its syntax, the compiler ignores comment-entry and replaces it with the date and time of the compilation, which it prints on the listing in this format: DATE-COMPILED. yy/mm/dd - hh:mm:ss where: Number Range Represents yy 00 through 99 Year mm 01 through 12 Month dd 01 through 31 Day hh 00 through 23 Hour ss 00 through 59 Second Example 5-3. DATE-COMPILED Paragraph Source text: DATE-COMPILED. This is the final version. Listing text: DATE-COMPILED. 92/01/08 - 14:45:00 HP COBOL Manual for TNS and TNS/R Programs —522555-006 5 -6 6 Environment Division The Environment Division is optional in a COBOL program. It has two optional sections, the Configuration Section and the Input-Output Section. The Configuration Section states the type of computer on which to compile the program and the type of computer on which to run the program. This section can also: • • • Define the association between program-supplied names and system-supplied facilities such as program switches or character sets Provide for substitution of the dollar sign ($) and decimal point (.) characters Adjust the character set to allow national alphabet extensions to pass the ALPHABETIC test The Input-Output Section includes: • • • File declarations File buffer allocations $RECEIVE supplementary declarations for interprocess communication If the program does not need to describe anything previously listed and does not use files, it does not need the Environment Division. If the program has the Environment Division and you move the program to an HP system from another type of system, you must change the information in the Environment Division. Topics: • • • Environment Division Syntax Configuration Section Input-Output Section HP COBOL Manual for TNS and TNS/R Programs —522555-006 6 -1 Environment Division Environment Division Syntax Environment Division Syntax ENVIRONMENT DIVISION . CONFIGURATION section INPUT-OUTPUT section VST014.vsd ENVIRONMENT DIVISION. is the division header. It must begin in area A. CONFIGURATION section is defined in Configuration Section. INPUT-OUTPUT section is defined in Input-Output Section. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6 -2 Environment Division Configuration Section Configuration Section The Configuration Section is forbidden in a contained program and is optional in any other program. The compiler prints a warning if a Configuration Section paragraph is out of order; it reports an error if a paragraph is repeated. CONFIGURATION SECTION . SOURCE-COMPUTER paragraph OBJECT-COMPUTER paragraph SPECIAL-NAMES paragraph VST015.vsd SOURCE-COMPUTER paragraph is defined in SOURCE-COMPUTER Paragraph. OBJECT-COMPUTER paragraph is defined in OBJECT-COMPUTER Paragraph. SPECIAL-NAMES paragraph is defined in SPECIAL-NAMES Paragraph. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6 -3 Environment Division SOURCE-COMPUTER Paragraph SOURCE-COMPUTER Paragraph The optional SOURCE-COMPUTER paragraph names the computer system on which the program is compiled and can specify that debugging lines be compiled. SOURCE-COMPUTER . . name DEBUGGING MODE WITH VST016.vsd name is any sequence of ASCII characters except WITH, DEBUGGING, or MODE. It names the computer system on which the program is compiled. DEBUGGING MODE puts any source line that has D or d in its indicator field into the object program, along with any USE DEBUGGING sections in the Declaratives Portion of the Procedure Division (see USE DEBUGGING). The process executes USE DEBUGGING sections only if the PARAM DEBUG ON command is active in the command interpreter environment. The process executes debugging lines whether the PARAM DEBUG ON command is active or not. Note. The 1985 COBOL standard classifies USE DEBUGGING as obsolete, so you are advised not to use it, even in TNS HP COBOL programs. The NMCOBOL compiler does not recognize it. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6 -4 Environment Division OBJECT-COMPUTER Paragraph OBJECT-COMPUTER Paragraph The optional OBJECT-COMPUTER paragraph names the computer system on which the object program can run. OBJECT-COMPUTER . . name «MEMORY-SIZE clause» PROGRAM COLLATING SEQUENCE clause «SEGMENT-LIMIT clause» CHARACTER-SET clause VST017.vsd name is any combination of character-strings except reserved words and separators (except period (.)). It is handled as a comment. MEMORY-SIZE clause Note. The 1985 COBOL standard classifies the MEMORY-SIZE clause as obsolete, so you are advised not to use it. is checked for proper syntax but otherwise ignored. For more information, see MEMORY-SIZE Clause. PROGRAM COLLATING SEQUENCE clause specifies a collating sequence for use in nonnumeric comparisons. For more information, see PROGRAM COLLATING SEQUENCE Clause. SEGMENT-LIMIT clause Note. The 1985 COBOL standard classifies the SEGMENT-LIMIT clause as obsolete, so you are advised not to use it. is checked for proper syntax but otherwise ignored. For more information, see SEGMENT-LIMIT Clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6 -5 Environment Division OBJECT-COMPUTER Paragraph CHARACTER-SET clause defines the ALPHABETIC class. For more information, see CHARACTER-SET Clause. MEMORY-SIZE Clause Note. The 1985 COBOL standard classifies the MEMORY-SIZE clause as obsolete, so you are advised not to use it. HP COBOL ignores the MEMORY SIZE clause except to check its syntax. MEMORY integer SIZE WORDS CHARACTERS MODULES VST018.vsd integer must be in the range 1 through 32,767 but is otherwise ignored. WORDS CHARACTERS MODULES are ignored. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6 -6 Environment Division OBJECT-COMPUTER Paragraph PROGRAM COLLATING SEQUENCE Clause The PROGRAM COLLATING SEQUENCE clause enables you to specify an arbitrary collating sequence for use in nonnumeric comparisons and changes the values of the figurative constants HIGH-VALUE, HIGH-VALUES, LOW-VALUE, and LOW-VALUES. This clause has no effect on national data items, which are collated in ascending order of binary value (of the 2-byte pair representing the character). SEQUENCE PROGRAM COLLATING alphabet-name IS VST019.vsd alphabet-name is defined in an ALPHABET clause in the SPECIAL-NAMES paragraph. For more information, see ALPHABET Clause. SEGMENT-LIMIT Clause Note. The 1985 COBOL standard classifies the SEGMENT-LIMIT clause as obsolete, so you are advised not to use it. HP COBOL ignores the SEGMENT LIMIT clause except to check its syntax. All segment-numbers, from 01 to 49, are permanent. segment-number SEGMENT-LIMIT IS VST020.vsd segment-number must be in the range 1 through 49 but is otherwise ignored. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6 -7 Environment Division OBJECT-COMPUTER Paragraph CHARACTER-SET Clause The CHARACTER-SET clause is an HP COBOL extension that enables you to specify the national character set defining the ALPHABETIC data class. character-set-type CHARACTER-SET IS VST021.vsd character-set-type is a keyword in the left column of this table, representing an alphabet in the right column: character-set-type Alphabets DANSK-NORSK Danish, Norwegian DEUTSCH German ESPANOL Spanish FRANCAIS-AZ French (AZERTY keyboard) FRANCAIS-QW French (QWERTY keyboard) SVENSK-SUOMI Swedish, Finnish UK United Kingdom USASCII United States ASCII In COBOL, this clause affects only the ALPHABETIC-UPPER, ALPHABETIC-LOWER, and ALPHABETIC tests. In SCREEN COBOL, the CHARACTER-SET IS clause has some additional semantics, including terminal configuration (see the Pathway/TS SCREEN COBOL Reference Manual). The CHARACTER-SET clause does not define the character sets used for national literals or national data items. The default character set is USASCII. The UK character set designator is handled as a comment, because it contains no extensions to the ALPHABETIC class. When the character set is USASCII (or UK), the ALPHABETIC class test work as Table 6-1 shows. Table 6-1. How Alphabetic Class Tests Work With Default Character Set Test Verifies that each character is … ALPHABETIC A space or a letter between A and Z or between a and z ALPHABETIC-UPPER A space or a letter between A and Z ALPHABETIC-LOWER A space or a letter between a and z HP COBOL Manual for TNS and TNS/R Programs —522555-006 6 -8 Environment Division OBJECT-COMPUTER Paragraph If you specify a character-set-type other than USASCII or UK, the ALPHABETIC class includes additional characters (see Table 6-2). The French character sets differ only in non-ALPHABETIC characters. Table 6-2. Additional Characters Accepted by Alphabetic Class Tests With Nondefault Character Sets ASCII Character (Decimal Value and ASCII Graphic) 91 [ 92 \ 93 ] DANSK-NORSK U U DEUTSCH U U Character Set 64 @ ESPANOL 94 ^ 96 123 { 124 | 125 } 126 ~ U L L L L U L L L L U L FRANCAIS-QW L L L L L FRANCAIS-AZ L L L L L SVENSK-SUOMI U L L L U U U U L L = This character is ALPHABETIC and ALPHABETIC-LOWER. U = This character is ALPHABETIC and ALPHABETIC-UPPER. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6 -9 L Environment Division SPECIAL-NAMES Paragraph SPECIAL-NAMES Paragraph The optional SPECIAL-NAMES paragraph assigns names of your choice to certain system-names. In addition, you can define a currency sign other than the dollar sign ($), and you can exchange the function of commas and periods in PICTURE characterstrings and numeric literals. National literals and national data items cannot be used in the SPECIAL-NAMES paragraph. SPECIAL-NAMES . System-Name clause . File-Mnemonic clause ALPHABET clause SYMBOLIC CHARACTERS clause CLASS clause CURRENCY SIGN clause DECIMAL-POINT clause VST022.vsd Topics: • • • • • • • System-Name Clause File-Mnemonic Clause ALPHABET Clause SYMBOLIC CHARACTERS Clause CLASS Clause CURRENCY SIGN Clause DECIMAL-POINT Clause HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 10 Environment Division SPECIAL-NAMES Paragraph System-Name Clause IS system-name mnemonic-name STATUS phrase VST023.vsd system-name is the name of a hardware device, carriage-control tape channel, or external switch. If the System Name clause has no STATUS phrase, system-name must be one of these values: Value Meaning CONSOLE Operator console MYTERM Process’s home terminal CHANNEL-1 through CHANNEL-12 Carriage-control tape channel Note. The operator console that CONSOLE specifies is $0, an output-only device. If you post an ACCEPT to this device, a run-time error occurs. mnemonic-name is a name you choose for the hardware device, carriage-control tape channel, or external switch specified by system-name. STATUS phrase on-phrase off-phrase off-phrase on-phrase VST746.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 11 Environment Division SPECIAL-NAMES Paragraph on-phrase switch-on ON STATUS IS VST025.vsd switch-on is a condition-name for testing the settings of switches. You do not have to specify a mnemonic-name for a switch; you can just define this conditionname. off-phrase switch-off OFF STATUS IS VST026.vsd switch-off is a condition-name for testing the settings of switches. You do not have to specify a mnemonic-name for a switch; you can just define this conditionname. Usage Considerations: • System-Name Clause Without a STATUS Phrase When the System Name clause has no STATUS phrase, system-name must be one of these values: Value Meaning CONSOLE Operator console MYTERM Process’s home terminal CHANNEL-1 through CHANNEL-12 Carriage-control tape channel ° system-name is CONSOLE When system-name is CONSOLE, the System-Name clause assigns a mnemonic-name to the operator console. You can then use the mnemonicname in DISPLAY statements, as in this example: SPECIAL-NAMES. CONSOLE IS OPERATOR-CONSOLE ... ... DISPLAY "MOUNT THE PAYROLL MASTER TAPE" UPON OPERATOR-CONSOLE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 12 Environment Division SPECIAL-NAMES Paragraph You cannot use the mnemonic-name in ACCEPT statements, because CONSOLE maps to $0, an output-only device. ° system-name is MYTERM When system-name is MYTERM, the System-Name clause assigns a mnemonic-name to the home terminal You can then use the mnemonic-name in ACCEPT and DISPLAY statements, as in this example: SPECIAL-NAMES. MYTERM IS MY-TERMINAL . ... DISPLAY "MOUNT THE PAYROLL MASTER TAPE" UPON MY-TERMINAL. ... ACCEPT EMPLOYEE-NAME FROM MY-TERMINAL. ° system-name is CHANNEL-1 … CHANNEL-12 When system-name is one of CHANNEL-1 … CHANNEL-12, the SystemName clause assigns a mnemonic-name to the channel in a printer carriagecontrol tape. This assignment allows the ADVANCING phrase of a WRITE statement to specify a channel skip instead of a line count, as in this example: SPECIAL-NAMES. CHANNEL-1 IS SIXTEENTH-LINE ... ... WRITE HEADING AFTER ADVANCING SIXTEENTH-LINE. • System-Name Clause With a STATUS Phrase When the System Name clause has a STATUS phrase, system-name must be the name of an external switch: SWITCH-1 through SWITCH-15. In the Guardian environment, set these switches at run time using the TACL command PARAM. In the OSS environment, set these switches with environment variables. The System-Name clause assigns a mnemonic-name to the chosen external switch in SET statements in your program. Conditional statements in the program can refer to the switch only through the condition-names you choose for switchon and switch-off. You can give a mnemonic-name to the switch itself, but you must declare at least one STATUS phrase for the switch because only the condition-name of the STATUS phrase can be used for testing within the program. The mnemonic-name has no purpose other than to qualify the condition-name. You can code either the ON STATUS or the OFF STATUS phrase first, but you can use only one of each phrase for each system-name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 13 Environment Division SPECIAL-NAMES Paragraph Example 6-1. ON STATUS Phrase SPECIAL-NAMES. SWITCH-4 IS TRANSACTION-TRACE, ON STATUS IS TRACING-TRANSACTIONS ... ... IF TRACING-TRANSACTIONS WRITE ... File-Mnemonic Clause The File-Mnemonic clause is, technically, a variant of the “system-name IS mnemonic-name ” clause, but its purpose is significantly different. It defines filemnemonic to be either a name that Binder or the linker uses to resolve an external reference in the Procedure Division (see CALL and ENTER) or a name suitable for use in ACCEPT and DISPLAY statements. The keyword FILE informs the compiler that the next token is either an operating system file name or (in the Guardian environment) a DEFINE name. FILE system-file-name IS file-mnemonic define-name-literal system-file-name-word VST027.vsd system-file-name is a partially or fully qualified operating system file name. It can be represented as a nonnumeric literal (enclosed in quotation marks). In the Guardian environment, system-file-name must be represented as a nonnumeric literal if it has the same spelling as a COBOL reserved word or has the form subvolume-name.file-name. If system-file-name consists of a single user-defined word or begins with one of the characters in this table, the compiler recognizes it as a file name without its being in quotation marks: First Character Meaning \ System-name qualifier $ Volume-name or process-name qualifier # Special operating system file name qualifier In the OSS environment, system-file-name must have the syntax described for filename in OSS Pathnames for OSS Files. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 14 Environment Division SPECIAL-NAMES Paragraph define-name-literal is a nonnumeric literal that specifies the name of a DEFINE of type MAP. For information about DEFINE names, see DEFINEs. system-file-name-word is a single user-defined word that specifies the name of an operating system file, not qualified by any system name, volume name, or subvolume name. It cannot be a nonnumeric literal. It cannot represent a DEFINE name. file-mnemonic is a name you choose as an alias for the operating system file name or (in the Guardian environment) the DEFINE name. You can use it in ACCEPT, CALL, DISPLAY, and ENTER statements. ALPHABET Clause The ALPHABET clause provides a way for you to associate a name with a specified character code set, collating sequence, or both. You can use the alphabet-name that you define in the ALPHABET clause in: • • • PROGRAM COLLATING SEQUENCE clause of the OBJECT-COMPUTER paragraph COLLATING SEQUENCE phrase of a SORT or MERGE statement CODE-SET clause of a file description entry ALPHABET alphabet-name IS STANDARD-1 STANDARD-2 NATIVE EBCDIC literal-phrase VST028.vsd alphabet-name is a user-defined word, the name to be associated with the character code set that you define. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 15 Environment Division SPECIAL-NAMES Paragraph STANDARD-1 STANDARD-2 NATIVE specify the USASCII character set. EBCDIC specifies the Extended Binary-Coded Decimal Interchange Code. literal-phrase literal-1 THROUGH literal-2 THRU ALSO literal-3 VST029.vsd defines an alphabet explicitly. An alphabet-name defined by literal-phrase cannot be used in the CODE-SET clause in a file description entry. If you use literal-phrase, you cannot specify a given character more than once in the ALPHABET clause. literal-1 literal-2 literal-3 are unsigned integer literals or nonnumeric literals, but not symbolic-character figurative constants. An unsigned integer literal must have a value in the range 1 through 256. It is the ordinal number of a character position in the computer’s character set (the first character has ordinal number 1, even though its representation is octal 00). A nonnumeric literal is an actual character or set of characters in the computer’s character set. If a nonnumeric literal consists of exactly one character, the literal identifies that character. If a nonnumeric literal consists of more than one character, the compiler handles it as an abbreviation for a consecutive series of literal phrases that identify each of the specified characters individually, in the order they appear in the nonnumeric literal. Each nonnumeric literal in a THROUGH or ALSO phrase must specify exactly one character. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 16 Environment Division SPECIAL-NAMES Paragraph Usage Considerations: • Alphabet-Name in PROGRAM COLLATING SEQUENCE Clause When you include an alphabet-name in the PROGRAM COLLATING SEQUENCE clause of the OBJECT-COMPUTER paragraph, you are specifying that the associated collating sequence is to be used in nonnumeric comparisons performed throughout the program. • Alphabet-Name in COLLATING SEQUENCE Phrase When you include an alphabet-name in the COLLATING SEQUENCE phrase of a SORT or MERGE statement, you are specifying that the associated collating sequence is to be used in nonnumeric comparisons performed by that statement. • Alphabet-Name in CODE-SET Clause of a File Description Entry When you include an alphabet-name in a CODE-SET clause of a file description entry, you are specifying that the associated character set is to be used in the external representation of the data for that file. • Literal-Phrase The THROUGH phrase can specify an ascending or descending sequence of characters. THRU is equivalent to THROUGH. The compiler interprets the THROUGH phrase as an abbreviation for a consecutive series of literal phrases, each identifying the next member of a set of contiguous characters in the computer’s character set. The set begins with the character identified by literal-1 and ends with the character identified by literal-2. If the character identified by literal-1 occurs earlier in the collating sequence than the one identified by literal-2, the implied literal sequence specifies the characters in their collating order; otherwise, the implied literal sequence specifies the characters in the reverse of their collating order. The characters identified in the successive literal phrases, including any implicit literal phrases generated by the interpretation previously described, are assigned successive ascending positions in the collating sequence being defined by the ALPHABET clause. The order of position assignment corresponds directly to the order of the literal phrases. When a literal phrase includes one or more ALSO components, each character identified by a literal-3 is assigned the same position in the collating sequence as the character identified by the phrase’s literal-1. Any characters of the collating sequence that are not identified in the successive literal phrases, including any implicit literal phrases generated by the interpretations previously described, are assigned collating sequence positions greater than that of the last character that is identified. The relative order within the set of these unspecified characters is unchanged from their order in the collating sequence. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 17 Environment Division • SPECIAL-NAMES Paragraph Program Collating Sequence and Figurative Constants You can use the literal phrase of the ALPHABET clause to specify an arbitrary collating sequence for use in nonnumeric comparisons, sorting, and the intrinsic functions CHAR and ORD. For information on nonnumeric comparisons, see Arithmetic Operations. For information on sorting, see SORT. For information on the intrinsic functions CHAR and ORD, see CHAR Function and ORD Function. The character that has the highest ordinal position in the specified program collating sequence is associated with the figurative constant HIGH-VALUE. If more than one character has the highest position, the last character specified is associated with HIGH-VALUE. The character that has the lowest ordinal position in the specified program collating sequence is associated with the figurative constant LOW-VALUE. If more than one character has the lowest position, the first character specified is associated with LOW-VALUE. SYMBOLIC CHARACTERS Clause The SYMBOLIC CHARACTERS clause assigns a name to a character, which can then be referenced as a figurative constant. It is especially useful for nonprinting characters that some input interfaces cannot except, such as the end-of-text character EXT. SYMBOLIC character-list CHARACTERS VST030.vsd character-list symbolic-char IS position ARE IN alphabet-name VST031.vsd assigns the name symbolic-char to the character in position within alphabet-name, enabling you to reference the character as a figurative constant. A character-list must have equal numbers of symbolic-char and position. The first symbolic-char corresponds to the first position, and so on. symbolic-char is a user-defined COBOL word. No symbolic-char can appear more than once in the set of SYMBOLIC CHARACTERS clauses in one program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 18 Environment Division SPECIAL-NAMES Paragraph position is an unsigned integer. Its value is in the range 1 through 256 and is the ordinal position of a character in an alphabet (the first ASCII character has ordinal position 1, although it is represented by octal 00). alphabet-name is an alphabet that includes the character to which you want to assign symbol-char. The default is USASCII. This SYMBOL-CHARACTERS clause sets C-RETURN to the carriage return character, which has ordinal position 14: SYMBOLIC CHARACTERS C-RETURN IS 14 CLASS Clause The CLASS clause defines classes other than the NUMERIC, ALPHABETIC, ALPHABETIC-UPPER, and ALPHABETIC-LOWER that the COBOL language defines. CLASS class-name IS literal-phrase VST032.vsd class-name is referenced in the program as a class-condition (see Class Conditions). literal-phrase literal-1 THROUGH literal-2 THRU VST033.vsd specifies a string of characters (literal-1 ) or a range of characters (literal-1 through literal-2 ) that make up the class you are defining. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 19 Environment Division SPECIAL-NAMES Paragraph literal-1 is an unsigned integer literal or a nonnumeric literal, but not a symboliccharacter figurative constant. If literal-1 is an unsigned integer literal, its value must be in the range 1 through 256. The value is the ordinal number of a character position in the computer’s character set (the first character has ordinal number 1, even though its representation is octal 00). If literal-1 is a nonnumeric literal, its value depends on the presence or absence of literal-2. If literal-2 is present, the value of literal-1 must be exactly one character, and it can be a character that is either before or after literal-2 in the ASCII collating sequence. If literal-2 is absent, the value of literal-1 can be a string of one or more characters. The compiler handles a multicharacter string as an abbreviation for a consecutive series of literal phrases that identify each of the single characters individually, in the order they appear in literal-1. literal-2 is an unsigned integer literal or a nonnumeric literal, but not a symboliccharacter figurative constant. If literal-2 is an unsigned integer literal, its value must be in the range 1 through 256. The value is the ordinal number of a character position in the ASCII character set. If literal-2 is a nonnumeric literal, its value must be exactly one character. The compiler handles the range literal-1 through literal-2 as an abbreviation for a consecutive series of literal phrases that specify all ASCII characters from the lower ordinal position to the higher ordinal position. The two definitions in Example 6-2 are equivalent. Example 6-2. Defining a Class of Vowels CLASS VOWEL IS "A" "E" "I" "O" "U" "a" "e" "i" "o" "u" CLASS VOWEL "AEIOUaeiou" The two definitions in Example 6-3 are equivalent. Example 6-3. Defining a Class of Special Characters CLASS SPEC-CHAR IS 1 THRU 32 OCT IS "0" THRU "7" CLASS SPEC-CHAR IS 32 THRU 1 HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 20 Environment Division SPECIAL-NAMES Paragraph Example 6-4. Defining a Class of Octal Numerics OCT IS "0" THRU "7" The order of specification has no effect on the performance of the program using the definition. CURRENCY SIGN Clause The CURRENCY SIGN clause specifies a one-character nonnumeric literal, sign, whose value is to be used in the PICTURE clause to represent the currency sign. sign CURRENCY SIGN IS VST034.vsd sign is one of these characters (which must be enclosed in quotation marks): ! E [ e # F \ f $ G ] g % H ^ h & I _ i ' : < > ? @ J K L M O Q T U W Y ~ j k l m o q t u w y It represents the currency sign, and cannot be a figurative constant, a control character (ASCII position 0 through 31, or 127), the space character, or any of these characters: 0 A a * 1 B b + 2 C c - 3 D d , 4 N n . 5 P p ; 6 R r ( 7 S s ) 8 V v " 9 X Z x z , = The clause CURRENCY SIGN IS "#" makes the currency sign #, and the picture ordinarily expressed as $$$,$$9.99 is instead expressed as ###,##9.99 If sign is a lowercase alphabetic character, it appears in any source listing as lowercase, but the compiler converts it to an uppercase character for all further processing. It is uppercase in any numeric edited item produced by the associated PICTURE clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 21 Environment Division Input-Output Section DECIMAL-POINT Clause The DECIMAL-POINT clause exchanges the functions of commas and periods in PICTURE character-strings and numeric literals. DECIMAL-POINT COMMA IS VST380.vsd Input-Output Section COBOL programs typically handle large amounts of data, stored on such devices as disks and magnetic tapes. Before a program can use the stored data, the operating system file names must be linked to COBOL file names. You connect the names in filecontrol entries in the Input-Output Section. INPUT-OUTPUT SECTION . FILE-CONTROL paragraph I-O-CONTROL paragraph RECEIVE-CONTROL paragraph VST035.vsd Topics: • • • FILE-CONTROL Paragraph I-O-CONTROL Paragraph RECEIVE-CONTROL Paragraph HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 22 Environment Division FILE-CONTROL Paragraph FILE-CONTROL Paragraph If the FILE-CONTROL paragraph is present, it must be the first paragraph in the InputOutput Section. FILE-CONTROL file-control-entry . VST036.vsd file-control-entry has different syntax for sequential, line sequential, relative, indexed, queue, and sort-merge files. See the appropriate topic. Topics: • • • • • • • File-Control Entries in General File-Control Entries for Sequential Files File-Control Entries for Line Sequential Files File-Control Entries for Relative Files File-Control Entries for Indexed Files File-Control Entries for Queue Files File-Control Entries for Sort-Merge Files File-Control Entries in General The file name of every data file and every sort-merge file described in the Data Division must appear exactly once in the SELECT clause of a file-control entry. Likewise, every file name that appears in the SELECT clause of a file-control entry must also appear in a corresponding data file description entry (with a level indicator of FD) or sort-merge file description entry (with a level indicator of SD). A file-control entry connects an operating system file name to a COBOL file name, specifies the file’s organization and keys, and gives other information needed for input and output. For information about Guardian file names, see the Guardian Procedure Calls Reference Manual. For information about OSS file names, see Files in the OSS Environment. Each file-control entry consists of a SELECT clause followed by one or more clauses that specify file-related information. Every file-control entry must contain at least the SELECT clause and the ASSIGN clause. The file organization determines which of the other clauses are required or optional. No clause can appear more than once except for the ALTERNATE RECORD KEY clause, which can appear as often as needed to describe the alternate record keys of the file. Code the SELECT clause first, and then code the other clauses in any order. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 23 Environment Division FILE-CONTROL Paragraph Table 6-3. Summary of File-Control Entry Clauses File Type File-Control Entry Clause1 Sequential Line Sequential Relative Indexed Queue SortMerge SELECT2 R R R R R R ASSIGN R R R R R R RESERVE O O O O O NA ORGANIZATION O O R R R NA PADDING CHARACTER O NA NA NA NA NA RECORD DELIMITER O NA NA NA NA NA ACCESS MODE3 O O O O O NA RECORD KEY NA NA NA R R NA RELATIVE KEY NA NA O if access mode is sequential, R otherwise NA NA NA ALTERNATE RECORD KEY O NA O O NA NA FILE STATUS O O O O O NA R=Required O=Optional NA=Not Applicable 1. File-control entry clauses have the same syntax for each file type, except as noted. 2. SELECT clause syntax is the same for all file types except sort-merge. 3. ACCESS MODE clause syntax is different for all types. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 24 Environment Division FILE-CONTROL Paragraph Table 6-4. Descriptions of File-Control Entry Clauses (page 1 of 2) Clause Description SELECT Defines the file name used to refer to the file in the remainder of the source program. The OPTIONAL phrase applies only to files opened in the INPUT, I-O, or EXTEND mode. When such a file is not required to be present every time the object program unit is executed, you can designate it as optional. Every file name in a SELECT clause must also be in a file description (FD) entry or sort-merge file description (SD) entry in the Data Division. Conversely, every file name in a file description entry or sort-merge file description entry must also be in a SELECT clause. ASSIGN Associates the file name used within the program with an operating system file. The operating system file name is the one the operating system uses to refer to the file. ORGANIZATION Specifies the logical structure of a file, which was established when the file was created and which you cannot change. The default is sequential organization. RECORD DELIMITER Specifies the method of determining the length of a variable-length record on the file’s physical medium. It can appear only for a sequential file whose description specifies variable-length records. HP COBOL handles the RECORD DELIMITER clause as a comment. ACCESS Specifies the order in which a process can read records from the file. The default is sequential access. When the access mode is sequential, a process can read records from or write records to the file one after the other, in an order that depends on the file’s organization (see Table 6-5). When the access mode is random, you use key values to specify the order in which a process reads or writes records. The file-control entry specifies a data item to hold a key value (see Table 6-6). When the access mode is dynamic, records can be processed either sequentially or randomly. ALTERNATE RECORD KEY See the paragraphs after Table 6-6. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 25 Environment Division FILE-CONTROL Paragraph Table 6-4. Descriptions of File-Control Entry Clauses (page 2 of 2) Clause Description FILE STATUS The FILE STATUS clause specifies the identifier (designated in the syntax as filestat ) that is to serve as the file-status data item for the file. When a COBOL runtime I-O routine completes an operation on the file, it stores the status code in the file-status data item before returning control to your program. The identifier filestat must reference an alphanumeric data item with a size of exactly two characters. The data item must be defined in the Working-Storage Section, Extended-Storage Section, or Linkage Section of the Data Division. Table 6-5. Sequential Access File Organization Records are read by ascending alternate key or processed in the order … Sequential, Line sequential that they are written, from the first physical record to the last Relative of ascending relative record numbers Indexed of ascending record key values within a given key Table 6-6. Random Access File Organization Next record to be processed is determined by the value of … Relative RELATIVE KEY or ALTERNATE RECORD KEY data item Indexed RECORD KEY or ALTERNATE RECORD KEY data item The ALTERNATE RECORD KEY clause specifies an alternate record key (designated in the syntax as altkey ) for the file. Each altkey must reference an alphanumeric or unsigned numeric data item defined in a record description entry associated with its file name. In either case, the collating sequence is ASCII—using tricks to allow altkey to be a signed numeric data item causes problems. An altkey cannot reference an item whose size is variable. The presence or absence of the DUPLICATES phrase specifies whether or not the value of this alternate record key can be duplicated among the records in the file. If more than one record in a file has the same alternate record key value then when a program reads the file according to the alternate record key, the records are presented to the program either in either prime record key order or in the chronological order of their insertion into the file. The 1985 ISO/ANSI COBOL standard specifies insertion order, but HP COBOL provides a mechanism to enable you to choose either order. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 26 Environment Division FILE-CONTROL Paragraph Each such file has an INSERTIONORDER attribute that governs this behavior for all its alternate keys. An insertion-ordered alternate key cannot share an alternate key file with other keys of different lengths, or with other alternate keys that are not insertion ordered. The attribute can be changed only by using either a call to the operating system routine SET or by use of the File Utility Program (FUP), not by any COBOL language phrase or clause. In FUP, the BUILDKEYRECORDS and LOADALTFILE commands do not support loading of insertion-ordered alternate key records. There are size and performance penalties for using insertion-ordered duplicate alternate keys; the size of the alternate file increases and the access time increases as the number of records having duplicate alternate keys increases. For more information see the File Utility Program (FUP) Reference Manual or the Guardian Procedure Calls Reference Manual. The data description of each altkey, its relative location within the file record, and the specification of the DUPLICATES attribute must correlate with one of the alternate record keys defined when the file was created. The file-control entry can contain at most one ALTERNATE RECORD KEY clause that describes a particular alternate record key of the file. If an alternate record key is not referenced in the source program Procedure Division, then it is not necessary to describe it in the file-control entry. A maximum of 31 alternate record keys can be described for a single file. No altkey can reference an item whose leftmost character position within the file record corresponds to the leftmost character position of the item referenced by any other altkey associated with this file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 27 Environment Division FILE-CONTROL Paragraph File-Control Entries for Sequential Files HP COBOL supports two types of sequential disk files: • • A disk file created as a sequential file (also called an entry-sequenced file on NonStop systems) An unstructured disk file Also, a COBOL file defined as sequential can be assigned to a tape file, to a device such as a terminal or process, or to $RECEIVE. See OPEN and RECEIVE-CONTROL Paragraph. In HP COBOL, entry-sequenced disk files can have alternate record keys, whose values can identify individual records. A file-control entry for a sequential file includes an ORGANIZATION SEQUENTIAL clause or no ORGANIZATION clause (in which case the file has sequential organization by default). SELECT clause . ASSIGN clause RESERVE clause ORGANIZATION clause PADDING CHARACTER clause RECORD DELIMITER clause ACCESS MODE clause ALTERNATE RECORD KEY clause FILE STATUS clause VST037.vsd SELECT clause SELECT file-name OPTIONAL VST038.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 28 Environment Division FILE-CONTROL Paragraph OPTIONAL makes the file optional, which means that an OPEN statement with an INPUT, I-O, or EXTEND phrase can open the file whether or not the file exists. If the file exists, its I-O status code is “00”; if not, its I-O status code is “05”. OPTIONAL does not affect the OPEN statement with an OUTPUT phrase. When you open a nonexistent optional file for input, the first READ statement for that file uses the AT END option (or USE procedure if the READ statement has no AT END phrase). file-name is the COBOL file-name (the file-name in a file description entry). ASSIGN clause ASSIGN system-file-name TO define-name-literal VST039.vsd associates file-name with system-file-name or define-name-literal. Only the first system-file-name or define-name-literal has meaning. The compiler ignores subsequent names and literals and issues a warning. system-file-name is the name of a file that the file system recognizes or one of the special operating system file names described in System-Names. If system-filename does not begin with a dollar sign ($), backward slash (\), or number sign (#), then it must be enclosed in quotation marks unless it forms a COBOL word. For more information about operating system file names, see the Guardian Procedure Calls Reference Manual. define-name-literal is allowed only in the Guardian environment. It is a nonnumeric literal representing a DEFINE name of class MAP, SPOOL, TAPE, or TAPECATALOG. Quotation marks must enclose define-name-literal. For more information about DEFINE names, see DEFINEs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 29 Environment Division FILE-CONTROL Paragraph RESERVE clause RESERVE number AREA AREAS VST040.vsd enables or prevents sequential block buffering on input and buffered cache on output, or enables or prevents HP COBOL Fast I-O for both input and output, for a disk file, depending on the value of number. number is a numeric literal, an unsigned integer. In the non-CRE environment, number must be in the range 1 through 8, and its value is interpreted: Value of number Effect 1 No buffering or HP COBOL Fast I-O 2 or greater HP COBOL Fast I-O if the assigned file qualifies; if not, sequential block buffering for input and buffered cache for output if the assigned file qualifies; otherwise normal I-O number is the number of blocks to buffer. In the CRE, number must be in the range 1 through 32, and its value is interpreted: Value of number Effect 1 No buffering or HP COBOL Fast I-O 2 Sequential block buffering on input and buffered cache on output if the assigned file qualifies 3 or greater HP COBOL Fast I-O if the assigned file qualifies; if not, sequential block buffering for input and buffered cache for output if the assigned file qualifies; otherwise normal I-O number is the number of blocks to buffer. Caution. Do not use sequential block buffering for a file opened for shared access. If you do, a process could read data that is not up-to-date while another process alters the file. For information on shared access, see OPEN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 30 Environment Division FILE-CONTROL Paragraph ORGANIZATION clause SEQUENTIAL ORGANIZATION IS VST041.vsd makes the organization of the file sequential (the default). PADDING CHARACTER clause pad-char PADDING IS CHARACTER VST042.vsd specifies pad-char, the character to be used for padding on sequential files on unlabeled magnetic tape when the physical record size (block size) exceeds the logical record size. HP COBOL handles this phrase as a comment, except for checking if pad-char is acceptable. pad-char is either a nonnumeric literal that represents a single character, or a qualified or unqualified name that references an alphanumeric data item whose value is a single character. If pad-char is a data item, it must be defined in the Working-Storage, Extended-Storage, or Linkage Section. pad-char cannot be a national literal or national data item. RECORD DELIMITER clause RECORD DELIMITER STANDARD-1 IS rec-delim VST043.vsd specifies the method of determining the length of a variable-length record on the file’s external medium. HP COBOL handles this clause as a comment, except that these requirements are checked: ° This clause can appear only for a file whose description specifies variablelength records. ° STANDARD-1 applies only to magnetic tape files that contain standard label records. ° rec-delim must be IMPLICIT (see rec-delim, following). HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 31 Environment Division FILE-CONTROL Paragraph rec-delim must be IMPLICIT, the only name predefined by HP COBOL for use in this clause. IMPLICIT signifies that the record delimiter is implied by the size of the records on the magnetic tape. ACCESS MODE clause ACCESS SEQUENTIAL MODE IS VST044.vsd makes the access mode of the file sequential (the default). ALTERNATE RECORD KEY clause ALTERNATE RECORD IS KEY alt-key WITH DUPLICATES VST045.vsd makes alt-key an alternate record key. alt-key is an alphanumeric or unsigned numeric data item declared in the record description entry of the file and is used to gain access to records within the file. The size and location of alt-key must agree with the size and location of the alternate key within the file, as defined when the alternate key file was established by the Guardian environment File Utility Program (FUP). (For information about FUP, see the File Utility Program (FUP) Reference Manual.) DUPLICATES means that alternate key values are not necessarily unique. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 32 Environment Division FILE-CONTROL Paragraph FILE STATUS clause filestat STATUS FILE IS VST046.vsd defines filestat as the file-status data item for the file. When a COBOL runtime IO routine completes an operation on the file, it stores the status code in filestat before returning control to your program (see I-O Status Code). filestat is a 2-character alphanumeric, nonnational data item defined in the WorkingStorage Section, Extended-Storage Section, or Linkage Section. Usage Considerations: • EDIT Files A file assigned to an EDIT file can be open for output only if it has the file code 101. It can be given the file code 101 by any of: ° ° The application that created it outside the COBOL program ° The COBOL_ASSIGN_ routine An ASSIGN command that was active during run unit initialization (the ASSIGN command must have a CODE phrase) The buffer size of an EDIT file created in the CRE is determined: 1. If an ASSIGN command includes the BLOCK parameter, that value is the buffer size. (ASSIGN commands are allowed only in the Guardian environment.) 2. If Step 1 is not true and the file description entry for the EDIT file includes a BLOCK CONTAINS clause, then that value is the buffer size. 3. If Step 2 is not true, the buffer size is 4,096. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 33 Environment Division • FILE-CONTROL Paragraph Alternate Record Keys Records in a file can be read in the ascending order of alternate key values, even if the file’s organization is sequential or relative. The order in which records are obtained using alt-key can differ from the order in which the records are stored. You can define up to 31 alternate keys for a file. If you include the DUPLICATES phrase in the ALTERNATE RECORD KEY clause, the value of alt-key need not be unique for each record in the file. Depending on the INSERTIONORDER parameter of the alternate key file, records with duplicate alternate key values are inserted (or retrieved) in either prime key order (the way NonStop systems software ordinarily works) or in the order in which they were inserted in the file (as specified in the 1985 ISO/ANSI COBOL standard). The data description entry for alt-key cannot contain an OCCURS clause or be subordinate to an entry that contains an OCCURS clause. The leftmost character position of an alt-key item cannot correspond to the leftmost character position of another alt-key item in that file. The file-control entry can contain at most one ALTERNATE RECORD KEY clause that describes a particular alternate record key of the file. If a file in the file system is defined as having alternate record keys to which the COBOL program does not make any reference, you do not need to specify them in the File-Control paragraph. An alt-key is permitted only for structured disk files and not for unstructured disk files or files that are not disk files. A file having a LINAGE clause in its file description cannot be a disk file (although it can be spooled to a printer by way of a disk). It is, therefore, never legal to define a file with an ALTERNATE RECORD KEY clause and have a LINAGE clause in the file description entry for that file. • Sequential Block Buffering Sequential block buffering, enabled by the RESERVE clause when the file is open in INPUT or I-O mode, is a feature of the Enscribe database record manager that enables faster reading of a sequentially structured file by reading a block of records together into a memory buffer. The file’s access must be sequential, but its organization can be sequential, relative, or indexed. A program requests sequential block buffering (or does not request it) when it opens the file. Each process that opens the file requests or does not request sequential block buffering. One process can request it while another process does not. Nothing stored on the disk keeps a record of whether the file is to be read with sequential block buffering. The RESERVE clause acts as a switch. In the CRE, the number 2 means to use sequential block buffering on input (and buffered cache on output) if the assigned file qualifies. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 34 Environment Division FILE-CONTROL Paragraph Enscribe determines the size of the sequential block buffer. Usually, the buffer size is the file’s data block size, but when a process accesses a file by alternate keys, the buffer size is the alternate key file’s data block size. You can obtain the data block size for the appropriate file with the FUP command: FUP INFO file-name,DETAIL The size is usually 1,024 characters. The size of the buffer space used for reading is 4* dbs, where dbs is the file’s data block size. The BLOCK CONTAINS clause, if specified, is ignored. Because double buffering is used, the size of the block read is half the size of the buffer. The maximum size of blocks read is 32,768 characters. If the process cannot perform sequential block buffering for any reason, it performs normal input-output. The file status code is “07”. Note. With the advent of the DP2 disk processing system, normal I/O could be faster than sequential block buffering, depending on the number of records per block. For example, a file containing eight 4K blocks and 1600 records requires one physical I/O operation and 1600 interprocess messages in normal mode, but eight physical I/O operations and only eight interprocess messages in SBB mode; on the other hand, a file with eight 4K blocks and only eight records requires one physical I/O and eight interprocess messages in normal mode, but eight physical I/O operations and eight interprocess messages in SBB mode • Buffered Cache Buffered cache is a feature of the DP2 disk process that uses more efficient disk I-O to write disk files. The RESERVE clause acts as a switch. In the CRE, the number 2 means to use buffered cache on output (and sequential block buffering on input) if the assigned file qualifies. The file must be open in the OUTPUT, I-O, or EXTEND mode. The size of the buffer space used for writing is 29K characters, regardless of the number in the RESERVE clause. This technique buffers records in cache rather than writing them immediately to disk, thereby reducing the number of requests to the disk process. Audited files always use buffered cache; nonaudited files can use buffered cache or writethrough cache under DP2. Write-through cache transfers each record to the disk as it is written. You can use the File Utility Program (FUP) commands SET and ALTER to set the BUFFERED attribute for a file, specifying that any programs that open that file must use buffered cache. If a file has the BUFFERED attribute set, a process can still override the attribute by calling the Guardian routine SETMODE to specify that buffered cache must not be used, but the run-time routines do not do this. If a COBOL program specifies RESERVE 1 AREA for a file that already has the BUFFERED attribute set, the disk process still uses buffered cache. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 35 Environment Division FILE-CONTROL Paragraph You must not use buffered cache in applications that require each record to be actually written to disk before execution of the next statement in the program. • HP COBOL Fast I-O (Local Buffering) HP COBOL Fast I-O is an enhancement in input-output performance beyond that of sequential block buffering or buffered cache. It is available if a program and the sequential file on which it is to operate meet these criteria: ° ° You are not creating an audited file (you can read an audited file, however). ° ° The file description does not include a LINAGE clause or a CODE-SET clause. ° The file’s open mode is either INPUT or OUTPUT. If it is INPUT, its exclusion mode is PROTECTED; if it is OUTPUT, its exclusion mode is EXCLUSIVE. ° ° The program is not compiled with the NONSTOP directive. The file description includes a RESERVE clause with a number specifying the number of blocks to buffer. In the non-CRE environment, the number must be greater than 1; in the CRE, it must be greater than 2. The file is not opened with time limits (as with the TIME LIMITS phrase in the OPEN statement). Regarding fast I-O and alternate keys, you must adhere to these rules: ° If the program is compiled with ENV OLD, there must be no alternate keys either in the SELECT statement or in the file itself. ° If the program is compiled with ENV COMMON, there must be no alternate keys mentioned in the SELECT statement. Any alternate keys that exist in the file must be set to NO UPDATE with FUP. With HP COBOL Fast I-O, the run-time routines use an auxiliary block buffer and perform the blocking and deblocking in local storage. This can operate as much as ten times faster than having the operating system perform the blocking and deblocking operations. The size of the buffer space used for reading is 2 * number *dbs, where dbs is the file’s data block size. The BLOCK CONTAINS clause, if specified, is ignored. Because double buffering is used, the size of the block read is half the size of the buffer. The maximum size of blocks read is 32,768 characters. You can obtain the data block size for the appropriate file with the FUP command: FUP INFO file-name, DETAIL The size is usually 1,024 characters. The size of the buffer space used for writing is 29K characters, regardless of the number in the RESERVE clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 36 Environment Division FILE-CONTROL Paragraph If the RESERVE clause specifies a number that uses HP COBOL Fast I-O and the assigned file qualifies for HP COBOL Fast I-O, but there is not enough buffer space for HP COBOL Fast I-O, then the I-O status code is “07” and sequential block buffering is used. If you run out of disk space, the corrupt bit is set, the program terminates abnormally, and you cannot open the file. If the file is entry-sequenced, use FUP to clear the corrupt bit. If the file is not entry-sequenced, the file is unusable. An auxiliary block buffer can be shared by two files in a program as long as both are not open at the same time. The space is allocated as part of the open operation and deallocated as part of the close operation. The SAME AREA clause has no effect on space allocation or deallocation. Example 6-5 contains two simple sequential files: ° An input file that the COBOL program recognizes as MASTER1-IN and to the operating system as NAMEFILE in a subvolume name SUB1 on a disk drive named $BULK. ° An output file that the COBOL program recognizes as REPORT-OUT and to the Guardian environment as a DEFINE named =ROSTER-PRINTER. Example 6-5. FILE-CONTROL Paragraph for Sequential File INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT MASTER1-IN ASSIGN TO "$BULK.SUB1.NAMEFILE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. SELECT REPORT-OUT ASSIGN TO "=ROSTER-PRINTER" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. ... DATA DIVISION. FILE SECTION. FD MASTER1-IN LABEL RECORDS ARE OMITTED. ... FD REPORT-OUT LABEL RECORDS ARE OMITTED. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 37 Environment Division FILE-CONTROL Paragraph File-Control Entries for Line Sequential Files Line sequential files are available only in the OSS environment. SELECT clause ASSIGN clause . RESERVE clause ORGANIZATION clause ACCESS MODE clause FILE STATUS clause VST624.vsd SELECT clause SELECT file-name OPTIONAL VST038.vsd OPTIONAL makes the file optional, which means that an OPEN statement with an INPUT, I-O, or EXTEND phrase can open the file whether or not the file exists. If the file exists, its I-O status code is “00”; if not, its I-O status code is “05”. OPTIONAL does not affect the OPEN statement with an OUTPUT phrase. When you open a nonexistent optional file for input, the first READ statement for that file uses the AT END option (or USE procedure if the READ statement has no AT END phrase). file-name is the COBOL file-name (the file-name in a file description entry). HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 38 Environment Division FILE-CONTROL Paragraph ASSIGN clause ASSIGN system-file-name TO VST640.vsd associates file-name with system-file-name. Only the first system-filename has meaning. The compiler ignores subsequent names and issues a warning. system-file-name is the name of a code-180 file that the file system recognizes or one of the special operating system file names described in System-Names. If systemfile-name does not begin with a dollar sign ($), backward slash (\), or number sign (#), then it must be enclosed in quotation marks unless it forms a COBOL word. For more information about Guardian file names, see the Guardian Procedure Calls Reference Manual. For more information about OSS file names, see the filename(5) reference page either online or in the Open System Services System Calls Reference Manual. RESERVE clause is ignored. ORGANIZATION clause LINE ORGANIZATION SEQUENTIAL IS VST625.vsd makes the organization of the file line sequential. ACCESS MODE clause ACCESS SEQUENTIAL MODE IS VST044.vsd makes the access mode of the file sequential (the default). HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 39 Environment Division FILE-CONTROL Paragraph FILE STATUS clause filestat STATUS FILE IS VST046.vsd defines filestat as the file-status data item for the file. When a COBOL runtime I-O routine completes an operation on the file, it stores the status code in filestat before returning control to your program (see I-O Status Code). filestat is a 2-character alphanumeric, nonnational data item defined in the WorkingStorage Section, Extended-Storage Section, or Linkage Section. File-Control Entries for Relative Files Relative organization provides the capability to read records from or write records to a disk file either randomly or sequentially. For each record in a relative file, a positive integer value that specifies the record’s logical ordinal position in the file uniquely identifies the record. In HP COBOL you can also use alternate alphanumeric or unsigned numeric keys (with possible duplicate values) within each record. A relative file has a fixed maximum record length, but the records can be of various lengths up to that maximum. A file-control entry for a relative file includes an ORGANIZATION RELATIVE clause. SELECT clause ASSIGN clause . RESERVE clause ORGANIZATION clause ACCESS MODE clause ALTERNATE RECORD KEY clause FILE STATUS clause VST047.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 40 Environment Division FILE-CONTROL Paragraph SELECT clause SELECT file-name OPTIONAL VST038.vsd OPTIONAL makes the file optional, which means that an OPEN statement with an INPUT, I-O, or EXTEND phrase can open the file whether or not the file exists. If the file exists, its I-O status code is “00”; if not, its I-O status code is “05”. OPTIONAL does not affect the OPEN statement with an OUTPUT phrase. When you open a nonexistent optional file for input, the first READ statement for that file uses the AT END option (or USE procedure if the READ statement has no AT END phrase). file-name is the COBOL file-name (the file-name in a file description entry). ASSIGN clause ASSIGN system-file-name TO define-name-literal VST039.vsd associates file-name with system-file-name or define-name-literal. Only the first system-file-name or define-name-literal has meaning. The compiler ignores subsequent names and literals and issues a warning. system-file-name is either the name of a disk file or the special file name #DYNAMIC or #TEMP. Quotation marks must enclose system-file-name unless it is a COBOL word or begins with a dollar sign ($), a backward slash (\), or a number sign (#). For more information about operating system file names, see the Guardian Procedure Calls Reference Manual. define-name-literal is a nonnumeric literal. It represents the name of a DEFINE of class MAP that is associated with a disk file. Quotation marks must enclose define-nameliteral. For information on DEFINE names, see DEFINEs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 41 Environment Division FILE-CONTROL Paragraph RESERVE clause RESERVE number AREA AREAS VST040.vsd enables or prevents sequential block buffering on input and buffered cache on output, or enables or prevents HP COBOL Fast I-O for both input and output, for a disk file, depending on the value of number. The access mode of the file must be SEQUENTIAL. number is a numeric literal, an unsigned integer. In the non-CRE environment, number must be in the range 1 through 8, and its value is interpreted: Value of number Effect 1 No buffering or HP COBOL Fast I-O 2 or greater Sequential block buffering for input and buffered cache for output if the assigned file qualifies number is the number of blocks to buffer. In the CRE, number must be in the range 1 through 32, and its value is interpreted: Value of number Effect 1 No buffering or HP COBOL Fast I-O. 2 Sequential block buffering on input and buffered cache on output if the assigned file qualifies. 3 or greater HP COBOL Fast I-O if the assigned file qualifies; if not, sequential block buffering for input and buffered cache for output if the assigned file qualifies; otherwise normal I-O number is the number of blocks to buffer. Caution. Do not use sequential block buffering for a file opened for shared access. If you do, a process could read outdated data while another process alters the file. For information on shared access, see OPEN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 42 Environment Division FILE-CONTROL Paragraph ORGANIZATION clause RELATIVE ORGANIZATION IS VST048.vsd makes the organization of the file relative. (The default is sequential.) ACCESS MODE clause ACCESS MODE IS SEQUENTIAL RANDOM RELATIVE KEY clause DYNAMIC VST049.vsd SEQUENTIAL makes the access mode of the file sequential (the default). That means the records of the file are to be operated upon as if they were sequentially organized. RANDOM makes the access mode of the file random. That means the records of the file are to be operated upon in any order, as selected by the current value of the relative key or an alternate key. DYNAMIC makes the access mode of the file dynamic. That means the records of the file are accessible by either sequential or random access; you can position the file to a certain key value with START and read or write sequentially from there. RELATIVE KEY clause rel-key RELATIVE KEY IS VST050.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 43 Environment Division FILE-CONTROL Paragraph rel-key is an integer data item to be used as a prime key to specify records within the file. It must be large enough to hold the maximum record number. Its definition cannot be in a record description entry for that file. It can be in another record description entry or in the Working-Storage Section, Extended-Storage Section, or Linkage Section. ALTERNATE RECORD KEY clause ALTERNATE RECORD IS KEY alt-key WITH DUPLICATES VST045.vsd alt-key is an alphanumeric or unsigned numeric data item declared in the record description entry of the file. It is used to access records within the file. Its size and location must agree with the size and location of the alternate key within the file, defined when the alternate key file was established by the Guardian environment File Utility Program (FUP). (For information about FUP, see the File Utility Program (FUP) Reference Manual.) DUPLICATES means that alternate key values are not necessarily unique. FILE STATUS clause filestat STATUS FILE IS VST046.vsd defines filestat as the file-status data item for the file. When a COBOL runtime IO routine completes an operation on the file, it stores the status code in filestat before returning control to your program (see I-O Status Code). filestat is a 2-character alphanumeric, nonnational data item defined in the WorkingStorage Section, Extended-Storage Section, or Linkage Section. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 44 Environment Division FILE-CONTROL Paragraph Usage Considerations: • Relative Key Every record in a relative file is uniquely identified by a positive integer called the relative record number. Each record’s number defines its logical position in the file. The first logical record has a relative number of 1, the second logical record has a relative number of 2, and so on. A file is not required to contain records in every logical position; record 3 can exist even when record 2 is missing. Note. COBOL record numbers begin at 1. This is different from the Guardian file-system convention of beginning record numbers at 0. The COBOL run-time I-O routines deduct 1 from the COBOL relative record number to obtain the Guardian file-system record number. When a COBOL program requests record 1, it receives the first record in the file—the record that the Guardian file system designates 0. Remember this difference if other HP products are to operate on a file. • Alternate Record Keys The records within the file can be accessed in ascending order of the alt-key value. The order in which records are obtained using alt-key can differ from the order obtained using rel-key. You can define up to 31 alternate keys for a file. If you include the DUPLICATES phrase in the ALTERNATE RECORD KEY clause, the value of alt-key need not be unique for each record in the file. Depending on the INSERTIONORDER parameter of the alternate key file, records with duplicate alternate key values are inserted (or retrieved) in either prime key order or in the order in which they were inserted in the file. The data description entry for alt-key cannot contain an OCCURS clause or be subordinate to an entry that contains an OCCURS clause. The leftmost character position of an alt-key item cannot correspond to the leftmost character position of another alt-key item in that file. The file-control entry can contain at most one ALTERNATE RECORD KEY clause that describes a particular alternate record key of the file. If a file in the file system is defined as having alternate record keys to which the COBOL program does not make any reference, you do not need to specify them in the File-Control paragraph. • Sequential Block Buffering Sequential block buffering, enabled by the RESERVE clause when the file is open in INPUT or I-O mode, is discussed under File-Control Entries for Sequential Files. • Buffered Cache Buffered cache, enabled by the RESERVE clause when the file is open in OUTPUT, I-O, or EXTEND mode, is discussed under File-Control Entries for Sequential Files. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 45 Environment Division • FILE-CONTROL Paragraph HP COBOL Fast I-O (Local Buffering) HP COBOL Fast I-O is an enhancement in input-output performance beyond that of sequential block buffering or buffered cache. It is available if a program and the relative file upon which it is to operate are in the CRE and meet the criteria under File-Control Entries for Sequential Files. Example 6-6. Relative File Used for Random Access INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT INPUT-FILE ASSIGN TO "$DATA.MYDISC.INPUT" ORGANIZATION IS RELATIVE ACCESS MODE IS RANDOM RELATIVE KEY IS INP-RELKEY FILE STATUS IS INP-STATUS. ... DATA DIVISION. FILE SECTION. FD INPUT-FILE LABEL RECORDS ARE OMITTED. 01 INPUT-REC. ... WORKING-STORAGE SECTION. 01 STATUSES. 03 INP-STATUS PICTURE XX VALUE SPACES. ... 01 KEYS. 03 INP-RELKEY USAGE NATIVE-4. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 46 Environment Division FILE-CONTROL Paragraph File-Control Entries for Indexed Files Indexed organization provides the capability to read records from and write records to a disk file either randomly or sequentially. In an indexed file, the value of the prime key of each record uniquely identifies that record. A file-control entry for an indexed file includes an ORGANIZATION INDEXED clause. SELECT clause ASSIGN clause RESERVE clause ORGANIZATION clause ACCESS MODE clause . RECORD KEY clause ALTERNATE RECORD KEY clause FILE STATUS clause VST051.vsd SELECT clause SELECT file-name OPTIONAL VST038.vsd OPTIONAL makes the file optional, which means that an OPEN statement with an INPUT, I-O, or EXTEND phrase can open the file whether or not the file exists. If the file exists, its I-O status code is “00”; if not, its I-O status code is “05”. OPTIONAL does not affect the OPEN statement with an OUTPUT phrase. When you open a nonexistent optional file for input, the first READ statement for that file uses the AT END option (or USE procedure if the READ statement has no AT END phrase). HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 47 Environment Division FILE-CONTROL Paragraph file-name is the COBOL file-name (the file-name in a file description entry). ASSIGN clause ASSIGN system-file-name define-name-literal TO VST039.vsd associates file-name with a file designated by system-file-name, or define-name-literal. Only the first system-file-name or define-nameliteral has meaning. The compiler ignores subsequent names and literals and issues a warning. system-file-name is the name of a disk file or either of the special operating system file names #DYNAMIC or #TEMP, described in System-Names. system-file-name must be enclosed in quotation marks unless it begins with a dollar sign ($), a backward slash (\), or a number sign (#), or is a COBOL word. If systemfile-name is #TEMP, the file cannot have alternate keys. For more information about operating system file names, see the Guardian Procedure Calls Reference Manual. define-name-literal is a nonnumeric literal that represents the name of a DEFINE of class MAP that is associated with a disk file. Quotation marks must enclose any DEFINE name. For information about DEFINE names, see DEFINEs. RESERVE clause RESERVE number AREA AREAS VST040.vsd enables or prevents sequential block buffering on input and buffered cache on output, or enables or prevents HP COBOL Fast I-O for both input and output, for a disk file, depending on the value of number. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 48 Environment Division FILE-CONTROL Paragraph number is a numeric literal, an unsigned integer. In the non-CRE environment, number must be in the range 1 through 8, and its value is interpreted: Value of number Effect 1 No buffering or HP COBOL Fast I-O 2 or greater Sequential block buffering for input and buffered cache for output if the assigned file qualifies number is the number of blocks to buffer. In the CRE, number must be in the range 1 through 32, and its value is interpreted: Value of number Effect 1 No buffering or HP COBOL Fast I-O 2 Sequential block buffering on input and buffered cache on output if the assigned file qualifies 3 or greater HP COBOL Fast I-O if the assigned file qualifies; if not, sequential block buffering for input and buffered cache for output if the assigned file qualifies; otherwise normal I-O number is the number of blocks to buffer. Caution. Do not use sequential block buffering for a file opened for shared access. If you do, a process could read outdated data while another process alters the file. For information on shared access, see OPEN. ORGANIZATION clause INDEXED ORGANIZATION IS VST052.vsd makes the organization of the file indexed (the default is sequential). ACCESS MODE clause ACCESS SEQUENTIAL MODE IS RANDOM DYNAMIC VST053.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 49 Environment Division FILE-CONTROL Paragraph SEQUENTIAL makes the access mode of the file sequential (the default). That means the records of the file are to be operated upon as if they were sequentially organized. RANDOM makes the access mode of the file random. That means the records of the file are to be operated upon in any order, as selected by the current value of the record key or of an alternate key. The default access mode is sequential. DYNAMIC makes the access mode of the file dynamic. That means the records of the file are accessible by either sequential or random access; you can position the file with START to a certain key value and read or write sequentially from there. The default access mode is sequential. RECORD KEY clause RECORD reckey KEY IS VST054.vsd rec-key is an alphanumeric or unsigned numeric data item defined in the record description entry for the file. It is the prime key for accessing records within the file. If the file was created with FUP or CREATE, the reckey size and location must agree with the size and location of the prime key established by FUP or CREATE. All records in the file are ranked in ascending order of the reckey value, which must be unique for each record. ALTERNATE RECORD KEY clause ALTERNATE RECORD IS KEY alt-key WITH DUPLICATES VST045.vsd makes alt-key an alternate record key. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 50 Environment Division FILE-CONTROL Paragraph alt-key is an alphanumeric or unsigned numeric data item declared in the record description entry of the file and is used to gain access to records within the file. The alt-key size and location must agree with the size and location of the alternate key within the file, as defined when the alternate key file was established by the operating system File Utility Program (FUP). (For information about FUP, see the File Utility Program (FUP) Reference Manual.) DUPLICATES means that alternate key values are not necessarily unique. FILE STATUS clause filestat STATUS FILE IS VST046.vsd defines filestat as the file-status data item for the file. When a COBOL runtime I-O routine completes an operation on the file, it stores the status code in filestat before returning control to your program (see I-O Status Code). filestat is a 2-character alphanumeric, nonnational data item defined in the WorkingStorage Section, Extended-Storage Section, or Linkage Section. Usage Considerations: • Record Key The data description entry for reckey cannot contain an OCCURS clause. • Alternate Record Keys The records within the file can be accessed in ascending order of the alt-key value. The order in which records are obtained using alt-key can differ from the order obtained using reckey. You can define up to 31 alternate keys for a file. If you include the DUPLICATES phrase in the ALTERNATE RECORD KEY clause, the value of alt-key need not be unique for each record in the file. Depending on the INSERTIONORDER parameter of the alternate key file, records with duplicate alternate key values are inserted (or retrieved) in either prime key order or in the order in which they were inserted in the file. The data description entry for alt-key cannot contain an OCCURS clause or be subordinate to an entry that contains an OCCURS clause. The leftmost character position of an alt-key item cannot correspond to the leftmost character position of the reckey item or another alt-key item in that file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 51 Environment Division FILE-CONTROL Paragraph The file-control entry can contain at most one ALTERNATE RECORD KEY clause that describes a particular alternate record key of the file. If a file in the file system is defined as having alternate record keys to which the COBOL program does not make any reference, you do not need to specify them in the File-Control paragraph. • Sequential Block Buffering Sequential block buffering, enabled by the RESERVE clause when the file is open in INPUT or I-O mode, is discussed under File-Control Entries for Sequential Files. • Buffered Cache Buffered cache, enabled by the RESERVE clause when the file is open in OUTPUT, I-O, or EXTEND mode, is discussed under File-Control Entries for Sequential Files. • HP COBOL Fast I-O (Local Buffering) HP COBOLFast I-O is an enhancement in input-output performance beyond that of sequential block buffering or buffered cache. It is available if: • ° Either the program runs in the non-CRE environment and the file is organized sequentially, or the program runs in the CRE (in which case the file can have any organization). ° The files upon which HP COBOLFast I-O is to operate meet the criteria under File-Control Entries for Sequential Files. Performance Penalty for Poorly Organized Indexed File If a large number of entries have been added to and/or deleted from an indexed file, accessing its records in sequence requires a significant amount of random processing; therefore, performance suffers. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 52 Environment Division FILE-CONTROL Paragraph Example 6-7. Indexed File With One Alternate Key INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT RECEIVABLES-MASTER ASSIGN TO "=RECMAST" ORGANIZATION IS INDEXED RECORD KEY IS INVOICE-NUMBER ALTERNATE RECORD KEY IS COMPANY-NAME WITH DUPLICATES, FILE STATUS IS IO-STATUS. ... DATA DIVISION. FILE SECTION. FD RECEIVABLES-MASTER LABEL RECORDS ARE OMITTED RECORD CONTAINS 39 CHARACTERS. 01 INVOICE-RECORD. 05 INVOICE-NUMBER PICTURE 9(7). 05 COMPANY-NAME PICTURE X(15). 05 INVOICE-DATE PICTURE 9(6). 05 INVOICE-AMOUNT PICTURE S9(9)V99. ... WORKING-STORAGE SECTION. 01 STATUSES. 03 IO-STATUS PICTURE XX VALUE SPACES. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 53 Environment Division FILE-CONTROL Paragraph File-Control Entries for Queue Files A queue file is an indexed file that can function as a queue. Unlike an ordinary index file, a queue file cannot have alternate keys. SELECT clause ASSIGN clause RESERVE clause ORGANIZATION clause ACCESS MODE clause RECORD KEY clause . FILE STATUS clause VST740.vsd For descriptions of clauses and usage considerations, see File-Control Entries for Indexed Files. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 54 Environment Division FILE-CONTROL Paragraph File-Control Entries for Sort-Merge Files A file-control entry for a sort-merge file defines a scratch file for a sort-merge process. SELECT clause ASSIGN clause . VST055.vsd SELECT clause SELECT sd-name VST056.vsd sd-name is a COBOL file-name (the file-name in a sort-merge file description entry). ASSIGN clause ASSIGN system-file-name TO define-name-literal VST039.vsd associates the COBOL file-name (sd-name ) with a file designated by systemfile-name, or define-name-literal. Only the first system-file-name or define-name-literal has meaning. The compiler ignores subsequent ones and issues a warning. system-file-name is the name of a disk file that the file system recognizes. Quotation marks must enclose system-file-name unless it is a COBOL word or begins with a dollar sign ($), backward slash (\), or number sign (#). For more information about operating system file names, see the Guardian Procedure Calls Reference Manual. define-name-literal is a nonnumeric literal representing a DEFINE name of type MAP. Quotation marks must enclose define-name-literal. For more information about DEFINE names, see DEFINEs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 55 Environment Division FILE-CONTROL Paragraph Usage Considerations: • Different Devices for Files The sort-merge file is a temporary file used by a SORT or MERGE statement. Programs that define their sort-merge file on a different device than the input or output file of the SORT or MERGE statement must run more efficiently than those defining input or output files on the same device as the sort-merge file. • Redirecting the Swap File The operating system assigns a swap file to swap pages in and out of memory while the compiler is running. The swap file mirrors all of the data areas that the compiler uses. The ideal swap file is a fast device that is neither busy nor mirrored. To redirect the swap file, give define-name-literal the value =_SORT_DEFAULTS. In Example 6-8, a file-control entry assigns a sort file to a temporary file on the default volume established at run time. Example 6-8. File-Control Entry for Sort-Merge File INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT SORT-FILE ASSIGN TO "#TEMP". ... DATA DIVISION. FILE SECTION. SD SORT-FILE RECORD CONTAINS 40 CHARACTERS. 01 SORT-FIELDS. ... If you want the temporary file on a different volume than the default, do not use #TEMP. The phrase ASSIGN TO "$FLAG" assigns a temporary file on $FLAG, regardless of the current default volume. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 56 Environment Division I-O-CONTROL Paragraph I-O-CONTROL Paragraph The optional I-O-CONTROL paragraph specifies positioning information for a tape file or the sharing of a memory area by more than one file. If the I-O-CONTROL paragraph is present, it must follow the FILE-CONTROL paragraph, because it refers to files established by file-control entries. Sequential, relative, or indexed file: I-O-CONTROL . «RERUN clause» . SAME AREA clause «MULTIPLE FILE clause» VST057.vsd Line sequential file: I-O-CONTROL . «RERUN clause» . SAME AREA clause VST632.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 57 Environment Division I-O-CONTROL Paragraph RERUN clause Note. The 1985 COBOL standard classifies the RERUN clause as obsolete, so you are advised not to use it. RERUN rerun-file ON system-name EVERY rerun-file-2-phrase units CLOCK-UNITS condition VST058.vsd rerun-file system-name units condition are handled as comments. rerun-file-2-phrase recs RECORDS REEL END OF OF UNIT rerun-file-2 VST059.vsd is handled as a comment. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 58 Environment Division I-O-CONTROL Paragraph SAME AREA clause SAME RECORD SORT AREA FOR MERGE same-file VST060.vsd specifies the files that share the same memory during program execution. These files do not share disk space or tape space. The SAME AREA clause has different meanings for I-O files (sequential, relative, indexed) than for sort-merge files. same-file is a file-name. MULTIPLE FILE clause Note. The 1985 COBOL standard classifies the MULTIPLE FILE clause as obsolete, so you are advised not to use it. MULTIPLE FILE TAPE CONTAINS tape-file POSITION position VST061.vsd specifies a multiple-file tape reel. For more information on multiple files, see MULTIPLE FILE Clause. tape-file is the name of a sequential file on magnetic tape, defined in a file-control entry and a file description entry. position is a numeric literal with a value of 1 or more. It defines the relative position of tape-file on a tape. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 59 Environment Division I-O-CONTROL Paragraph SAME AREA Clause for I-O Files The SAME AREA clause advises the compiler that two or more files that are not sortmerge files can use the same memory area during processing. Only one of these files can be open at any given time. SAME RECORD AREA FOR same-file VST062.vsd RECORD specifies that two or more files are to use the same memory area for processing the current logical record. same-file is the sd-name in the sort-merge file description entry or the fd-name in the file description entry for the file. The compiler ignores the advice provided by the SAME AREA clause. For information on one way files can share memory, see the HP COBOL Fast I-O (Local Buffering). The SAME RECORD AREA clause specifies that two or more files use the same memory area for processing the current logical record. Ordinarily, all the files can be open at the same time, but see the restrictions on the usage of SAME clauses. A logical record in the SAME RECORD AREA is considered a logical record of each opened output file whose file name appears in this SAME RECORD AREA clause and of the most recently read input file whose file name appears in this SAME RECORD AREA clause. This is equivalent to a redefinition of the area—records are aligned on the leftmost character position. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 60 Environment Division I-O-CONTROL Paragraph More than one SAME clause can be included in a program; however, there are some restrictions on the usage of SAME clauses: • • A file name must not appear in more than one SAME AREA clause or in more than one SAME RECORD AREA clause. If any file names of a SAME AREA clause appear in a SAME RECORD AREA clause, all of the file names in that SAME AREA clause must appear in the SAME RECORD AREA clause; however, additional file names not appearing in that SAME AREA clause can also appear in that SAME RECORD AREA clause. The rule that only one of the files mentioned in a SAME AREA clause can be open at any given time takes precedence over the rule that all files mentioned in a SAME RECORD AREA clause can be open at any given time. The files mentioned in the SAME AREA or SAME RECORD AREA clause can differ in organization or access. SAME AREA Clause for Sort-Merge Files The SAME AREA clause of the I-O-CONTROL paragraph can also specify sort-merge files. HP COBOL ignores the advice provided to the compiler by the SAME AREA clause. The file system automatically allocates and manages all memory areas needed for file processing and for sort or merge operations. SAME RECORD SORT AREA FOR MERGE same-file VST060.vsd RECORD specifies that two or more files are to use the same memory area for processing the current logical record. SORT is ignored by the compiler, but SORT specifies that the compiler can use (and reuse) the same memory area to sort or merge each sort or merge file specified by same-file. If SORT is specified, at least one same-file must be a sort file. MERGE is equivalent to SORT in the SAME AREA clause. If MERGE is specified, at least one same-file must be a merge file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 61 Environment Division I-O-CONTROL Paragraph same-file is the sd-name in the sort-merge file description entry or the fd-name in the file description entry for the file. Usage Considerations: • File Organization and Access Modes The files specified in the SAME AREA clause can have different types of organization or different access modes. • SAME SORT AREA or SAME MERGE AREA Clause If the SAME SORT AREA or SAME MERGE AREA clause is used, at least one same-file must be a sort or merge file. Files that are not sort or merge files can also be named. You can include more than one SAME AREA clause in a program; however, if a file name that is not a sort or merge file appears in a SAME AREA clause and one or more SAME SORT AREA or SAME MERGE AREA clauses, then all of the files named in that SAME AREA clause must also be named in each of the affected SAME SORT AREA or SAME MERGE AREA clauses. This clause specifies that storage be shared: • ° The SAME SORT AREA and SAME MERGE AREA clauses advise the compiler that the same memory area can be used in sorting or merging each sort or merge file named and that any memory area used for sorting or merging a sort-merge file can be reused in sorting or merging any other sort-merge files. The compiler ignores the advice provided by this clause. ° Storage areas assigned to files that do not represent sort or merge files can be allocated as needed for sorting or merging the sort-merge files named in the SAME SORT AREA or SAME MERGE AREA clause. ° Files other than sort-merge files do not share the same storage area with each other. If you want these files to share the same storage area, you must also include a SAME AREA or SAME RECORD AREA clause naming the files. ° During the execution of a SORT or MERGE statement referring to a sort or merge file named in this clause, any file named in this clause that is not a sort or merge file must not be open. SAME RECORD AREA Clause The SAME RECORD AREA clause specifies that two or more files are to use the same memory area for processing the current logical record. All of the files can be open at the same time. A logical record in the SAME RECORD AREA is considered a logical record of each opened output file whose file name appears in this SAME RECORD AREA clause. This is equivalent to implicit redefinition of the area—records are aligned on the leftmost character position. A file name must not appear in more than one SAME RECORD AREA clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 62 Environment Division I-O-CONTROL Paragraph MULTIPLE FILE Clause Note. The 1985 COBOL standard classifies the MULTIPLE FILE clause as obsolete, so you are advised not to use it. MULTIPLE FILE TAPE CONTAINS tape-file POSITION position VST061.vsd tape-file is the file name of a file on the tape that the program uses. Regardless of the number of files on a single reel, only files that the program uses need to be defined; however, if any file in the set is not listed, or if the files are not listed in the order they occur on the tape, then each file’s position relative to the beginning of the tape must be specified. POSITION is unnecessary when you list all the files on the tape in physical order; otherwise, it is required. position is an integer data item whose value is the ordinal number of a file on the tape. The first file on the tape has position 1; the second, position 2; and so on. For information on multiple-tape format, see the Guardian Programmer’s Guide. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 63 Environment Division RECEIVE-CONTROL Paragraph RECEIVE-CONTROL Paragraph You can write server processes in HP COBOL. The system file process named $RECEIVE is the communication mechanism between a requester process and a server process or between the operating system and any process (as if the process were a server). When a COBOL server resumes execution upon the completion of a READ on $RECEIVE, it can require information about the source of the message that was delivered. To define the two tables used by $RECEIVE, include a RECEIVE-CONTROL paragraph in the Environment Division of your server process. In the CRE, the RECEIVE-CONTROL paragraph used for a run unit is the one for the program that first opens $RECEIVE. In the non-CRE environment, the RECEIVE-CONTROL paragraph used for a run unit is the one in the main program. The $RECEIVE mechanism of a server written in HP COBOL uses the receive-control table (sometimes called the Requester table) to record the status of the requesting processes that have opened the server. It uses the reply table to keep copies of the replies it has sent to each requesting process. When the requester is running as a process pair and the requester sends a message and the backup process takes over before the requester receives a reply, the server can resend the reply automatically if a CHECKPOINT statement is executed after the server reads the requester’s message and before the server writes a reply (or generates one automatically with another READ). In this case, the server does not see the duplicate message. The CHECKPOINT statement can be executed even if the server is not running as a process pair. In the simplest case, when a single requester and a single server are involved and neither is running as a process pair, the default tables can accommodate the $RECEIVE operations. The ERROR clause provides a means of specifying that the server itself (and not its run-time routines) takes responsibility for specifying any error number that the $RECEIVE mechanism is to deliver to the requester. The MESSAGE SOURCE phrase provides a means of identifying the sender of any message arriving through $RECEIVE. The REPORT clause provides a means of specifying the classes of messages arriving at $RECEIVE that are to be delivered to the server, rather than handled automatically by the $RECEIVE mechanism. National literals and national data items cannot be used in a RECEIVE-CONTROL paragraph. In the non-CRE environment, the RECEIVE-CONTROL paragraph for a run unit is the one in the main program. In the CRE, the RECEIVE-CONTROL paragraph for a run unit is the one in the first program to open $RECEIVE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 64 Environment Division RECEIVE-CONTROL Paragraph RECEIVE-CONTROL . . EXTERNAL TABLE OCCURS phrase SYNCDEPTH LIMIT phrase REPLY CONTAINS phrase ERROR CODE phrase MESSAGE SOURCE phrase REPORT phrase VST063.vsd EXTERNAL can only appear in a CRE program; enables COBOL external files to share communication with $RECEIVE and to share $RECEIVE properly with FORTRAN. EXTERNAL causes the compiler to create a special block, #RECEIVE, which contains the information used when $RECEIVE is opened by FORTRAN or by a COBOL external file. The COBOL85 compiler does not generate a default #RECEIVE block, as the FORTRAN compiler does TABLE OCCURS phrase TABLE OCCURS EXTENDED-STORAGE table-length TIMES VST064.vsd establishes the length of the receive-control table, governing the maximum number of requesters that can have this process open concurrently. In a Pathway environment, this number can be decreased at execution time but not increased. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 65 Environment Division RECEIVE-CONTROL Paragraph Each entry in the receive-control table records which requester opened the server process and which open operation the requester used (if a requester opens the server process more than once). table-length is an unsigned integer numeric literal in the range 1 through 255. The default value is 1. EXTENDED-STORAGE allows saved messages to be stored in extended storage. The conditions for its use are: • • The program must open $RECEIVE (otherwise, EXTENDED-STORAGE is irrelevant) The program does not run in the CRE (that is, it was compiled by the COBOL85 compiler without the ENV COMMON or ENV LIBRARY directive). If the program runs in the CRE, the saved messages are automatically stored in extended storage if they exceed an internal threshold value. • The product of table-length, the length of the saved message, and sync-id, plus the sizes of all the data items in the Extended-Storage sections of all the programs in the run unit cannot exceed 134,217,214 characters. (The length of the saved message is specified by the REPLY CONTAINS phrase.) SYNCDEPTH LIMIT phrase sync-id SYNCDEPTH LIMIT IS VST065.vsd establishes the length of the reply table, controlling how many replies are saved for each requesting process (opener). sync-id is an unsigned integer numeric literal in the range 1 through 255. In any requester process that opens the server process, the value in the SYNCDEPTH phrase of the OPEN statement cannot exceed sync-id. When you do not use the SYNCDEPTH LIMIT phrase, sync-id defaults to 1. A Pathway server never needs a SYNCDEPTH LIMIT greater than 1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 66 Environment Division RECEIVE-CONTROL Paragraph REPLY CONTAINS phrase REPLY CONTAINS reply-length CHARACTERS file-name RECORD VST066.vsd specifies the number of characters of a reply message that are to be saved in the reply table. The default is 0. reply-length is an unsigned integer numeric literal. Its value is the maximum number of characters from a reply message to be saved in the reply table. file-name is the name of a file whose longest record’s length is the number of characters from a reply message to be saved in the reply table. ERROR CODE phrase error ERROR CODE IS VST067.vsd error is an unsigned integer numeric item for storing an error code for a reply message, which you must set. It can be in the Working-Storage Section, the File Section, or the Linkage Section. MESSAGE SOURCE phrase message SOURCE MESSAGE IS VST068.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 67 Environment Division RECEIVE-CONTROL Paragraph message is an alphanumeric item that is: ° Defined in the Working-Storage Section, Extended-Storage Section, File Section, or Linkage Section ° ° ° ° ° Aligned on an even character boundary within a record At least 32 characters long Not a table Not modified by a reference Not of a variable size (not a data structure that contains an OCCURS DEPENDING ON clause) The contents of message are updated automatically after a file assigned to $RECEIVE is successfully read. REPORT phrase REPORT message-type MESSAGES VST069.vsd specifies the type of system messages to be passed to the program. message-type depends on the environment. In the non-CRE environment, message-type has one of these values: ABEND NEWPROCESSNOWAIT-COMPLETION BREAK NODE-DOWN CLOSE NODE-UP CONTROL OPEN CONTROLBUF POWER-ON CPU-DOWN PROCESS-DELETION CPU-UP PROCESS-TIME-SIGNAL DEVICE-INFO REMOTE-CPU-DOWN DEVICE-INFO-2-COMPLETION REMOTE-CPU-UP JOB-PROCESS-CREATION RESETSYNC LOGICAL-CLOSE SETMODE LOGICAL-OPEN SETPARAM MEMORY-LOCK-COMPLETION SETTIME HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 68 Environment Division RECEIVE-CONTROL Paragraph MEMORY-LOCK-FAILURE STATUS-3270 MESSAGE-CANCELLED STOP MESSAGE-MISSED SYSTEM NETWORK TIME-SIGNAL NEWPROCESS-COMPLETION In the CRE, message-type has one of these values: BREAK NEWPROCESSNOWAIT-COMPLETION CLOSE NODE-DOWN CONTROL NODE-UP CONTROLBUF OPEN CPU-DOWN PATHSEND-DIALOG-ABORT CPU-UP POWER-ON DEVICE-INFO PROCESS-CREATE-COMPLETION DEVICE-INFO-2-COMPLETION PROCESS-DELETION FILE-GETINFOBYNAMECOMPLETION PROCESS-TIME-SIGNAL FILE-FILENAME-COMPLETION REMOTE-CPU-DOWN JOB-PROCESS-CREATION REMOTE-CPU-UP LOGICAL-CLOSE RESETSYNC LOGICAL-OPEN SETMODE MEMORY-LOCK-COMPLETION SETPARAM MEMORY-LOCK-FAILURE SETTIME MESSAGE-CANCELLED STATUS-3270 MESSAGE-MISSED SYSTEM NETWORK TIME-SIGNAL NEWPROCESS-COMPLETION message-type identifies the class of system message passed to a program. Messages in unnamed classes are handled by the run-time routines in a standard manner. CONTROL and SETMODE messages are rejected if not requested by a program. BREAK messages are ignored if not requested by a program. SYSTEM as a type signifies a particular subset of the preceding list. The other classes of messages provide the run-time routines with information needed to accept, manage, and delete requesters. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 69 Environment Division RECEIVE-CONTROL Paragraph Topics: • • • • • Receive-Control Table Reply Table ERROR CODE Phrase MESSAGE SOURCE Phrase REPORT Phrase Receive-Control Table The receive-control table, an internal table, is required for $RECEIVE operation. Its purpose is to identify, by the PROCESS-ID, which requesting processes have opened the server process. Table 6-7. Receive-Control Table Example Entry Number Requesting Process 1 REQUESTER PROCESS 1 2 REQUESTER PROCESS 2 3 REQUESTER PROCESS 3 … … 100* REQUESTER PROCESS 100 * The number of entries in the receive-control table is defined by table-length. The compiler allocates only one receive-control table because only one file assigned to $RECEIVE can be open for input or input-output at a time. When more than one program unit defines a receive-control table, the compiler reserves space for the largest table. In the Pathway environment, the value of table-length for a server must be greater than or equal to the value of the MAXLINKS parameter in the server-class definition for the server. When the number of active requesters fills the receive-control table, OPEN messages from new requesters are refused with a run-time error message and are not reported to your program. OPEN messages received from backup processes of active requesters are still accepted and reported. Reply Table When reply messages are sent back to the requesting processes, the COBOL compiler constructs a second internal table in which to save the replies. The reply message includes the sync-id and the contents of the reply. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 70 Environment Division RECEIVE-CONTROL Paragraph In the COBOL85 environment, if the RECEIVE-CONTROL paragraph’s TABLE OCCURS phrase includes EXTENDED-STORAGE, the reply table is in the ExtendedStorage Section. In the CRE, if the reply table exceeds an internal threshold value, the reply table is in the Extended-Storage Section. Note. You do not need a reply table if the requester is not a fault-tolerant process. Figure 6-1. Reply Table Entry length is defined by reply-length or file-name REQUESTER PROCESS 1 REPLY MESSAGE 1 REQUESTER PROCESS 1 REPLY MESSAGE 2 Number of replies per requester is defined by sync REQUESTER PROCESS 2 REPLY MESSAGE 6 REQUESTER PROCESS 2 REPLY MESSAGE 7 REQUESTER PROCESS 3 REPLY MESSAGE 4 REQUESTER PROCESS 3 REPLY MESSAGE 5 . . . Number of entries is defined by table-length * sync VST506.vsd Reply messages saved in the reply table are identified by their requester process. These messages correspond to and answer the specific requester. For example, if REQUESTER PROCESS 3 in Figure 6-1 failed before it received REPLY MESSAGE 5, and its backup reissued the request based on the checkpoint information, the COBOL fault-tolerant facility would recognize that the request was performed. It would reissue REPLY MESSAGE 5 to REQUESTER PROCESS 3 without re-executing the request. If a Receive-Control paragraph has no reply table (no SYNCDEPTH LIMIT and REPLY CONTAINS clauses), then replies are not saved. The fault-tolerant facility cannot retransmit them. If a requester’s backup process retransmits them, they are not recognized as duplicate requests, because the originals were not saved. Responding to duplicate messages can corrupt the database. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 71 Environment Division RECEIVE-CONTROL Paragraph ERROR CODE Phrase The ERROR CODE phrase of the RECEIVE-CONTROL paragraph provides a way for a server process to appear as a device to its requesters. When the server process sends an error code to a requester, the server process uses file-system error codes to set the ERROR CODE item. How the server process sets the ERROR CODE item depends on the device type of the device the server is simulating. When the server makes a reply to a READ on $RECEIVE, the operating system passes back the value of the ERROR CODE item separately from the reply-message text. Additionally, the system passes back a condition code (CCE, CCG, or CCL) based on the value of the file-system error number. (See the Guardian Programmer’s Guide for information about file-system errors and condition codes.) The requester checks for a condition code other than CCE (successful operation) after its action to send a task message and receive a response. If there is an error (CCG or CCL), the requester must call FILEINFO, a system procedure, to determine the error code (from ERROR CODE item) passed by the operating system. When a requester process is written in COBOL, condition code checking (including the call to FILEINFO) is handled by the COBOL run-time library routines. When you use ERROR CODE error, but the server is not executing a WRITE for each READ on $RECEIVE, the system acknowledges each message from a requester and also passes the value of error with each internal reply. If you take this approach, be careful to have the right value in error at all times. The operating system also returns the value of error with explicit or systemgenerated replies to reported system messages (system messages are reported when the REPORT message-type MESSAGES option is used). When system messages are not reported, the COBOL run-time library replies to them and generates an error code. MESSAGE SOURCE Phrase The MESSAGE SOURCE phrase provides a mechanism through which a COBOL program can discover the sender of each message received. During the successful execution of a read operation on $RECEIVE, the $RECEIVE mechanism assigns a set of values to the storage space designated in the MESSAGE SOURCE phrase. Example 6-9. MESSAGE SOURCE Phrase (Non-CRE) 01 SOURCE-MESSAGE. 05 MESSAGE-TYPE 05 ENTRY-NUMBER 05 FILLER 05 PROCESS-ID. 10 PROCESS-NAME 10 CPU-PIN 05 FILLER PICTURE PICTURE PICTURE S999 USAGE IS COMPUTATIONAL. 999 USAGE IS COMPUTATIONAL. X(4). PICTURE PICTURE PICTURE X(6). X(2). X(16). HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 72 Environment Division RECEIVE-CONTROL Paragraph Example 6-10. MESSAGE SOURCE Phrase (CRE) 01 SOURCE-MESSAGE. 05 MESSAGE-TYPE 05 ENTRY-NUMBER 05 FILLER 05 PHANDLE 05 FILLER PICTURE PICTURE PICTURE PICTURE PICTURE S999 USAGE IS COMPUTATIONAL. 999 USAGE IS COMPUTATIONAL. X(4). X(20). X(4). MESSAGE-TYPE is one of: Value Meaning Zero or greater Message sent by the requesting process Less than zero Message sent by the operating system ENTRY-NUMBER is the number assigned to the receive-control table entry for a requesting process. It is in the range set by table-length. When certain system messages not associated with any requester, such as CPU-UP and CPU-DOWN, are received, the number is 0. PROCESS-ID is the 8-byte operating system process ID. The first 6 characters are the process name or a timestamp for an unnamed process. The last 2 characters are the processor number and process number. PHANDLE is a unique identifier that specifies a process to process-related procedure calls (for more information, see the Guardian Programmer’s Guide). REPORT Phrase Normally, the $RECEIVE mechanism automatically intercepts and processes all messages sent to the run unit by the operating system. By specifying the REPORT clause, you state that the $RECEIVE mechanism is not to intercept certain classes of system messages, but pass them back to the program for processing. The program then supplies the appropriate error code (if the ERROR CODE clause appears), and generates the appropriate response (by performing a write operation or another read operation on $RECEIVE). In the non-CRE environment, the file accepting messages through $RECEIVE must have a record length of at least 34 characters when system messages are received. In the CRE, the file must have a record length of at least 255 characters. “System” is an abbreviation for the messages that are generated under program control. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 73 Environment Division RECEIVE-CONTROL Paragraph Table 6-8. Message Types That the Program Generates (System) Message-Type Code COBOL Keyword Non-CRE Environment CRE ABEND -06 Not used—see Table 6-10 CLOSE -31 -104 CONTROL -32 -32 CONTROLBUF -35 -35 MEMORY-LOCK-COMPLETION -23 -23 MEMORY-LOCK-FAILURE -24 -24 NEWPROCESSNOWAIT-COMPLETION -12 -12 OPEN -30 -103 RESETSYNC -34 -34 SETMODE -33 -33 STOP -05 Not used—see Table 6-10 TIME-SIGNAL -22 -22 Messages generated by asynchronous hardware events must be explicitly requested. Table 6-9. Message Types That the Hardware Generates (Asynchronous) Message-Type Code COBOL Keyword Non-CRE Environment CRE BREAK -20 -105 CPU-DOWN -02 -02 or -101 CPU-UP -03 -03 NETWORK -08 Not used—see Table 6-10 POWER-ON -11 -11 SETTIME -10 -10 See the Guardian Programmer’s Guide for a description of system messages, their formats, and their implications. The D-series has many message types and some codes for HP COBOL message types that the C-series does not have. For example, in the CRE, the message type SYSTEM includes all messages except LOGICAL-CLOSE and LOGICAL-OPEN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 74 Environment Division RECEIVE-CONTROL Paragraph LOGICAL-OPEN and LOGICAL-CLOSE are conventions that enable a program to keep track of its active requesters simply and directly. LOGICAL-OPEN selects only the first OPEN message from each new requester. OPEN messages from requester backups are automatically handled by the run-time routines and not passed to the program. Similarly, LOGICAL-CLOSE selects only the final CLOSE message from a requester. If both are asserted, the program receives a single OPEN message whenever a process or process pair bids for requester access and a single CLOSE message whenever an active requester relinquishes its access. Because the specific message type causes all messages of its class to be passed to the program, the assertion of OPEN (or SYSTEM, which implies OPEN) overrides LOGICAL-OPEN, and the assertion of CLOSE (or SYSTEM) overrides LOGICAL-CLOSE. Table 6-10. REPORT Clause Message Types in the CRE (page 1 of 2) Message Type Code Message Type CRE COBOL85 Meaning BREAK -105 -20 Break on device CLOSE -104 -31 Close CONTROL -32 -32 CONTROL system request CONTROLBUF -35 -35 CONTROLBUF system request CPU-DOWN -02 -02 Local processor failure CPU-UP -03 -03 Local processor reload DEVICE-INFO -106 -40 Device type inquiry DEVICEINFO2-COMPLETION -41 -41 Nowait device type inquiry FILE-GETINFOBYNAMECOMPLETION -108 N. A. Nowait FILE_GETINFOBYNAME_ completion FILENAME-FINDNEXTCOMPLETION -109 N. A. Nowait FILENAME_FINDNEXT_ completion JOB-PROCESS-CREATION -112 -09 Job process creation LOGICAL-CLOSE N. A. N. A. Logical close LOGICAL-OPEN N. A. N. A. Logical open MEMORY-LOCKCOMPLETION -23 -23 Memory lock completion MEMORY-LOCK-FAILURE -24 -24 Memory lock failure MESSAGE-CANCELLED -38 -38 Message cancelled MESSAGE-MISSED -13 -13 System message buffer overrun NEWPROCESSCOMPLETION -12 -12 NEWPROCESSNOWAIT completion HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 75 Environment Division RECEIVE-CONTROL Paragraph Table 6-10. REPORT Clause Message Types in the CRE (page 2 of 2) Message Type Code Message Type CRE COBOL85 Meaning NEWPROCESSNOWAITCOMPLETION -12 -12 NEWPROCESSNOWAIT completion NODE-DOWN -110 -08 Lost communication with node NODE-UP -111 -08 Established communication with node OPEN -103 -30 Open POWER-ON -11 -11 Power on PROCESS-CREATECOMPLETION -102 N. A. Nowait PROCESS_CREATE_ completion PROCESS-DELETION -101 -02 Process deletion (processor failure, STOP, ABEND) -05 -06 PROCESS-TIME-SIGNAL -26 -26 Process time timeout REMOTE-CPU-DOWN -100 -08 Remote processor down REMOTE-CPU-UP -113 -08 Remote processor up RESETSYNC -34 -34 RESETSYNC system request SETMODE -33 -33 SETMODE system request SETPARAM -37 -37 Process SETPARAM SETTIME -10 -10 Set time STATUS-3270 -21 -21 3270 device status received SUBORDINATE-NAME -107 N. A. Subordinate name inquiry SYSTEM N. A. N. A. All except logical open and close TIME-SIGNAL -22 -22 Elapsed time timeout HP COBOL Manual for TNS and TNS/R Programs —522555-006 6- 76 7 Data Division The Data Division is optional in a COBOL program. It has four sections: the File Section, the Working-Storage Section, the Extended-Storage Section, and the Linkage Section. Each section contains entries describing data that the program unit being compiled from the source program manipulates. If your program does not use the type of data that the section defines, then the section is optional. DATA DIVISION . FILE Section WORKING-STORAGE Section EXTENDED-STORAGE Section LINKAGE Section VST070.vsd Topics: • • • • • • • • • Data Categories and Data Descriptions File Section Working-Storage Section Extended-Storage Section Linkage Section Descriptions of Records (Levels 01-49) Descriptions That Rename Items (Level 66) Descriptions of Noncontiguous Elementary Items (Level 77) Descriptions of Condition-Names for Values (Level 88) HP COBOL Manual for TNS and TNS/R Programs —522555-006 7 -1 Data Division Data Categories and Data Descriptions Data Categories and Data Descriptions Table 7-1. Data Categories Category File Data Internal Data External Data Definition Data that a process can read from or write to files (including the mapping between the internal program storage and the file storage) Data that a process develops internally and holds in temporary areas Data that all programs in the run unit can access Where Data is Described File Section Working-Storage Section Extended-Storage Section Linkage Section File Section Working-Storage Section Extended-Storage Section How Data is Described Data file description entries and sort-merge file description entries, each followed by one or more record description entries Record description entries and independent data item entries File descriptions, record description entries, and independent data item entries Topics: • • Record Description Entries Independent Data Item Description Entries Record Description Entries A record description entry is a set of one or more data description entries. The first data description entry has level number 01. Each additional entry has a level number in the range 02 through 49 or the special level number 66 or 88. Entries with level numbers 02 through 49 and 66 are subordinate data items of the record data item defined in the initial data description entry (which has level number 01). Entries with level number 66 redefine or rename portions of the record. Entries with level number 88 define condition-names. Data items with level number 77 do not belong to records. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7 -2 Data Division Independent Data Item Description Entries More information: Record Levels Sources 01-49 Records 66 Descriptions That Rename Items (Level 66) 77 Independent Data Item Description Entries and Descriptions of Noncontiguous Elementary Items (Level 77) 88 Descriptions of Condition-Names for Values (Level 88) Independent Data Item Description Entries An independent data item description entry is a set of one or more data description entries. The first entry must have level number 77. Each additional entry has either the special level number 88 (to define condition-names associated with values of the level77 item) or both the level number 77 and the REDEFINES clause (to make it a redefinition of the preceding level-77 item). Level-77 items are discussed at length in Descriptions of Noncontiguous Elementary Items (Level 77). Example 7-1. Level-77 Description Entries 77 BUFFER PIC X(132). 77 ARTIFACT PIC X(10). 88 CONTAINER VALUES ARE "JAR" "AMPHORA" "CANISTER". 88 WEAPON VALUES ARE "SPEAR" "BOW" "KNIFE" "MISSILE". 77 LOCATION PIC X(30). 77 OFFICE PIC X(25) REDEFINES LOCATION. 88 LOCAL VALUE IS "HEADQUARTERS". 88 NORTHEAST-USA VALUES ARE "ALLENTOWN" "NEW HAVEN" "CAPE MAY" "WILMINGTON". 88 SOUTHEAST-USA VALUES ARE "ATLANTA" "MYRTLE BEACH". There is no difference between a level-77 item and an elementary level-01 item, and the latter is preferred. File Section The File Section defines the characteristics of the program’s files. Every file name described as a data file (FD) or a sort-merge file (SD) in the File Section must be defined as the same type of file in a corresponding file-control entry of the Environment Division. Conversely, every data file defined in a file-control entry of the Environment Division must be described exactly once in an file description entry of the File Section, and every sort-merge file defined in a file-control entry of the Environment Division must be described exactly once in an sort-merge file description entry of the File Section. The storage space in the File Section is limited because it is allocated in the lower 64 KB of user data space. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7 -3 Data Division File Section FILE SECTION . 66-or-88 FD-entry 66-or-88 SD-entry 66-or-88 VST071.vsd 66-or-88 is a level-66 or level-88 description. For syntax, see Descriptions That Rename Items (Level 66) and Descriptions of Condition-Names for Values (Level 88). FD-entry FD file-description 01-data-description VST072.vsd file-description defines the physical aspects of a data file. See File Description Entries. 01-data-description defines a logical record, specifying the layout of fields within the record and the size and usage of each field. See Data Description Entries. SD-entry SD sort-merge-file-description 01-data-description VST073.vsd sort-merge-file-description defines the physical aspects of a sort-merge file. See Sort-Merge File Description Entries. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7 -4 Data Division File Description Entries 01-data-description defines a logical record, specifying the layout of fields within the record and the size and usage of each field. See Data Description Entries. Topics: • • • File Description Entries Sort-Merge File Description Entries Data Description Entries File Description Entries The file description (FD) entry is the highest level of organization in the File Section of the Data Division. FD clauses give the size of logical and physical records and the names and attributes of the data records within the file. When a file is to be printed on a printer (either directly, or through a spooler), its file description can include information about how the data is printed on a page. The characteristics of the file determine which of the clauses are required and which are optional. Clauses that appear can follow in any order, ending with a period after the last clause. No clause can appear more than once. The data description entries of one or more records must follow the file description entry. Each file description entry must be followed by one or more record description entries. These describe the format or formats of the logical records in the file. When more than one record description entry appears, they can describe record images of different lengths and substructures. All record description entries associated with a single file represent implicit redefinitions of the file’s record area. The file name in the file description entry can be used as the final qualifier in references to its record items, their subordinate data items, or condition-names associated with any of these. When more than one of the source programs compiled into a run unit includes a file description entry defining the same external file name, all of these descriptions must specify the same block size convention, character code convention, labeling convention, linage attributes, and record attributes. For details, see EXTERNAL Clause. The file description entry describes the logical characteristics of a data file. The record description entries associated with a file description entry define the possible formats of the logical records for that file. Although different record descriptions define different types of logical records from the perspective of the source program, the corresponding logical records in the file might not have different representations. Conceptually, every record description applies to every logical record in the file; therefore, when the file actually contains different types of logical records, it is your responsibility to code the program such that it determines which of the record descriptions are appropriate for each particular record. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7 -5 Data Division File Description Entries In Example 7-2, two record description entries (level-01 items) follow a file description entry. Example 7-2. File Description (FD) Entry FD INPUT-FILE-MASTER GLOBAL RECORD IS VARYING IN SIZE FROM 10 TO 256 CHARACTERS 01 OFFICE-DETAILS. 03 NUMBER PIC 9(5). 03 ADDRESS. 05 LINE-1 PIC X(25). 05 LINE-2 PIC X(25). 05 LINE-3 PIC X(25). 03 HEAD-COUNT PIC 999. 03 MANAGER-ID-NUMBER 9(5). 01 EMPLOYEE-DETAILS. 03 ID-NUMBER PIC 9(5). 03 TITLE PIC X(25). 03 MANAGER-ID-NUMBER PIC 9(5). 03 SALARY-LEVEL PIC X(2). The syntax of a file description entry (file-description ) depends on the file’s access mode: • • • File Description Entry for Sequential File File Description Entry for Line Sequential File (OSS environment only) File Description Entry for Relative, Indexed, or Queue File HP COBOL Manual for TNS and TNS/R Programs —522555-006 7 -6 Data Division File Description Entries File Description Entry for Sequential File file-name . EXTERNAL clause GLOBAL clause BLOCK CONTAINS clause RECORD CONTAINS clause «LABEL RECORDS clause» «VALUE OF clause» «DATA RECORDS clause» LINAGE clause CODE-SET clause REPORT clause VST074.vsd file-name is the highest-level qualifier for both a file description entry and its data descriptions; therefore, the name must be unique within a program. EXTERNAL clause is described in EXTERNAL Clause. GLOBAL clause is described in GLOBAL Clause. BLOCK CONTAINS clause is described in BLOCK CONTAINS Clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7 -7 Data Division File Description Entries RECORD CONTAINS clause is described in RECORD CONTAINS Clause. LABEL RECORDS clause is described in LABEL RECORDS Clause. VALUE OF clause is described in VALUE OF Clause. DATA RECORDS clause is described in DATA RECORDS Clause. LINAGE clause is described in LINAGE Clause. CODE-SET clause is described in CODE-SET Clause. REPORT clause is described in REPORT Clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7 -8 Data Division File Description Entries File Description Entry for Line Sequential File Note. Available only in the OSS environment. file-name . EXTERNAL clause GLOBAL clause RECORD CONTAINS clause «LABEL RECORDS clause» «VALUE OF clause» «DATA RECORDS clause» REPORT clause VST633.vsd file-name is the highest-level qualifier for both a file description entry and its data descriptions; therefore, the name must be unique within a program. EXTERNAL clause is described in EXTERNAL Clause. GLOBAL clause is described in GLOBAL Clause. RECORD CONTAINS clause is described in RECORD CONTAINS Clause. LABEL RECORDS clause is described in LABEL RECORDS Clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7 -9 Data Division File Description Entries VALUE OF clause is described in VALUE OF Clause. DATA RECORDS clause is described in DATA RECORDS Clause. REPORT clause is described in REPORT Clause. File Description Entry for Relative, Indexed, or Queue File file-name . EXTERNAL clause GLOBAL clause BLOCK CONTAINS clause RECORD CONTAINS clause «LABEL RECORDS clause» «VALUE OF clause» «DATA RECORDS clause» VST637.vsd file-name is the highest-level qualifier for both a file description entry and its data descriptions; therefore, the name must be unique within a program. EXTERNAL clause is described in EXTERNAL Clause. GLOBAL clause is described in GLOBAL Clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 10 Data Division File Description Entries BLOCK CONTAINS clause is described in BLOCK CONTAINS Clause. RECORD CONTAINS clause is described in RECORD CONTAINS Clause. LABEL RECORDS clause is described in LABEL RECORDS Clause. VALUE OF clause is described in VALUE OF Clause. DATA RECORDS clause is described in DATA RECORDS Clause. EXTERNAL Clause The EXTERNAL clause gives the file connector referenced by file-name the external attribute, meaning that it belongs to the run unit rather than to any single program in the run unit. When more than one program in a run unit specifies a file connector with the same file name and the external attribute, they all refer to the same file connector. For an explanation of external objects (those with the external attribute), see External and Internal Objects. EXTERNAL IS VST075.vsd Usage Considerations: • Sharing a File Connector If more than one of the source programs compiled into a run unit contain file description entries defining the same file name, all entries that include the EXTERNAL clause describe the same external file connector. Any file name whose file description entry does not include the EXTERNAL clause refers to an internal file connector, even if the same file name identifies an external file connector in some other program of the run unit. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 11 Data Division • File Description Entries EXTERNAL Clause Inherited by Data Items in External Files The EXTERNAL clause specifies that the file connector associated with the file name defined by the containing file description entry is an external file connector, and that the data items associated with all of the record descriptions for this file name are external data items; therefore, any other source program compiled into the same run unit can share these resources by including a file description entry that defines the same file name and contains the EXTERNAL clause. • Other Related Data Items Required to be External Any data items referenced in the clauses of a file description entry containing the EXTERNAL clause (such as the LINAGE clause or the VARYING DEPENDING clause) or in the clauses of the corresponding file-control entry (such as the FILE STATUS clause or the ALTERNATE RECORD KEY clause) must be external data items. • Consistency of External Files Throughout the Run Unit All descriptions of the same external file connector, and the file that it references, must be functionally identical. The detailed restrictions are: ° File-control entries All of the file-control entries must specify or imply the same operating system file name, organization, and access mode. If any of the file-control entries includes the OPTIONAL phrase, all of them must do so. ° Keys If any of the file-control entries specifies a relative key, record key, or alternate record key, all of them must specify the same external data item for that purpose. Each alternate record key must have a consistent DUPLICATES attribute. ° PADDING CHARACTER clause If any of the file-control entries includes a PADDING CHARACTER clause, all of them must include a PADDING CHARACTER clause that specifies the same padding attribute. In particular, when the value of a data item supplies the padding character, the same external data item must be specified for this purpose in each of the clauses. ° RECORD DELIMITER clause If any of the file-control entries includes a RECORD DELIMITER clause specifying a system-name, all of them must include a RECORD DELIMITER clause specifying the same system-name. ° BLOCK CONTAINS clause If any of the file description entries includes a BLOCK CONTAINS clause, all of them must include a BLOCK CONTAINS clause that specifies the same block size attribute. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 12 Data Division ° File Description Entries RECORD CONTAINS clause If any of the file description entries includes a RECORD CONTAINS clause, all of them must include a RECORD CONTAINS clause that specifies the same record attributes (fixed-length or variable-length, fixed record size or minimum and maximum record sizes, and the external data item that reflects the current logical record size, if any). ° LABEL RECORDS clause Note. The 1985 COBOL standard classifies the LABEL RECORDS clause as obsolete, so you are advised not to use it. If any of the file description entries includes a LABEL RECORDS clause with the STANDARD phrase, all of them must include a LABEL RECORDS clause with the STANDARD phrase. ° LINAGE clause If any of the file description entries includes a LINAGE clause, all of them must include a LINAGE clause that specifies the same logical page attributes. In particular, when the value of a data item supplies one of the attributes, the same external data item must be specified for this purpose in each of the clauses. ° CODE-SET clause If any of the file description entries includes a CODE-SET clause that references an alphabet-name associated with a system-name, all of them must include a CODE-SET clause that references an alphabet-name associated with the same system-name. • Open Mode States At the beginning of each execution of the run unit, the open mode state for each external file connector is Closed and the status of all other dynamic file attributes is undefined. If the open mode state of an external file connector is not Closed or Locked when execution of the run unit terminates, it is closed by the execution of an implicit CLOSE statement without any of the optional phrases. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 13 Data Division File Description Entries GLOBAL Clause The GLOBAL clause makes file-name a global name, meaning that it is available to every program contained within the program that describes it. The contained programs do not contain a description of the file. For an explanation of global names, see Global and Local Names. GLOBAL IS VST076.vsd Usage Considerations: • Referencing Global Items A statement in a program contained directly or indirectly within a program that describes a global name can reference that name without describing it again. • Subordinates of Global Names Are Global Names A file name described using a GLOBAL clause is a global name. All data-names subordinate to a global name are global names. All condition-names associated with a global name are global names. • SAME RECORD AREA Clause If the SAME RECORD AREA clause is specified for several files, the record description entries or the file description entries for these files must not include the GLOBAL clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 14 Data Division File Description Entries BLOCK CONTAINS Clause Use the optional BLOCK CONTAINS clause to specify the number of logical records or the number of character positions in a physical record on tape or unstructured disk files only. For these types of files, if this clause is absent, the compiler assigns a block size of one logical record. The operating system handles all other file blocking and deblocking in a way that is transparent to the COBOL program. BLOCK blk-2 CONTAINS blk-1 TO RECORDS CHARACTERS VST077.vsd blk-1 is an unsigned integer literal that specifies the minimum size of a block. blk-2 is an unsigned integer literal. In the presence of blk-1, blk-2 is the fixed size of a block; otherwise, it is the maximum size of a block. RECORDS specifies that the values of blk-1 and blk-2 represent numbers of logical records. CHARACTERS specifies that the values of blk-1 and blk-2 represent numbers of character positions. This is the default. Usage Considerations: • Limits The minimum number of character positions you can specify is equal to the maximum record size of the file. If you specify more than 32,767 character positions, the compiler reports an error. If you specify a number of records greater than 32,767 divided by the maximum record size for the file, the compiler reports an error. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 15 Data Division File Description Entries When blk-1 is present, its value must be less than or equal to that of blk-2. When the RECORDS option is not specified, the value of blk-1 must be greater than or equal to the minimum record size of the file; otherwise, the value of blk-1 must be greater than 0. Although tape devices are capable of handling blocks of 32,767 characters, unstructured disk files are limited to a block size of 4,096. Furthermore, an unstructured disk file can have a BLOCKSIZE attribute that is smaller than 4,096. Other devices have their own block size limitations. See the discussion of the WRITE procedure call in the Guardian Procedure Errors and Messages Manual for these limits. Because the compiler cannot determine the block size of the device that is ultimately associated with a file, you must choose the correct block size and record size or risk getting a run-time error. • Blocking and Deblocking for Tape and Unstructured Disk A BLOCK CONTAINS clause is effective (HP COBOL performs record blocking and deblocking) only when all of these conditions are met, and the file associated at open time is either a tape unit or an unstructured disk file: ° ° The file’s organization is sequential. ° When the block size is specified in characters, it is a multiple of the number of characters in the logical record size. Also, when a RECORD CONTAINS clause extends the record size, the block size expressed is a multiple of the number of characters in that specified record size. ° ° The file is not described with a LINAGE or ALTERNATE RECORD KEY clause. The file has fixed-length records. This condition is met only when the file description contains either no RECORD CONTAINS or RECORD VARYING clause or contains a RECORD CONTAINS clause that specifies only a single record size. Tape Files If the actual file associated with the COBOL file at open time is a tape unit, then blocking/deblocking always occurs. For an unlabeled tape file, the maximum block size is the one specified in the BLOCK CONTAINS clause. For a labeled tape file, the maximum block size specified in the tape label (which must be an exact multiple of the logical record size) overrides the one specified in the BLOCK CONTAINS clause. If the file is opened for INPUT, then each physical block on the tape medium must contain one or more complete logical records. The size of a block must not exceed the maximum block size; however, any block can be smaller than the maximum block size (can contain fewer than the potential number of logical records). HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 16 Data Division ° File Description Entries Unstructured Disk Files If the actual file associated with the COBOL file at open time is an unstructured disk file, then blocking/deblocking occurs if the logical record size is an even number of character positions or the file has the odd-length access attribute; otherwise the BLOCK CONTAINS clause is ignored (that is, logical records are physically read or written one at a time). (To have the odd-length access attribute, a file must be created with FUP CREATE and ODDUNSTR must be specified.) Odd-length records are written as even-length unless ODDUNSTR is active. The compiler issues a warning if blocking is specified when the conditions, other than variable-length records, are not satisfied. RECORD CONTAINS Clause Use the RECORD CONTAINS clause to specify whether the records of a file are of fixed or variable length and to document the size of the records. RECORD contains-phrase-fixed «contains-phrase-range» VARYING phrase VST078.vsd contains-phrase-fixed length-fixed CONTAINS CHARACTERS VST079.vsd length-fixed is an unsigned integer literal that specifies the exact length, in characters, of fixed-length records. Its value is in the range 0 through 32,767. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 17 Data Division File Description Entries «contains-phrase-range» Note. The 1985 COBOL standard classifies contains-phrase-range as obsolete, so you are advised not to use it. Instead, use a VARYING phrase of the form: RECORD IS VARYING FROM length-min TO length-max length-min TO length-max CONTAINS CHARACTERS VST405.vsd length-min is an unsigned integer literal that specifies the minimum length, in characters, of variable-length records. Its value is in the range 0 through 32,767. No record description entry for the file described with length-min can specify a number of character positions less than the value of length-min. When the RECORD clause appears in a data file description entry, no record key or alternate record key defined for the file can be described as beginning after or extending beyond the number of characters specified by length-min. length-max is an unsigned integer literal that specifies the maximum length, in characters, of variable-length records. Its value must be greater than or equal to the value specified by length-min (for the RECORD CONTAINS form of variablelength specification) or greater than the value specified by length-min (for the RECORD VARYING form of variable-length specification). No record description entry for the file described with length-max can specify a number of character positions greater than the value of length-max. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 18 Data Division File Description Entries VARYING phrase VARYING IS IN length-min SIZE CHARACTERS FROM TO length-max length-var DEPENDING ON VST092.vsd explicitly declares that the file consists of variable-length records (records of different sizes). length-min is as defined previously. The default is the size of the shortest record description entry. length-max is as defined previously. The default is the size of the longest record description entry. length-var is the data-name of an unsigned integer numeric data item. It tells the REWRITE and WRITE statements how many characters to deliver, and receives the size (in characters) of any record that was read successfully. It can be qualified, but not subscripted or reference-modified. Record size is the actual number of bytes needed to store the record, determined by the sum of bytes for each fixed-length elementary item plus the maximum number of bytes for any variable-length item. The number of bytes for an item also depends on its USAGE clause, and if synchronization is active, any filler from alignment on storage boundaries. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 19 Data Division File Description Entries Usage Considerations: • Describing Fixed-Length Records The RECORD CONTAINS length-fixed CHARACTERS form specifies that the file consists of fixed-length records. Both other forms specify that the file consists of variable-length records. If the record you write is smaller than the fixed length, the extra characters are undefined. If you declare a file for a terminal, you must specify variable-length records, or else each record entered must be exactly the same length. • Defaulting to Fixed-Length Records If no RECORD clause is present, the compiler declares the file to consist of fixedlength records. In this case, the record length is the size of the associated record description entry specifying the greatest number of character positions. • File With Fixed-Length Records Can Hold Records of Shorter Lengths If you describe a file as having fixed-length records, each record description for that file’s record area can describe a record of any length from 1 up to the stated fixed length. The length you specify in the RECORD CONTAINS clause is the fixed length of the record area that holds individual records read from or to be written to the file during execution. Each record description entry can define the record area in a different way, possibly describing a record of a shorter length than the actual record has in the record area or in the file. • Example of a File with Fixed-Length Records This explicitly declares a file to have fixed-length records: RECORD CONTAINS 256 CHARACTERS • Purpose of Variable-Length Records If you describe a file as having variable-length records, the individual record descriptions for that file can be of any length from the stated or implied minimum length to the stated or implied maximum length. The specified minimum size can be less than that implied by the record description entry defining the smallest number of character positions. The specified maximum size can be greater than that implied by the record description entry defining the largest number of character positions; however, only those character positions defined in the record descriptions are accessible to the program. If the record you write is smaller than the minimum length, the extra characters are undefined. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 20 Data Division • File Description Entries Depending Item When length-var is specified, the data item it references is called the depending item. ° Governs the length of the record to be written The contents of this item, evaluated just before the execution of a REWRITE or WRITE statement for the file, determine the size of the record to be written. ° Contains the length of the record after it has been read After the successful execution of a READ statement for the file, the contents of the depending item indicate the size of the item just read. The size is expressed in characters. The execution of a DELETE, RELEASE, REWRITE, START, or WRITE statement, or the unsuccessful execution of a READ statement, does not alter the contents of the depending item. • Establishing the Length of a Variable-Length Record When the run-time routines execute a REWRITE or WRITE statement referencing a file of variable-length records, the number of character positions in the record written is determined: ° If length-var is specified, by the content of the data item referenced by length-var. ° If length-var is not specified and the record does not contain a variableoccurrence data item, by the number of character positions in the record (as specified in the record description). ° If length-var is not specified and the record contains a variable-occurrence data item, by the sum of the size of the fixed portion and that portion of the table described by the number of occurrences at the time of execution of the output statement. Example 7-3. Variable-Length Record RECORD IS VARYING IN SIZE FROM 100 TO 144 CHARACTERS HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 21 Data Division File Description Entries LABEL RECORDS Clause Note. The 1985 COBOL Standard classifies the LABEL RECORDS clause as obsolete, so you are advised not to use it. On systems that support file labels, this clause specifies whether the file being described has labels or not. HP COBOL does not support labeling or label processing. If you want to use file labels, you must create your own and check them. LABEL RECORD STANDARD IS OMITTED RECORDS ARE VST083.vsd STANDARD specifies that standard system labeling conventions apply to the file. OMITTED specifies that no explicit labels exist for the file. Usage Considerations: • File Description Entry Without LABEL RECORDS Clause When a file description entry does not have a LABEL RECORDS clause, HP COBOL assigns the OMITTED attribute to the file. • STANDARD or OMITTED The choice of STANDARD or OMITTED is significant only for files residing on tape. • LABEL RECORDS Clause With MULTIPLE FILE TAPE Clause When the LABEL RECORDS clause appears in the file description entry of any file name mentioned in a MULTIPLE FILE TAPE clause, the specified labeling convention must apply to all of the file names mentioned in that clause. In practical terms, this means that every file name appearing in a particular MULTIPLE FILE TAPE clause must be described with the LABEL RECORDS STANDARD clause if any of them are so described. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 22 Data Division File Description Entries VALUE OF Clause Note. The 1985 COBOL Standard classifies the VALUE OF clause as obsolete. HP COBOL does not support the VALUE OF clause. If this clause is present, the compiler checks its syntax and issues a warning. VALUE OF label-value label-name OF VST084.vsd label-name is a COBOL word. label-value is either a literal or a COBOL word. DATA RECORDS Clause Note. The 1985 COBOL Standard classifies the DATA RECORDS clause as obsolete, so you are advised not to use it. Use the optional DATA RECORDS clause to enumerate the names of the records that are defined for the file. Each data-name corresponds to one level-01 name in the record descriptions following the file description. The existence of more than one dataname indicates the file has more than one type of data record. These records can vary in size, format, and so on, and can be listed in any order. All data records within a file share the same memory area. DATA rec-name RECORD IS RECORDS ARE VST085.vsd rec-name is the name of a record that is to follow the file definition. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 23 Data Division File Description Entries Usage Considerations: • Correspondence Each rec-name specified in the DATA RECORDS clause must correspond to some level-01 name in the list of record description entries. Order is not important. The converse is not true; level-01 entries can exist among the record description entries without their names appearing in the DATA RECORDS clause. • FILLER Keyword and the DATA RECORDS Clause Although a record description can, except in certain circumstances, be named FILLER or have no name at all (the implicit FILLER), the name FILLER cannot appear as a rec-name in the DATA RECORDS clause. LINAGE Clause The LINAGE clause controls where data is printed on a page. Top and bottom margins and a body area with an optional footing area within it are defined in terms of the number of lines each has. LINAGE body IS LINES FOOTING foot AT WITH TOP LINES AT BOTTOM LINES top bottom AT VST086.vsd body is either an unsigned integer literal or the data-name of an elementary unsigned numeric integer data item. Its value is the number of lines that can be written on a logical page, so it must be greater than 0. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 24 Data Division File Description Entries foot is either an unsigned integer literal or the data-name of an elementary unsigned numeric integer data item. Its value is the line number within the page body at which the footing area begins, so it must be greater than 0 and not greater than the value of body. The default is body +1. top is either an unsigned integer literal or the data-name of an elementary unsigned numeric integer data item. Its value is the number of lines in the top margin of the logical page. The default is 0. bottom is either an unsigned integer literal or the data-name of an elementary unsigned numeric integer data item. Its value is the number of lines in the bottom margin of the logical page. The default is 0. Example 7-4. LINAGE Clauses LINAGE IS 60 LINES WITH FOOTING AT 51, LINES AT TOP 0, LINES AT BOTTOM 3 LINAGE IS NUMBER-OF-TEXT-LINES, LINES AT TOP TEXT-OFFSET, LINES AT BOTTOM REST-OF-PAGE HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 25 Data Division File Description Entries Usage Considerations: • The Logical Page The size of a logical page is the sum of the top and bottom margins and the body. The logical page is not necessarily the same size as the physical page. Figure 7-1. LINAGE Clause Layout Top Margin Top Body (Includes Footing) Body Footing Bottom Bottom Margin VST708.vsd • Restriction Because the purpose of the LINAGE clause is to control printing of data, it can be used only with files assigned to line printer devices or spooler processes. • Initial Positioning of First Logical Page Before printing the first logical page, a standard printer file issues a page eject, positioning itself at the fourth line of the physical page. The run-time routines cannot determine if a printer file behaves in the standard way or not; therefore, the run-time routines handle all printer files as if they do; therefore, when the LINAGE clause applies, the OPEN statement operates: ° If the value of top is 3 or more If the value of top is 3 or more, the run-time routines issue a page eject to establish a known initial position on the physical page. Because the run-time routines now expect the printer position to be at the fourth line (that is, 3 lines have already been skipped), they advance the printer by top - 3 lines. ° If the value of top is 2 or less If the value of top is 2 or less, the preceding strategy does not work, because the run-time routines cannot backspace the printer. The run-time routines HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 26 Data Division File Description Entries assume that the printer is positioned at the first line, omit the page eject, and advance the printer by top lines. Examples: Lines Skipped Value of top Page-Eject Issued? Additional Total 0 No 0 0 1 No 1 1 2 No 2 2 3 Yes (skips 3) 0 3 4 Yes (skips 3) 1 4 5 Yes (skips 3) 2 5 6 Yes (skips 3) 3 6 This logic applies only during initial positioning of the first logical page. The printer does not perform page ejects for subsequent pages, and the value of top is not modified. • Handling the First Logical Page Specially If you know that the printer file does not behave in the standard way, you can program around the situation described in Initial Positioning of First Logical Page. In simple cases, follow these steps: 1. In the LINAGE clause, specify a data item for top. 2. Initialize the data item with a value that produces the desired result for the first logical page (see Initial Positioning of First Logical Page). 3. Open the output file. 4. Change the value of the data item to the value of the “real” top margin. (You can do this even before the first WRITE statement.) In more complex cases, follow these steps: 1. 2. 3. 4. 5. In the LINAGE clause, specify a data item for top. Initialize the data item to 0. Open the output file. Use WRITE statements to position the first logical page properly. Change the value of the data item to the value of the “real” top margin. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 27 Data Division • File Description Entries Effect of body, foot, top, and bottom The description of the first logical page is determined from top, body, foot, and bottom when the file is opened by an OPEN statement with the OUTPUT phrase. If literals are used to define all these page areas, all logical pages have the same layout. If one or more of the values are data-names, then each time a WRITE statement with the ADVANCING PAGE phrase is executed or a page overflow occurs, the current value of the data-names is used to set up the next logical page. • Printing Device Does Not Space Each logical page continues to the next with no additional spacing from the printing device. • The LINAGE-COUNTER Special Register Every file description that has a LINAGE clause generates a special register called LINAGE-COUNTER. At any given time, LINAGE-COUNTER contains the value of the current line number within the current page body. A LINAGE-COUNTER can be read but not modified. If more than one file description contains a LINAGE clause, each reference to a LINAGE-COUNTER must be qualified by its file name. The value of LINAGE-COUNTER is automatically set to 1 when its file is opened. During execution of a WRITE statement to its file, LINAGE-COUNTER is automatically modified under these conditions: ° When the ADVANCING PAGE phrase of a WRITE statement is encountered, LINAGE-COUNTER is reset to 1. ° When the ADVANCING phrase is specified in a WRITE statement, LINAGECOUNTER is increased by the number of lines given. ° When the ADVANCING phrase of the WRITE statement is not used, LINAGECOUNTER is increased by 1. ° When execution of a WRITE statement repositions the file to the first line in the page body of the next logical page, LINAGE-COUNTER is reset to 1. If the file description entry containing the LINAGE clause includes the EXTERNAL clause as well, the file then has the external attribute. In this case, the LINAGECOUNTER special register is also an external data item. Execution of a WRITE statement for such a file by any programs that share access to the file modifies the same unique special register. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 28 Data Division File Description Entries CODE-SET Clause The CODE-SET clause specifies the character code convention used to represent data on the external media supporting the file. alphabet-name CODE-SET IS VST087.vsd alphabet-name is the character set used to represent data on external media. It determines the way external codes are converted to native character codes during input and output operations. It must be defined in the SPECIAL-NAMES paragraph to be STANDARD-1, STANDARD-2, or NATIVE (all of which designate the ASCII character set), or a system-name predefined by HP COBOL as an alternate alphabet name. The only such system-name is EBCDIC. Usage Considerations: • Sequential Files Only You can specify the CODE-SET clause only for sequential files that do not have alternate keys. On files associated with the $RECEIVE device, the CODE-SET clause has no effect. • Action of CODE-SET EBCDIC The presence of the CODE-SET clause causes translation between the native USASCII character code convention and the EBCDIC code convention for all input and output operations, regardless of the type of the device associated with the sequential file. If you specify CODE-SET EBCDIC in the file description associated with a printer, EBCDIC codes are delivered to the printer (which may or may not be prepared to accept EBCDIC codes). The most common use for CODE-SET EBCDIC is for reading or writing tapes for interchange with an EBCDIC-based system. • Restrictions Established by the CODE-SET Clause When the CODE-SET clause appears, it places these restrictions on all data items defined in the record description entries associated with the file description entry: ° ° Some SIGN SEPARATE clause must apply to every signed numeric data item Every data item must be USAGE DISPLAY. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 29 Data Division Sort-Merge File Description Entries REPORT Clause HP COBOL does not support the report-writing feature of ISO/ANSI COBOL. If the REPORT clause is present, the compiler checks it for syntactic validity and reports an error. report REPORT IS REPORTS ARE VST088.vsd report is irrelevant. Sort-Merge File Description Entries Each SORT or MERGE operation refers to a sort-merge file. The sort-merge file description (SD) describes the size, structure, and names of data records in a sortmerge file. A sort-merge file description must begin with sort-merge file description followed by a file name. The optional clauses can follow in either order. A period ends the whole entry. One or more record descriptions must then follow. No input-output statements can be executed for this type of file. The system-file-name specified in the filecontrol entry associated with this file identifies the sort-merge scratch file or volume. file-name . RECORD CONTAINS clause DATA RECORDS clause VST089.vsd file-name is the highest qualifier for both the sort-merge file description entry and its records. It must be unique within the program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 30 Data Division Sort-Merge File Description Entries RECORD CONTAINS clause CONTAINS phrase RECORD VARYING phrase VST090.vsd CONTAINS phrase length-fixed CONTAINS length-min TO length-max CHARACTERS VST091.vsd VARYING phrase VARYING IS IN length-min SIZE CHARACTERS FROM TO length-max length-var DEPENDING ON VST092.vsd length-min length-max length-var are integer values as in the file description entry. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 31 Data Division Data Description Entries DATA RECORDS clause RECORD DATA data-name IS RECORDS ARE VST093.vsd data-name is the name of a record that is declared following the sort-merge file description entry. One or more fields of those records are used as keys in SORT and MERGE statements. Usage Consideration: Only the DATA RECORD and RECORD CONTAINS (or RECORD VARYING) clauses are valid. For descriptions of these clauses, see File Description Entries. In Example 7-5, the record description entry associated with the sort-merge file description entry defines CUSTOMER-NAME, CUSTOMER-ADDRESS, and CUSTOMER-ZIP. These data items can be used as sort-merge keys. Example 7-5. Sort-Merge File Description Entry SD SORT-THIS RECORD CONTAINS 80 CHARACTERS DATA RECORD IS SORT-TEMPLATE. 01 SORT-TEMPLATE. 05 CUSTOMER-NAME PIC X(35). 05 FILLER PIC X(35). 05 CUSTOMER-ADDRESS PIC X(55). 05 CUSTOMER-ZIP PIC 9(15). ... Data Description Entries Data description entries in the File Section describe record areas associated with files. Each level-01 data description entry is a record description entry that describes the record area for the file named in the preceding file description entry or sort-merge file description entry. If multiple record description entries follow an file description or sortmerge file description entry, each record description entry after the first one is a redefinition of the record area. See Descriptions of Records (Levels 01-49). You can use level-66 data description entries to rename contiguous items in a record and level-88 data description entries to assign condition-names to values of record items. See Descriptions That Rename Items (Level 66) and Descriptions of ConditionNames for Values (Level 88). You cannot put level-77 data description entries in the File Section. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 32 Data Division Working-Storage Section Working-Storage Section The Working-Storage Section defines records and miscellaneous data items for the process to use. You can set the initial values of most data items in working storage. When a process does not need local data items or explicit intermediate storage to execute the run unit, you can omit the Working-Storage Section. WORKING-STORAGE SECTION . 01-data-description 77-data-description 66-or-88 VST094.vsd 01-data-description 77-data-description describe data items for the process to use (for details, see Data Description Entries). You can specify initial values for most of these data items (see Initializing Data Items). There is no difference between level-77 items and elementary level-01 items, and the latter are preferred. There are limits to the number of records and level-77 items that a program can contain. See Section 18, HP COBOL CRE Support. 66-or-88 is a level-66 or level-88 description. For syntax, see Descriptions That Rename Items (Level 66) and Descriptions of Condition-Names for Values (Level 88). HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 33 Data Division Data Description Entries Data Description Entries The data description entries for unrelated items (level-77 items) or records or both follow the Working-Storage Section header. Record-names, level-77 item names, and subordinate data-names are not required to be unique within the program except in these cases: • • A data-name that is referenced in the program and cannot be uniquely designated by including qualifying names in the reference cannot be uniquely designated by including qualifying names in the reference (the reference is diagnosed, not the data-name) A data-name for a language element whose syntax mandates uniqueness; for example, the level-01 names of external data items If data items have hierarchical relationships to one another, you must group them into records according to the rules for record descriptions. All clauses available for record descriptions in the File Section are available for record descriptions in the WorkingStorage Section. See Descriptions of Records (Levels 01-49). If elementary data items bear no relationship to any other items, you do not need to group them into records. You can define each as a noncontiguous item with level number 77, followed by a data-name and a PICTURE or USAGE clause. Other data description clauses are optional for noncontiguous items; you can use other clauses to complete an item’s description when necessary. You do not have to put level-01 items (records) and level-77 items in any special order in the Working-Storage Section; however, if you are planning working storage for a program to be run as a process pair, see Checkpointing for a recommended approach that simplifies checkpointing. You can also use level-66 data description entries to rename contiguous items in a record (see Descriptions That Rename Items (Level 66)) and level-88 data description entries to assign condition-names to values of items (see Descriptions of ConditionNames for Values (Level 88)). HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 34 Data Division Data Description Entries In Example 7-6, the Working-Storage Section has five record description entries. Example 7-6. Record Description Entries WORKING-STORAGE SECTION. 01 DATA-TO-CHECKPOINT. 05 USER-INPUTS. 10 COMMAND-IN 10 TRAN-CODE 10 REPORT-TO-PRINT 10 REPORT-NUMBER 05 PERFORM-FLAGS 88 BAD 88 GOOD 01 01 CURRENT-DATE. 05 CURRENT-YEAR 05 CURRENT-MONTH 05 CURRENT-DAY PICTURE PICTURE PICTURE PICTURE PICTURE REPORT-HEADING-1. 05 FILLER 05 REPORT-MM 05 FILLER 05 REPORT-DD 05 FILLER 05 REPORT-YY 05 REPORT-YY 05 FILLER ... PICTURE 99 PICTURE 99 PICTURE 99 PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE X(8) VALUE 999 VALUE 99 VALUE 99 VALUE 9. VALUE 0. VALUE 1. SPACES. ZERO. ZERO. ZERO. X(7) 99. X 99. X 99. 99. X(7) VALUE ZERO. VALUE ZERO. VALUE ZERO. VALUE SPACES. VALUE "/". VALUE "/". VALUE SPACES. 01 MONTH-ABBREVIATIONS VALUE "JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC". 03 MON-ABBR PIC X(3) OCCURS 12 TIMES. 01 CONSTANTS-FOR-I-O. 05 ERROR-MSG-CONST ... 01 PICTURE X(13) VALUE "*** ERROR ***". CONSTANTS-FOR-LOGIC. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 35 Data Division Initializing Data Items Initializing Data Items The value to which a data item is initialized is determined by: • EXTERNAL clause A data item described with an EXTERNAL clause (an external data item) cannot have a VALUE clause and is not affected by events that cause internal data items to be initialized. Its contents are unpredictable until a program assigns a value to it. Thereafter, it retains the last value assigned to it throughout the current execution of the run unit. • VALUE clause With some exceptions, you can set the initial value of an internal data item by including a VALUE clause in its data description entry (for exceptions, see VALUE Clause). • BLANK and NOBLANK directives When a data item is not described with a VALUE clause, the BLANK or NOBLANK directive determines its initial value (see BLANK and NOBLANK). An internal data item is initialized at each of these times: • • • The first time the program is executed. The first time the program is called after a CANCEL statement that references it has been executed, unless a NOCANCEL directive affects the program. Every time the program is called, if the program is an initial program (see Initial Programs). The NOCANCEL directive does not affect initial programs. Once initialized, an internal data item retains the last value assigned to it throughout the current execution of the run unit, unless an event that causes internal data items to be reinitialized occurs. In that case, the data item is reassigned its initial value if it has a VALUE clause or if a BLANK directive is active; if not, its contents are unpredictable. Size Limits In Section 20, HP COBOL Limits, see Data in a run unit. Checkpointing You do not have to put level-01 items (records) and level-77 items in any special order in the Working-Storage Section; however, when you plan working storage for a program to be run as a process pair, this approach simplifies checkpointing: • • Group all independent data items into a record, and code the record in the same part of the Working-Storage Section as other level-01 items. Reserve level-77 items for constants, and code them last. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 36 Data Division Extended-Storage Section Extended-Storage Section Note. TNS/R HP COBOL does not need an Extended-Storage Section. The NMCOBOL compiler handles any data items that are described in the Extended-Storage Section as if they were described in the Working-Storage Section, without issuing a warning. The Extended-Storage Section is similar to the Working-Storage Section, but it describes data to be stored in the single area of extended memory each program can address on a NonStop operating system. To have storage allocated for a data item in the area of extended memory, you must either declare the data item explicitly in this section or use the directive LARGEDATA. EXTENDED-STORAGE SECTION . 01-data-description 77-data-description 66-or-88 VST095.vsd 01-data-description 77-data-description describe data items for the process to use. You can specify initial values for most of these data items. See Data Description Entries and Initializing Data Items. There are limits to the number of records and level-77 items that a program can contain. See Section 20, HP COBOL Limits. 66-or-88 is a level-66 or level-88 description. For syntax, see Descriptions That Rename Items (Level 66) and Descriptions of Condition-Names for Values (Level 88). The Extended-Storage Section, if present, must appear after any Working-Storage Section. A program can have both sections, either section without the other, or neither section. Data Description Entries and Initializing Data Items Data description entries and data initialization rules are the same in the ExtendedStorage Section as they are in the Working-Storage Section. See Data Description Entries and Initializing Data Items. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 37 Data Division Addressing Addressing Items described in the Extended-Storage Section are accessed using 32-bit addressing. Extended-storage items are allocated in a single extended data segment, which is managed entirely by the run-time routines. Instructions that involve 32-bit addresses consume more space in the object file and execute at a slightly slower speed than the instructions that involve 16-bit addresses. Size Limits In Section 20, HP COBOL Limits, see Data in a run unit. Checkpointing If your program is compiled with the COBOL85 compiler and the ENV COMMON directive, the CHECKPOINT statement can process data items declared in the Extended-Storage Section. Linkage Section The Linkage Section describes data passed from a calling program to the program containing the Linkage Section. No local data space is used for these items because they refer to existing items in the calling program. LINKAGE SECTION . 01-data-description 77-data-description 66-or-88 VST096.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 38 Data Division Data Description Entries and Initializing Data Items 01-data-description 77-data-description are described under Working-Storage Section, except that each data description entry can include this clause: ACCESS MODE IS EXTENDED-STORAGE STANDARD VST097.vsd 66-or-88 is a level-66 or level-88 description. For syntax, see Descriptions That Rename Items (Level 66) and Descriptions of Condition-Names for Values (Level 88). Topics: • • • • • Data Description Entries and Initializing Data Items ACCESS MODE Clause CALL Statement and USING Phrase Index-Names Absent Linkage Section Data Description Entries and Initializing Data Items Data description entries and data initialization rules are the same in the Linkage Section as they are in the Working-Storage Section, except that you can use the VALUE clause only for level-88 items. For information on using the VALUE clause in the Linkage Section, see Descriptions of Condition-Names for Values (Level 88). For information on data description entries and data initialization rules, see Data Description Entries, Initializing Data Items. ACCESS MODE Clause The ACCESS MODE clause describes the addressing method used to access parameters passed to the program—STANDARD or EXTENDED-STORAGE. You can specify the ACCESS MODE clause only in level-01 through level-49 and level-77 data description entries in the Linkage Section. ACCESS MODE IS EXTENDED-STORAGE STANDARD VST097.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 39 Data Division CALL Statement and USING Phrase EXTENDED-STORAGE specifies extended (32-bit) addressing. This is the default. STANDARD specifies standard (16-bit) addressing. STANDARD cannot be specified for a program that is to be called with a CALL identifier statement. The compiler cannot check for this, so the result of such a call is undefined. Note. If you specify STANDARD in a TNS/R program, the NMCOBOL compiler issues a warning and uses 32-bit addressing. Usage Considerations: • STANDARD Access Mode and the CALL Statement If a formal parameter (in the called program) has STANDARD access mode, the CALL statement (in the calling program) cannot pass it an actual parameter that has EXTENDED-STORAGE access mode (the default) and was declared in the calling program’s Extended-Storage Section or Linkage Section. Also, the called program’s object must be available to the compiler when the calling program is compiled (see CALL). The only advantage to STANDARD is slightly more efficient access in the called program. • Extended Addressing and the CALL Statement If a formal parameter (in the called program) has EXTENDED-STORAGE access mode (the default), a CALL statement (in the calling program) can pass it any actual parameter defined in the calling program’s Data Division. • Access Mode Heritability Subordinate items inherit the access mode of their parent. If a record has no ACCESS MODE clause or has an ACCESS MODE EXTENDED-STORAGE clause, no element of that record can have STANDARD access mode. If a record has an ACCESS MODE STANDARD clause in its description, no element of that record can have EXTENDED-STORAGE access mode. CALL Statement and USING Phrase The Linkage Section is required when parameters are passed from a calling program to a called program, which is signaled by the presence of a USING phrase in the Procedure Division header of the called program. The data items named in the CALL statement of the calling program correspond with the data items named in the USING phrase of the Procedure Division header of the called program. For details, see CALL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 40 Data Division CALL Statement and USING Phrase Statements within the Procedure Division of the called program can refer to any items defined in the Linkage Section of the program. Global items can be referenced by contained programs. The Linkage Section can contain matched and unmatched items. Matched items are those within a record that is specified in the USING phrase of the Procedure Division header, within a record that is a redefinition of a matched record, a level-77 item or a record that is in the USING phrase, or a redefinition of those. An unmatched item is one not associated with the USING phrase. The PORT directive determines the action taken for a reference to an unmatched item. If the program was not compiled with the PORT directive, the compiler issues a warning for any unmatched record or level-77 item. A reference to an unmatched item can cause abnormal program termination, data corruption, or other failures. If the program was compiled with the PORT directive, the SET ADDRESS OF statement can make unmatched items accessible. A reference to an unmatched item for which no address was set can cause abnormal program termination, data corruption, or other failures. Example 7-7. Correspondence Between Formal and Actual Parameters These lines are in the calling program: WORKING-STORAGE SECTION. 01 PARAMETER-TABLE. 02 ROW-PART OCCURS 20 TIMES. 03 COL-PART PIC 9999 COMPUTATIONAL OCCURS 10 TIMES. ... 77 ROW PIC 99 COMPUTATIONAL. 77 COL PIC 99 COMPUTATIONAL. ... PROCEDURE DIVISION. ... CALL "SUBPROG1" USING ROW, COL, PARAMETER-TABLE. ... These lines are in the called program: LINKAGE SECTION. 01 PARM-3-IN-OUT. 04 FORMAL-ROW OCCURS 20 TIMES. 07 FORMAL-COLUMN PIC 9999 COMPUTATIONAL OCCURS 10 TIMES. 77 PARM-R PIC 99 COMPUTATIONAL. 88 ROW-WITHIN-RANGE VALUE IS 1 THROUGH 20. 77 PARM-C PIC 99 COMPUTATIONAL. 88 COLUMN-WITHIN-RANGE VALUE IS 1 THROUGH 10. ... PROCEDURE DIVISION USING PARM-R, PARM-C, PARM-3-IN-OUT. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 41 Data Division Index-Names Index-Names A Procedure Division reference to a Linkage Section data item in the called program refers to a location in the calling program; however, this convention does not extend to index-names. The index-name of a table in the calling program and the index-name of a table in the called program always refer to separate indexes. This remains true even when the names of the indexes are the same in the calling program and the Linkage Section of the called program. An index-name’s value can be passed if it is saved in a separate item and then passed. (See the example under CALL.) Absent Linkage Section If there is no Linkage Section in the called program, it looks like a main program to the compiler. If you compile a main program and a subprogram with no parameters in the same compilation session, you must include either a MAIN directive or an empty Linkage Section to tell the compiler which program is the main one (see Main Programs). If you do neither, the compiler reports that it found two main programs. Because the compiler interprets subprograms that have no parameters as main programs, if you want to compile a collection of such subprograms, you need to direct the compiler not to attempt to give any of them the main attribute. To do this, use a MAIN directive specifying a program-name that does not correspond to the name of any program in the compilation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 42 Data Division Descriptions of Records (Levels 01-49) Descriptions of Records (Levels 01-49) A data description entry that starts at level-01 is a record description entry. It defines the characteristics of a record, and is followed by subordinate data description entries for items that are part of the record. You can put record description entries in any section in the Data Division. . level data-name-1 FILLER REDEFINES clause EXTERNAL clause GLOBAL clause PICTURE clause USAGE clause SIGN clause OCCURS clause SYNCHRONIZED clause JUSTIFIED clause BLANK WHEN ZERO clause VALUE clause VST098.vsd level is a 1-character or 2-character string whose value is in the range “1” (or “01”) to “49,” which represents the record’s level number. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 43 Data Division General Considerations data-name-1 is an alphanumeric data item whose value is the name of the record you are describing. FILLER is a place holder for a record to which the program never refers. This is the default. General Considerations These considerations apply to all record descriptions: • Data Items Must be Defined You must define every data item the source program uses (except the special registers) with an appropriate data description entry in the Data Division. The forms specified in this topic include: • ° When the data item is a logical record associated with a file, you must define it in a level-01 data description entry associated with the file description entry for the file of which it is a record. ° When the data item is a logical record that is not associated with a file, you must define it in a level-01 data description entry in the Linkage, WorkingStorage, or Extended-Storage Section. ° When the data item is an independent elementary data item, you must define it in a level-01 or level-77 data description entry in the Linkage, Working-Storage, or the Extended-Storage Section. ° When the data item is a subordinate part of a record, you must define it in a data description entry (with a level number in the range 02 through 49) associated with the appropriate record description entry. ° When the data item is a redefinition of another item, you must define it in a data description entry (with the same level number as the item it redefines) associated with the appropriate record description entry or level-77 data description entry. ° The syntax and semantics of entries with level numbers 66 and 88 are explained in later topics of this section. Constraints on Clauses of the Data Description Entry Each data description entry must begin with the level number. If a data-name or the keyword FILLER is specified, it must immediately follow the level number. The characteristics of the data item determine which of the clauses are required or optional. Clauses that appear can do so in any order. No clause can appear more than once. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 44 Data Division ° General Considerations Data Name or FILLER Keyword If the data-name appears, it specifies the name of the data item being described. You can give an entry a name so that the name can be used to refer to the entry. If you do not need to refer to the entry, you can give it the name FILLER, or omit the name entirely. Such unnamed or FILLER items act as place holders in records where not all the fields are referred to or as convenient names for constants, such as in report headings. When the level number is 01, the data item is a record, and the data-name is sometimes referred to as a record-name. In this case, the data-name must be specified if the data description entry contains the EXTERNAL clause or if the data description entry is associated with a file description entry that contains the EXTERNAL clause. If neither the data-name nor the keyword FILLER is specified, it is as if the keyword FILLER had been specified. When the level number is 77, the data item is an independent (or noncontiguous) elementary data item, and the data-name (not FILLER) must always be specified. ° REDEFINES Clause The REDEFINES clause, when it appears, must immediately follow the dataname or FILLER keyword. If it does not, the compiler issues a warning, because COBOL requires REDEFINES to precede all other clauses. ° EXTERNAL Clause The EXTERNAL clause can be specified only for data description entries within the Working-Storage or Extended-Storage Sections whose level number is 01. It cannot be specified in a data description entry containing a REDEFINES clause. ° PICTURE Clause The PICTURE clause must be specified for every elementary item except these, which must not have PICTURE clauses: ° ° ° Indexes (described only in INDEXED phrases) ° Data items declared by RENAMES clauses Data items described as USAGE INDEX, USAGE NATIVE-n, or USAGE POINTER USAGE Clause The USAGE clause cannot be used for national data items. ° SIGN Clause The SIGN clause cannot be used for national data items. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 45 Data Division ° General Considerations SYNCHRONIZED Clause The SYNCHRONIZED clause cannot be used for national data items. ° BLANK WHEN ZERO Clause The BLANK WHEN ZERO clause cannot be used for national data items. • Clauses Applying Only to Elementary Data Items The PICTURE, SYNCHRONIZED, JUSTIFIED, and BLANK WHEN ZERO clauses can be specified only for an elementary data item. • Allocation of Storage ° Elementary Items The description of an internal elementary item in the Working-Storage Section or Extended-Storage Section causes allocation of storage space for that item unless that item redefines another item, in which case that item shares the redefined item’s storage space. The description of an external elementary item causes allocation of storage space for that item in space belonging to the run unit, outside the storage area of any individual program. This space is shared by all programs that describe the external data item. ° Linkage Items The description of an elementary item in the Linkage Section does not cause its allocation. In this case, the item is allocated by some other program, or by the run unit, and is made available to the current program with the SET statement or the CALL statement that causes its execution. ° Data Structures The description of a data structure in the Working-Storage Section or Extended-Storage Section does not cause any direct allocation, because its data-name merely designates the combined storage spaces of all the elementary items subordinate to it; however, the storage alignment requirements of some elementary items can cause the generation of implicit FILLER items whose storage space also belongs to the containing data structures (for details, see SYNCHRONIZED Clause). ° Data Items in the File Section Technically, the data description entries in the File Section only establish descriptions of data items in record areas—they are not declarations in the purest sense. If the file description does not establish a record length, the longest data description entry associated with it does so. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 46 Data Division ° General Considerations Relationship with File Description Entries In the File Section, data description entries that describe records follow file description entries or sort-merge file description entries. The file description or sort-merge file description entry is not part of the data description entry (see Example 7-8). The record description entry defines a record area associated with the file named in the file description entry. Note. Any File Section record you describe cannot exceed 32,767 bytes. At execution time, records for $RECEIVE files cannot exceed 32 KB (see RECEIVE-CONTROL Paragraph). For input and output operations on NonStop systems, the actual record-length limit for individual devices depends on the operating system limits. Example 7-8. File Description Entry Followed by Record Description Entry FD SAMPLE-FILE LABEL RECORDS ARE OMITTED. 01 SAMPLE-RECORD. 05 STORE-ID. 10 STORE-NUMBER 10 STORE-REGION 88 NORTHERN 88 SOUTHERN 05 STORE-MANAGER 05 STORE-ADDRESS. 10 STREET 10 CITY 10 ZIP-CODE PIC 999. PIC X. VALUE "N". VALUE "S". PIC X(35). PIC X(25). PIC X(15). PIC 9(5). In the other sections of the Data Division, record description entries are data declarations, as in Example 7-9. The level-77 entry is a description of a data item that is not part of a record. See Descriptions of Noncontiguous Elementary Items (Level 77). Example 7-9. Record Description Entries as Data Declarations 01 77 MEDICATIONS. 03 BRAND-NAME PICTURE X(50). 03 SIZE-IN-MG PICTURE 9999V99. 03 CONTRA-COUNT PICTURE 99. 03 CONTRAINDICATIONS OCCURS 1 TO 25 TIMES DEPENDING ON CONTRA-COUNT PICTURE X(50). I-DEX PICTURE 9999 USAGE IS COMPUTATIONAL VALUE IS ZERO. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 47 Data Division FILLER Keyword FILLER Keyword The FILLER keyword, explicit or implicit, substitutes for a data-name when it is not important that an item have a name. It is allowed on elementary or data structures. Commonly, FILLER is used when you build records in the Working-Storage Section or Extended-Storage Section for heading lines or error messages, where most of the text is groups of literals. Example 7-10. FILLER Keyword WORKING-STORAGE SECTION. 01 HEAD-1. 05 FILLER PIC X(10) VALUE "PART NUM". 05 FILLER PIC X(25) VALUE "DESCRIPTION". 05 FILLER PIC X(30) VALUE SPACES. 05 FILLER PIC X(15) VALUE "UNITS ON HAND" 01 BAD-NEWS. 02 THE-VALUES. 05 PIC X(45) VALUE "That part number is invalid.". 05 PIC X(45) VALUE "That job code is invalid.". 05 PIC X(45) VALUE "That delivery date is a holiday.". ... 02 THE-MESSAGES REDEFINES THE-VALUES. 05 ERR-MESSAGE PIC X(45) OCCURS 15 TIMES. Data items designated as FILLER can be conditional data items. This means that a FILLER item can be followed by one or more level-88 items describing conditionnames that have the value TRUE when the FILLER item contains a certain value. REDEFINES Clause The REDEFINES clause enables you to describe the same computer storage area in more than one way. This can be quite valuable for tasks such as input data validation, when tests require different descriptions of the data. It is also convenient when some portions of a record are constant, while other parts vary. REDEFINES data-name-2 VST102.vsd data-name-2 is the name of the existing data item that is being redefined as data-name-1. In Example 7-11, the two records RECORD-IN and RECORD-TOTAL share the same storage space, but their fields are different. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 48 Data Division REDEFINES Clause Example 7-11. REDEFINES Clause WORKING-STORAGE SECTION. 01 RECORD-IN. 05 RECORD-CODE 05 RECORD-DETAIL 05 RECORD-SUBTOTAL 01 RECORD-TOTAL REDEFINES 05 TOTAL-1 05 TOTAL-2 05 TOTAL-3 05 TOTAL-4 05 TOTAL-5 PIC 9. PIC X(30). PIC 9(3)V99. RECORD-IN. PIC 9(5)V99. PIC 9(5)V99. PIC 9(5)V99. PIC 9(5)V99. PIC 9(6)V99. Usage Considerations: • Determining Size of Shared Storage Area When the redefined item is a record item and one or more redefinitions specify a different number of character positions than the redefined item (either greater or lesser), the size of the shared storage area is determined by the requirements of the largest associated record item. • Elementary items or Data Structures Can Be Redefined You can describe an elementary data item and follow that description with a redefinition entry. You can also describe a data structure and follow that description first with descriptions of its component elementary items (with numerically higher level numbers), then with a redefinition entry that redefines the data structure. Redefinition continues until the appearance of a level number less than or equal to that of the data-name being redefined (or the ending of the current section of the Data Division). • Series of Redefinitions You can describe a series of redefinition entries with the same level number as that of the redefined entry, provided that each of these entries also contains a REDEFINES clause specifying the data-name of the redefined item. You cannot, however, separate a redefinition entry from the redefined entry by any data description entry with a numerically lower level number. • No Redefinitions of Level-66 or Level-88 Items Data items of level 66 (RENAMES) and 88 (condition-name) cannot be redefined. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 49 Data Division • REDEFINES Clause Redefined Item Cannot Include OCCURS or REDEFINES The description of data-name-2 cannot include an OCCURS clause or REDEFINES clause; however data-name-2 can be subordinate to an item containing one or both clauses, and items subordinate to data-name-2 can contain one or both clauses. Because an OCCURS clause can occur in the description of data-name-1, it is common to declare a record first and then to declare an array that redefines the same storage. Neither the original definition nor the redefinition can include an item whose size is variable due to an OCCURS clause of a subordinate entry. • No Subscripting or Qualifying in REDEFINES The REDEFINES declaration cannot include any subscripting or qualification on data-name-2. Qualification is automatic. • VALUE Clauses Only in Condition-Name Descriptions VALUE clauses are not permitted in the redefinition except as part of a conditionname declared in conjunction with a conditional variable in the redefinition. • Restrictions on Level Numbers The level number of a data description entry with a REDEFINES clause can be 01 in the Working-Storage Section, Extended-Storage Section, or Linkage Section but not in the File Section (where consecutive level-01 items are always multiple definitions of the same storage space). When the level number is other than 01, the redefinition must specify a number of character positions (bytes) that is less than or equal to the number of character positions in the data item being redefined. • Redefinitions Must All Specify Same Redefined Item The REDEFINES clause redefines a storage area, not the data items occupying the area. Multiple redefinition of the same record area is permitted, but each instance of data-name-2 must designate the name of the entry that originally defined the area. • The EXTERNAL Clause and the REDEFINES Clause The redefinition entry cannot contain the EXTERNAL clause. When the redefined item is an external record item or is described with a level number other than 01, the redefinition can specify the same or fewer character positions (bytes) than the redefined item, but cannot specify more. When the redefined item is a record (that is, has a level number of 01) without the EXTERNAL clause, there is no such constraint. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 50 Data Division • REDEFINES Clause Complete Description of Restrictions on Entry Order The first redefinition of a data item must begin immediately after the last data description entry associated with that item. Additional redefinitions can appear immediately after the first one in any convenient order. Each redefinition begins with the data description entry that contains the REDEFINES clause and continues with any other entries needed to define the subordinate data items or conditionnames that complete it. That is, the scope of the redefinition continues until the appearance of a level number less than or equal to that of the data-name being redefined, or to the end of the current section of the Data Division; therefore, the set of data description entries that describe a data item and its redefinitions must appear in a continuous sequence within either a single record description or, if the level number of the redefined item is 01 or 77, a single section of the Data Division. • Multiple Redefinitions The REDEFINES clause associates the redefinition data item with the same storage area occupied by the redefined data item. Because more than one redefinition can make reference to the same redefined item, the same storage area can be described in as many ways as required by the logic of the containing source program. Although the REDEFINES clause associates multiple data description entries with one storage area, the data items described by these entries are independent in all other respects; therefore, the actual content of the shared storage area at any particular time does not necessarily represent a valid value for all of the associated data items. • Alignment and the REDEFINES Clause The location of data items within a record can be affected by their storage alignment requirements (see SYNCHRONIZED Clause). When a redefinition item is an elementary item, its first character position must coincide with the first character position of the redefined item. The compiler issues a diagnostic message if the item’s alignment requirements make this impossible. When a redefinition item is a data structure, the first character position of its initial contained elementary item must coincide with the first character position of the redefined item. The compiler issues a diagnostic message if alignment requirements of the elementary item make this impossible. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 51 Data Division EXTERNAL Clause EXTERNAL Clause The EXTERNAL clause specifies that a record data item is external. This item and all of its subordinate data items are available to every program in the run unit that describes that record. EXTERNAL IS VST075.vsd Usage Considerations: • Working-Storage Section and Extended-Storage Section Records Only Only data description entries within the Working-Storage Section or ExtendedStorage Section whose level number is 01 can include an EXTERNAL clause. In this case the data-name must be specified; it cannot be omitted or replaced with the keyword FILLER. Within the same source program, you cannot define a specific data-name in more than one level-01 entry described with an EXTERNAL clause. You cannot specify the EXTERNAL clause in a data description entry that contains the REDEFINES clause. • Not With VALUE Clause You must not specify the VALUE clause in any data description entry that includes, or is subordinate to an entry that includes, the EXTERNAL clause. You can specify the VALUE clause for condition-name entries associated with the data description entries, however. • External Record The EXTERNAL clause specifies that the data item defined by this data description entry is external. Because this data item is a record data item, it is also referred to as an external record. All data items defined by subordinate data description entries, including any redefinitions, are also external. The data contained in the record identified by the record-name is external and can be accessed and processed by any program in the run unit that describes and, optionally, redefines it. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 52 Data Division GLOBAL Clause Within a run unit, if two or more programs describe the same external data record, then the associated data description entries (including all subordinate data-names and data items and their redefinitions) must be identical; however, a program that describes an external record can contain a data description entry including the REDEFINES clause that redefines the complete external record, and this complete redefinition need not occur identically in other programs in the run unit. Also, all descriptions must be in the same section; that is, a description cannot be in the Extended-Storage Section in one program and in the Working-Storage Section of another program. When a file description entry contains the EXTERNAL clause, the data items defined in its associated record description entries inherit the external attribute; therefore, the preceding rules apply to these record description entries as well as those defined in the Working-Storage Section and Extended-Storage Section. Example 2-2 contains an example of the use of the EXTERNAL clause. GLOBAL Clause The GLOBAL clause specifies that a data-name is a global name. A global name is available to every program contained within the program that describes it, even though the contained programs do not contain a description of it. GLOBAL IS VST076.vsd Usage Considerations: • Global Name Can be Used in Contained Programs A statement in a program contained directly or indirectly within a program that describes a global name can reference that name without describing it again. • Only for Level-01 Items The GLOBAL clause can be specified only in data description entries whose level number is 01 in the File Section, Working-Storage Section, or Extended-Storage Section. • Name Uniqueness Within a Single Program In the Data Division of any one program, the data description entries for any two data items for which the same data-name is specified must not include the GLOBAL clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 53 Data Division • PICTURE Clause Not With SAME RECORD AREA Clause If the SAME RECORD AREA clause is specified for several files, the record description entries or the file description entries for these files must not include the GLOBAL clause. • Global Attribute is Inherited A data-name described using a GLOBAL clause is a global name. All data-names subordinate to a global name are global names. All condition-names associated with a global name are global names. • Use With REDEFINES Clause If the GLOBAL clause is used in a data description entry that contains the REDEFINES clause, the global attribute applies only to the subject of the REDEFINES clause. Example 2-2 contains an example of the use of the GLOBAL clause. PICTURE Clause The PICTURE clause defines the characteristics and editing requirements of an elementary item. character-string PICTURE IS PIC VST103.vsd character-string is one or more symbols that determine the category of an elementary item, restrict the values that you can assign to the item, and define editing operations. These data items do not have PICTURE clauses: • • • • • An index (described only in an INDEXED phrase) A data item described as USAGE INDEX A data item described as USAGE NATIVE-n (where n is 2, 4, or 8) A data item described as USAGE POINTER A data item declared by a RENAMES clause HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 54 Data Division PICTURE Clause Usage Considerations: • Size of character-string The maximum number of characters in character-string is 30. To signify more than one consecutive instance of a picture character, you can write it once, followed by an unsigned integer in parentheses. The integer tells how many times that character is to occur. For example, PICTURE 99999 is equivalent to PICTURE 9(5). While a character-string can have at most 30 characters, using the repetition technique lets you define items longer than 30 characters. You cannot use this technique for characters that are limited to one occurrence in a PICTURE character-string. • Composition of character-string The meaning of each character used in a PICTURE character-string is peculiar to the PICTURE clause and is independent of any meaning assumed in other contexts. The character-string in a PICTURE clause consists of certain allowable combinations of symbols formed from the COBOL character set. The particular combination of symbols in the character-string determines the size, category, sign, and editing attributes of the elementary item that it describes. The symbols also specify any restrictions on the values that the program can assign to the item and any editing that COBOL is to perform in conjunction with an assignment. Most individual symbols serve two purposes: ° ° Represent character positions in the item value Describe the characteristics of these positions Some symbols merely contribute attribute information without defining character positions. Within the character-string, the presence of a symbol followed by a repetition factor has the same meaning as the presence of the symbol repeated the specified number of times. The symbols are shown in uppercase, but both uppercase and lowercase are effective. Table 7-2 lists and explains the symbols used to describe an elementary item. Table 7-2. PICTURE Character-String Symbols (page 1 of 3) Symbol Symbol Counts in Item’s Size A Yes Represents a character position for a letter or the space character. B Yes Represents a character position for a space character. N No Indicates that the picture string is a national data item. Description HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 55 Data Division PICTURE Clause Table 7-2. PICTURE Character-String Symbols (page 2 of 3) Symbol P Symbol Counts in Item’s Size No, but determines the maximum number of digit positions in numeric and numeric edited items. Description Indicates scaling when the decimal point is not within the number that appears in the data item. One or more P s can appear only as a string of contiguous characters to the left or right of all other digit positions in the character-string. Because P implies an assumed decimal point, V is redundant. P and the insertion character period (.) cannot be in the same character-string. In some operations that manipulate a data item whose character-string contains P, the algebraic value of the data item is used rather than the actual character representation of the data item. In this algebraic value, the decimal point is in the prescribed location and zero is in each digit position specified by P. The size of the value is the number of digit positions represented by the characterstring. These operations are any of: • • • Any operation requiring a numeric sending operand A MOVE statement where the sending operand is a numeric or numeric-edited data item, its characterstring contains P, and the receiving operand is numeric or numeric-edited A comparison operand where both operands are numeric In all other operations, the digit positions specified with P are ignored. S Only if you use a SIGN clause with a SEPARATE phrase Indicates that the picture string represents a signed numeric value. Only one S can appear in a character-string. If present, it must be the leftmost character. If no S is present, the item is unsigned. A negative value becomes positive if it is stored in an item that does not have an S. The location (leading or trailing) and representation (embedded or separate) attributes are specified in other clauses of the data description entry, not in the PICTURE clause (see SIGN Clause). V No Represents the assumed decimal point location in noninteger numeric items. Only one V can appear in a characterstring, and V cannot occur in the same characterstring with an explicit decimal point. X Yes Represents a character position that can contain any character from the ASCII character set. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 56 Data Division PICTURE Clause Table 7-2. PICTURE Character-String Symbols (page 3 of 3) Symbol Symbol Counts in Item’s Size Z Yes Represents a leading numeric character position whose contents are to be replaced by a space when it and all preceding numeric character positions are 0. All Zs must precede any 9 s within the character-string. 9 Yes Represents a character position for a digit. 0 Yes Represents a character position where the character zero (0 ) is to be inserted. , Yes Represents a character position where a comma (,) is to be inserted. A comma must not be the last (rightmost) character in the character-string. See note below. . Yes Represents the decimal point for alignment purposes. A period (.) is to be inserted at that position. The period must not be the last (rightmost) character in the characterstring and can only be used once. No V can occur in a PICTURE character-string containing an explicit decimal point. / Yes Represents a character position where a slash (/) is to be inserted. + CR DB Yes Sign-editing symbols. A character-string cannot have more than one sign-editing symbol. If it has one sign-editing symbol, the sign-editing symbol represents the position where the sign-control symbol goes. * Yes Represents a leading numeric character position that is to be replaced by an asterisk (*) if its contents and the contents of all preceding numeric character positions are 0. All asterisks must precede any 9 s. $ Yes Represents the character position where the currency symbol is to be placed. The dollar sign ($) is used unless a CURRENCY SIGN clause specifies another single character. Description Note. If you use the DECIMAL-POINT COMMA clause in the SPECIAL-NAMES paragraph in the Environment Division, periods function as commas, and commas function as periods. Neither the period nor the comma can be the last (rightmost) symbol of a PICTURE character-string ; with this exception: when the comma, semicolon, or period separator follows the character-string. In this case a preceding comma or period character is acceptable as the last symbol in the character-string ; for example: 999. 999., is “999” followed by a period separator is “999.” followed by a comma separator HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 57 Data Division • PICTURE Clause Precedence Rules Figure 7-2 shows the order of precedence for the symbols in a PICTURE character-string. An x at an intersection indicates that the symbol at the top of the column can precede the symbol at the left of the row. Where two symbols appear in a column or row, they are mutually exclusive within the same character-string. The comma (,) and period (.) insertion symbols can be reversed by the DECIMALPOINT COMMA clause (see DECIMAL-POINT Clause). The symbol cs represents the currency symbol. The nonfloating insertion symbols plus (+) and minus (-), the floating insertion symbols Z, asterisk (*), plus (+), minus (-), and cs, and the symbol P appear twice. The leftmost column and uppermost row for each symbol represents its use to the left of the decimal point position. The other appearance of the symbol represents its use to the right of the decimal point position. Each PICTURE character-string must contain at least one of the symbols A, N, X, Z, 9, or asterisk (*) or at least two of the symbols plus (+), minus (-), or cs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 58 Data Division PICTURE Clause Figure 7-2. Precedence Rules for PICTURE Symbols First Symbol Second Symbol NonFloating Insertion Symbols Nonfloating Insertion Symbols Other Symbols Floating Insertion Symbols Z Z * * + – + – cs cs 9 A S X V x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x B 0 / , . + – + CR cs – DB B x x x x x x 0 x x x x x / x x x x , x x x x . x x x x + - x x x x x CR DB x x x x x x x P P x + - cs Floating Insertion Symbols Other Symbols x Z * x x x x Z * x x x x + - x x x x + - x x x x cs x x x x cs x x x x x x 9 x x x x x x A X x x x V x x x x x x x x x x x x P x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x S P x x x cs = currency symbol VST525.vsd • Data Item Size A data item’s size is determined by the symbols of its PICTURE character-string. Each A, B, N, X, Z, 9, zero (0), slash (/), comma (,), period (.), plus (+), minus (-), asterisk (*), or currency symbol (usually the dollar sign ($)) counts as one character position. CR or DB counts as two character positions. S is one character only if the item is subject to a SIGN clause with a SEPARATE phrase. S, V, CR, and DB cannot appear more than once in a single character-string. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 59 Data Division PICTURE Clause A PICTURE character-string (or part of a PICTURE character-string) of the format symbol (integer) where symbol is any symbol allowed in a PICTURE character-string except P, is equivalent to a PICTURE character-string (or substring) of integer consecutive occurrences of symbol. For example, PICTURE X(4) is equivalent to PICTURE XXXX and PICTURE A(3)0A is equivalent to PICTURE AAA0A. The size of a DISPLAY item is determined by the PICTURE character-string symbols. COMPUTATIONAL and BINARY items deviate from the rules for DISPLAY items. See USAGE Clause. The amount of storage given to a data item can exceed its size if the SYNCHRONIZED clause is used; however, any excess bytes so allocated (called “implicit FILLER” bytes) belong not to the synchronized item but to its parent item. • Trapping Size Errors If a data item is described with a PICTURE clause, you must use the SIZE ERROR Phrase to trap size errors that occur because the result of a calculation exceeds the maximum number allowed by the PICTURE phrase. The SIZE ERROR phrase is especially important for COMPUTATIONAL and BINARY items, because without the SIZE ERROR phrase, you might not discover until much later that a value larger than that allowed by the PICTURE was stored as the result of a computation. • Categories of Data Items The PICTURE clause can describe these categories of data items: ° ° ° ° ° ° Alphabetic Numeric Alphanumeric Alphanumeric edited Numeric edited National The results of most statements in the Procedure Division depend on the categories of the data items. Some statements disallow certain categories for some or all of their operands. In other cases, the same statement can take distinctly different actions when applied to data items of different categories. In the remainder of this topic, 9 s and A s within the PICTURE character-string are described as representing character positions that contain only numbers or letters and spaces. For greater efficiency, the HP COBOL compilers do not always enforce this restriction. Characters other than those permitted can be moved into these positions if they appear in the corresponding positions of a sending data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 60 Data Division PICTURE Clause Because the COBOL language considers every data structure to be in the alphanumeric category, manipulations upon data structures ignore all PICTURE constraints of their constituent elementary items, including editing specifications. As an extreme (but quite legal) example, an assignment to a containing data structure can cause any character position of an elementary item to assume any character. If numeric items contain nonnumeric characters, the results of using them in numeric operations are undefined. • Alphabetic Data Items An item is in the alphabetic category when its PICTURE character-string contains only A s. The contents of this type of item are represented externally as some combination of the 26 (uppercase or lowercase) letters of the alphabet and space character. Example 7-12. Alphabetic Data Items 05 15 PACKAGE-CODE DEPT-ID • Numeric Data Items PIC AAA. PIC A(12). An item is in the numeric category when its PICTURE character-string contains only the symbols from the set: 9, P, S, and V. The number of digits described must be greater than 0 and not more than 18. The contents are represented externally as a combination of 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9. If the S is present, the sign of the value is retained. Example 7-13. Numeric Data Items 05 05 DIVISION-TOTAL FRACTION-AMOUNT PIC S9(10)V99. PIC VPP99. The PICTURE character-string must include the symbol S if the item is described with a SIGN clause. If the item inherits a SIGN clause from a data structure, the PICTURE character-string cannot include the symbol S unless the item category is DISPLAY. • Alphanumeric Data Items An item is in the alphanumeric category when its PICTURE character-string contains both 9 s and A s, or only X s, or a combination of 9 s, A s, and X s. A PICTURE character-string of all A s or all 9 s is not an alphanumeric item. The item is handled as if the string contained only X s. The contents of the item can be any combination of characters. Example 7-14. Alphanumeric Data Items 10 15 STOCK-ITEM-NAME ZONE-ID PIC X(25). PIC A(4)99. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 61 Data Division • PICTURE Clause Alphanumeric Edited Data Items An item is in the alphanumeric edited category when its PICTURE characterstring consists of at least one X or A and at least one B, zero (0 ), or slash (/). The contents of the data item can be any combination of characters. Example 7-15. Alphanumeric Edited Data Items 10 15 05 20 20 05 • PART-NAME BRANCH-CODE REPORT-VERSION SITE-ID SYSTEM-TAG SEAT-NUMBER PIC PIC PIC PIC PIC PIC X(5)BX(5). XX0X. XX/X. A(3)0A. AA/A. AB9. Numeric Edited Data Items An item is in the numeric edited category when its PICTURE character-string contains only combinations of the symbols B, slash (/), P, V, Z, zero (0 ), 9, comma (,), period (.), asterisk (*), plus (+), minus (-), CR, DB, and the currency symbol (usually the dollar sign ($)). The number of digit positions must be in the range from 1 through 18. The PICTURE character-string must have at least one symbol from the listed set other than 9, P, or V. Example 7-16. Numeric Edited Data Items 12 10 35 05 10 05 77 12 03 77 • R-TOTAL-1 ITEM-PRICE UNIT-PRICE AMOUNT-OWED AMOUNT-LEFT BACK-ORDERS START-DATE S-BLIVIT STARRED-X SUM-X PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC ZZZ,ZZZ.99. $999. $$$9. 999CR. ***99. -99. 99/99/99. +$99.99. ***.**. --B---.---. National Data Items An item is in the national category when its PICTURE character-string begins with N or n and contains no editing symbols. A national data item is used for languages that are not represented by roman letters and numbers, such as the Japanese Kanji alphabet. Special terminals and keyboards are required to use national data items. In general, you can use a national data item anywhere you can use an alphanumeric data item. Exceptions are: ° ° ° ° In an ACCEPT statement with DATE, DAY, DAY-OF-WEEK, or TIME In a FILE STATUS clause of the SELECT statement In an INITIALIZE statement with a REPLACING phrase In an INSPECT statement HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 62 Data Division ° ° ° ° ° ° PICTURE Clause In the PADDING clause of the SELECT statement In a RECEIVE-CONTROL paragraph In the SPECIAL-NAMES paragraph As the identifier in a CALL statement As the identifier in a CANCEL statement In comparison with a nonnational data item or nonnational literal If national data items and national literals are used for items in a STRING statement (part-1, delimiter, or result ) or an UNSTRING statement (delim-1, delim-2, result, or delimstore ), all the items must be national data items or national literals. If you use a VALUE clause with a national item, you must precede the value with N or n with no space between N or n and the value. For example: 01 kanji-field PIC N(4) VALUE IS N"kanji-value" where kanji-value is a Kanji literal. • Editing Characters Editing is done by inserting, suppressing, or replacing a character. Editing occurs when a value is moved into a data item whose PICTURE character-string contains editing characters. The primary purpose of editing is to easily transform data into reportable form. The methods of editing are: ° ° ° ° ° Simple insertion Special insertion Fixed insertion Floating insertion Zero suppression The type of editing that you can perform on an item depends on the item’s category. Table 7-3. Types of Editing Performed Data Item Category Type of Editing Alphabetic None Numeric None Alphanumeric None Alphanumeric Edited Simple insertion [0, B, or slash (/)] Numeric Edited All, subject to note following table National None HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 63 Data Division PICTURE Clause Note. Floating insertion editing and editing by zero suppression and replacement are mutually exclusive in a single PICTURE clause, and only one of the two replacement types can be used with zero suppression in a single PICTURE clause. ° Simple insertion The comma (,), space (B), zero (0 ), and slash (/) are used as the insertion characters. They are counted in the item’s size and represent where that character is inserted. The result of simple insertion editing is the appearance of the insertion character within the edited item value in the same position as it appears in the character-string. Here are some examples: ° Source Item PICTURE Edited Result 123456 PIC 999,999 123,456 123456 PIC 99BBB9999 12 3456 1234 PIC 990099 120034 1234 PIC 99/99 12/34 123456 PIC 99B99B99 12 34 56 1234 PIC 999900 123400 13184 PIC 99/99/99 01/31/84 12345 PIC 999,999 012,345 "ABCD" PIC ABABABA ABCD "1st2nd" PIC XXXB/BXXX 1st / 2nd Special insertion A period (.) is used as the insertion character and also acts as the decimal point for alignment purposes. The insertion character used for the actual decimal point is counted in the item’s size. An assumed decimal point character (V ) and an actual decimal point character (.) cannot both occur in the same PICTURE character-string. The result of special insertion editing is the appearance of the insertion character within the edited item value in the same position as it appears in the character-string. Here are some examples. The caret (^) in each source item is the decimal point location from its PICTURE character-string. Source Item PICTURE Edited Result 1234^56 PIC 9999.99 1234.56 1^23456 PIC 9.99999 1.23456 1^23456 PIC 99.999999 01.234560 123^4 PIC 99.9999 23.4000 12^345 PIC 99.99 12.34 HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 64 Data Division ° PICTURE Clause Fixed insertion The currency symbol and the editing sign control symbols (+, -, CR, DB) are the insertion characters. Only one currency symbol and one of the editing control symbols can be used in a PICTURE character-string. CR and DB represent two positions when counting an item’s size. When used, they must be in the rightmost positions. When a plus (+) or minus (-) is used, it must be in either the leftmost or rightmost character position to be counted in the item’s size. When the currency symbol is used, it must be the leftmost character, except when preceded by either a plus (+) or minus (-). Only one currency symbol and only one of the editing sign control characters can be used in the same PICTURE character-string. The result of fixed insertion editing is the appearance of the insertion characters within the item value in the same positions as they appear in the PICTURE character-string. Table 7-4. Sign Control Symbols Result Editing Symbol Positive or Zero Data Item Negative Data Item + + - - space - CR 2 spaces CR DB 2 spaces DB Here are some examples of fixed insertion editing. The caret (^) in each source item is the decimal point location from its PICTURE character-string. Source Item PICTURE Edited Result 12^34 PIC 99.99+ 12.34+ -12^34 PIC 99.99+ 12.34- 12^34 PIC +$99.99 +$12.34 -12^34 PIC +$99.99 -$12.34 12^34 PIC $99.99- $12.34 -12^34 PIC $99.99- $12.34- 12^34 PIC -$99.99 $12.34 -12^34 PIC -$99.99 -$12.34 12^34 PIC 99.99CR 12.34 -12^34 PIC 99.99CR 12.34CR 12^34 PIC $99.99DB $12.34 -12^34 PIC $99.99DB $12.34DB HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 65 Data Division ° PICTURE Clause Floating insertion The currency sign and editing sign control symbols plus (+) and minus (-) are floating insertion characters, mutually exclusive in a PICTURE character-string. At least two of any one symbol must be used. Simple insertion characters can be mixed with floating characters. To indicate floating insertion editing in a PICTURE character-string, you include a string of at least two of the floating insertion characters. This string can also contain any of the simple insertion symbols or have simple insertion characters immediately to its right. Any such simple insertion characters are part of the floating string. The leftmost character of the floating insertion string marks the leftmost limit of the floating symbol. The rightmost character of the floating string marks the rightmost limit of the floating symbols. The second floating character from the left marks the leftmost limit of numeric data that can be stored. Nonzero numeric data can replace all characters at or to the right of this limit. In floating insertion editing, you can either represent any or all of the leading numeric positions on the left of the decimal point by the insertion symbol.R or represent all the numeric positions, right or left of the decimal point, by the insertion symbol. If the character-string contains a decimal point symbol, at least one floating insertion character must appear to the left of it. If the insertion characters are only to the left of the decimal point, then assignment to the item places a single floating insertion character in the position immediately preceding either the decimal point or the first nonzero digit in the data represented by the insertion symbol string, whichever is farther to the left in the PICTURE character-string. The character positions preceding the insertion character are replaced with spaces. If all numeric character positions in the PICTURE character-string are represented by the insertion character, the result depends on the value of the assigned data. If the value is 0, the entire data item is set to spaces. If the value is not 0, the result is the same as when the insertion character is only to the left of the decimal point. To avoid truncation of the edited item, the minimum size of the PICTURE character-string for the receiving data item must be the number of characters in the sending item, plus the number of nonfloating characters being edited into the receiving data item, plus one for the floating insertion character. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 66 Data Division PICTURE Clause Examples of floating insertion editing: ° Source Item PICTURE Edited Result 123 $$999 $123 1234 $$$$$ $1234 2 $$999 $002 0 $$$$$ (all spaces) 0 $$$99 $00 1234 +++99 +1234 -23 +++99 -23 4 +++99 +04 123 ------9 123 -123 ------9 -123 1.23 $$$9.99 $1.23 -1.23 $$$9.99 $1.23 0.03 $$$9.99 $0.03 -0.03 $$$9.99 $0.03 1.23 $$$$.$$ $1.23 -1.23 $$$$.$$ $1.23 0.03 $$$$.$$ $.03 -0.03 $$$$.$$ $.03 1.23 ---9.99 1.23 -1.23 ---9.99 -1.23 0.03 ---9.99 0.03 -0.03 ---9.99 -0.03 1.23 ----.-- 1.23 -1.23 ----.-- -1.23 0.03 ----.-- .03 -0.03 ----.-- -.03 Zero suppression Suppression of leading zeros in numeric character positions is done with a Z or asterisk (*) in the PICTURE character-string. These symbols are mutually exclusive in a single PICTURE character-string. When you use the asterisk, you cannot use BLANK WHEN ZERO in the same entry. Each suppression symbol is counted in the item’s size. Spaces replace Z s; asterisks remain asterisks. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 67 Data Division PICTURE Clause You specify zero suppression and replacement by using a string of one or more Z s or asterisks to represent leading numeric character positions that are to be replaced when any of those positions in the data are zero. Any of the simple insertion characters embedded in the string of symbols or to the immediate right of this string are part of the string. For zero suppression in a PICTURE character-string, you can either represent any or all of the leading numeric character positions to the left of the decimal point by Z s or asterisks or you can represent all of the numeric positions, right or left of the decimal point, as Z s or asterisks. If the suppression symbols appear only to the left of the decimal point, any leading zero in the data that corresponds to the symbol is replaced by the replacement character. Suppression terminates at the first nonzero digit in the data represented by the suppression symbol string or at the decimal point, whichever comes first. If all numeric character positions in the PICTURE character-string are represented by suppression symbols and the value of the data is not 0, the result is the same as if the suppression characters were only to the left of the decimal point. If the value is 0 and the suppression symbol is Z, the entire data item is set to spaces. If the value is 0 and the suppression symbol is the asterisk, the data item is set to all asterisks except for the actual decimal point. In this case, the actual decimal point appears in the data item. Only one of the symbols plus (+), minus (-), asterisk (*), Z, and the currency symbol can be used as a floating replacement character within a single PICTURE character-string. Note. The caret (^) in the source item is the decimal point from its PICTURE character-string. Here are some examples of suppression editing: Source Item PICTURE Edited Result 123456 $ZZZ,ZZZ.99 $123,456.00 1234^56 $ZZZ,ZZZ.99 $ 1,234.56 0 Z,ZZZ.ZZ 8 spaces 12^34 $***,***.99 $*****12.34 0 $***,***.99 $*******.00 0 $***,***.** $*******.** HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 68 Data Division USAGE Clause USAGE Clause The USAGE clause determines how a data item is stored in the system (its format), and usually, the number of character positions the data item uses. BINARY USAGE IS COMPUTATIONAL COMP COMPUTATIONAL-3 COMP-3 COMPUTATIONAL-5 COMP-5 DISPLAY INDEX NATIVE-2 NATIVE-4 NATIVE-8 PACKED-DECIMAL POINTER VST099.vsd BINARY COMPUTATIONAL COMP describe a two’s complement binary integer with an implied decimal point. COMPUTATIONAL-3 COMP-3 PACKED-DECIMAL describe a numeric data item in radix 10, but with each digit of the value stored in half a computer character (4 bits, called a nibble). The sign is stored in a separate, trailing nibble; that is, at the right-hand (least significant) end of the data item. Any unused nibbles are on the left-hand (most significant) end of the data item and are set to zero. SeeTable 7-5, Table 7-6, and Table 7-7. COMPUTATIONAL-3/PACKED-DECIMAL is also called binary coded decimal form. The keyword PACKED-DECIMAL is an element of COBOL, but the data format is not. If your program is compiled with a FIPS directive with NONSTANDARDEXT in the flag-option-list, the compiler issues a warning message when it finds a COMPUTATIONAL-3/PACKED-DECIMAL data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 69 Data Division USAGE Clause COMPUTATIONAL-5 COMP-5 describes a two’s complement binary integer that occupies 2, 4, or 8 character positions (bytes), depending on its PICTURE clause. For more information on the PICTURE clause, see PICTURE clause. The COMPUTATIONAL-5 data type is not an element of COBOL. If your program is compiled with a FIPS directive with NONSTANDARDEXT in the flag-optionlist, the compiler issues a warning message when it finds a COMPUTATIONAL-5 data item. DISPLAY describes a sequence of characters stored in standard data format. Its PICTURE clause determines the number and types of characters in the value, which can be used in any context for its category. DISPLAY is the default for elementary data items. INDEX describes an index data item—a data item that occupies four character positions and whose value is the occurrence number of a table element. This value cannot be used in computations. An index data item has no PICTURE clause. NATIVE-2 describes a signed, two’s complement binary integer that occupies 2 character positions (bytes) and can have a value in the range -32,768 through +32,767. NATIVE-4 describes a signed, two’s complement binary integer that occupies 4 character positions (bytes) and can have a value in the range -2,147,483,648 through +2,147,483,647. NATIVE-8 describes a signed, two’s complement binary integer that occupies 8 character positions (bytes) and can have a value in the range -9,223,372,036,854,775,808 through +9,223,372,036,854,775,807. POINTER describes a 4-byte data item whose value, which is assigned with the SET statement, is the address of another data item. Note. The NATIVE-n and POINTER data types are not elements of COBOL. If your program is compiled with a FIPS directive with NONSTANDARDEXT in the flag-option-list, the compiler issues a warning message when it finds a NATIVE-n or POINTER data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 70 Data Division USAGE Clause Table 7-5. COMPUTATIONAL-3/PACKED-DECIMAL Digit Representation Hexadecimal Digit Representation Digit Value Left* Nibble (Odd Digit) Right* Nibble (Even Digit) 0 X"00" X"00" 1 X"10" X"01" 2 X"20" X"02" 3 X"30" X"03" 4 X"40" X"04" 5 X"50" X"05" 6 X"60" X"06" 7 X"70" X"07" 8 X"80" X"08" 9 X"90" X"09" * Count even and odd from right to left. Table 7-6. COMPUTATIONAL-3/PACKED-DECIMAL Sign Digit Representation Sign Convention in PICTURE Clause Sign of Data Item Value Sign Half-Character (Hexadecimal) Unsigned Not applicable X"0F" Signed + X"0C" Signed - X"0D" Table 7-7. Numeric Data Storage for the COMPUTATIONAL-3/PACKED-DECIMAL PICTURE Clause Bytes Required Number of Digits (Signed or Unsigned) 1 1 2 2-3 3 4-5 4 6-7 5 8-9 6 10-11 7 12-13 8 14-15 9 16-17 10 18 HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 71 Data Division USAGE Clause A COMPUTATIONAL-3/PACKED-DECIMAL data item with PICTURE 9999 and value +1234 is stored as shown in Figure 7-3, where F represents the nonprinting plus sign. Figure 7-3. Example of COMPUTATIONAL-3/PACKED-DECIMAL Storage ... 1 2 3 4 F 0000 0001 0010 0011 0100 1111 1 byte VST601.vsd A COMPUTATIONAL-3/PACKED-DECIMAL data item with PICTURE S9999 and value +1234 is stored as shown in Figure 7-3 except that F is replaced by C (1100), which represents the plus sign (+). A COMPUTATIONAL-3/PACKED-DECIMAL data item with PICTURE S9999 and value -1234 is stored as shown in Figure 7-3 except that F is replaced by D (1101), which represents the minus sign (-). Usage Considerations: • National Data Items Cannot Have USAGE Clauses Verify that national data items do not have USAGE clauses (inherited, explicit, or implicit) and are not mixed with nonnational data items in group descriptions. • USAGE Clause Rarely Restricts Actual Usage The USAGE clause describes a data item, but rarely restricts how the item is actually used. Exceptions are USAGE INDEX, USAGE POINTER, and rules for certain statements that require the DISPLAY phrase or default to USAGE DISPLAY. • USAGE Clause Applies to Both Elementary and Data Structures Any level of a data description can have a USAGE clause. A USAGE clause at the group level applies to each elementary item in the group, and the USAGE of an elementary item cannot contradict the USAGE clause of a group to which the item belongs. Because data structures are always in the alphanumeric category, their USAGE clauses might not always apply to their own manipulation, for example: The subitems of a BINARY/COMPUTATIONAL data structure can be used in computations, but the data structure itself cannot. The subitems of an INDEX data structure are index data items, but the data structure itself is not. The subitems of a POINTER data structure are pointers, but the data structure itself is not. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 72 Data Division • USAGE Clause BINARY or COMPUTATIONAL Data Items ° Purpose The purpose of BINARY or COMPUTATIONAL items is to improve performance and reduce the size of generated code (sometimes by a factor of as much as 100). Use BINARY or COMPUTATIONAL for a value that can be represented in the number of digits specified in the PICTURE clause; for example: ° PICTURE Range of Values PICTURE 9(4) 0 through 9999 PICTURE S9(4) -9999 through 9999 PICTURE character-string contents A BINARY/COMPUTATIONAL data item’s PICTURE character-string can contain only 9 s, the sign character S, the decimal point character V, and one or more P s. The PICTURE clause for an elementary BINARY/COMPUTATIONAL data item must describe the item’s category as numeric. A BINARY/COMPUTATIONAL data item whose PICTURE character-string has one to four 9 s is stored as 16 bits. A BINARY/COMPUTATIONAL data item whose PICTURE character-string has five or more 9 s is stored as 4 or 8 bytes. ° Cannot have or inherit SIGN clause The description of a group or elementary data item with BINARY/COMPUTATIONAL format cannot include or inherit a SIGN clause, because if such an item is signed, the host computer’s architecture determines the representation of the sign. ° Cannot have BLANK WHEN ZERO clause A BLANK WHEN ZERO clause changes a numeric data item’s category from numeric to numeric edited; therefore, the item cannot be BINARY/COMPUTATIONAL. ° COMPUTATIONAL data item with value 8224 or 224 In HP COBOL, if you find that a data item of USAGE COMPUTATIONAL has the value 8224, it might be because it actually consists of 2 bytes, each containing a space character. If it is described as consisting of 3 digits, it appears to have the value 224. ° See Trapping Size Errors. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 73 Data Division • USAGE Clause COMPUTATIONAL-3/PACKED-DECIMAL Data Items ° Purpose COMPUTATIONAL-3/PACKED-DECIMAL data items are provided for data compatibility with systems other than NonStop systems. They are not recommended for other purposes. ° Inefficiency Packed-decimal data format is inefficient because HP hardware does not support it. Avoid using it if possible, especially in benchmarks and performance-critical programs. ° Where you can use them You can use COMPUTATIONAL-3/PACKED-DECIMAL data items wherever you can use data items that do not have USAGE DISPLAY. ° SYNCHRONIZED clause The SYNCHRONIZED clause (with or without the LEFT or RIGHT phrase) has no effect on COMPUTATIONAL-3/PACKED-DECIMAL declarations. • ° See Trapping Size Errors. COMPUTATIONAL-5 Data Items ° Purpose The COMPUTATIONAL-5 data type is compatible with the X/Open COBOL specification (see the X/Open CALL Statement). Signed COMPUTATIONAL-5 data items are equivalent to NATIVE-n data items, but unsigned COMPUTATIONAL-5 data items can store a larger range of values than the corresponding NATIVE-n data items (see in PICTURE clause). HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 74 Data Division ° USAGE Clause PICTURE clause A COMPUTATIONAL-5 data item can have any PICTURE clause containing 9, P, S, and V. The PICTURE clause determines its size and the range of its values. Bracketed items are optional. Range PICTURE Clause NATIVE-n Equivalent Signed 1 Unsigned2 PIC [S]9(1) PIC [S]9(4) NATIVE-2 -32,768 through 32,767 0 through 65,535 PIC [S]9(5) PIC [S]9(9) NATIVE-4 -2,147,483,648 through 2,147,483,647 0 through 4,294,967,295 PIC [S]9(10) PIC [S]9(18) NATIVE-8 -9,223,372,036,854,775, 808 through 9,223,372,036,854,775, 807 0 through 18,446,744,073,709, 551, 615 1. NATIVE-n items must be in the signed range. 2. Applies only to PICTURE Clause. ° SYNCHRONIZED clause causes 2-Byte alignment The SYNCHRONIZED clause causes COMPUTATIONAL-5 data items to be aligned on 2-byte or 4-byte boundaries, depending on their size. In this case, LEFT and RIGHT phrases have the same effect. ° Passing by reference requires SYNCHRONIZED clause To pass a COMPUTATIONAL-5 data item to a routine written in a language that requires parameters to be 2-byte-aligned, describe the data item with the SYNCHRONIZED clause. ° Decimal numeric literal cannot have maximum value of COMP-5 data item You cannot specify a decimal numeric literal that is the maximum value allowed for a COMPUTATIONAL-5 data item. The reason is that the maximum value allowed for a COMPUTATIONAL-5 data item has 19 digits and a decimal numeric literal cannot have more than 18 digits. You can use a hexadecimal numeric literal for the maximum value allowed for a COMPUTATIONAL-5 data item. • DISPLAY Data Items If the data description entry for an elementary item does not include a USAGE clause and is not subordinate to any data structure description that includes an explicit USAGE clause, then the effect is as if a USAGE DISPLAY clause had appeared in the elementary item’s data description entry; therefore, an elementary data item’s usage attribute can be inherited, explicit, or implicit. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 75 Data Division USAGE Clause DISPLAY format is required for these data items: • ° Data items subordinate to a data structure that is described with a VALUE clause or has condition-names associated with it ° ° Signed numeric data items that are affected by a data structure’s SIGN clause ° See Trapping Size Errors. Elementary items whose data description entries contain SIGN, JUSTIFIED, or BLANK WHEN ZERO clauses INDEX Data Items The description of a group or elementary data item with INDEX format cannot include any of these clauses: ° ° ° ° ° PICTURE VALUE SYNCHRONIZED JUSTIFIED BLANK WHEN ZERO An index data item description cannot be followed immediately by any level-88 items; that is, an index data item cannot serve as a conditional variable. The compiler stores each INDEX data item as 4 bytes, aligned on a 4-byte boundary. • NATIVE-n Data Items The description of a group or elementary data item with NATIVE-n format cannot include any of these clauses: ° ° ° ° ° PICTURE SYNCHRONIZED JUSTIFIED BLANK WHEN ZERO SIGN If an arithmetic statement includes a SIZE ERROR phrase, the size error condition occurs as defined in SIZE ERROR Phrase, except that in a NATIVE-n receiving item the test is for truncation of significant bits, not significant decimal digits. If a NATIVE-n data item used as a receiving operand specifies the ROUNDED phrase, decimal (not binary) rounding occurs, as described in SIZE ERROR Phrase. Because COBOL limits literals to a length of 18 digits, the maximum value that you can assign to a NATIVE-8 data item (by initialization with a VALUE phrase or by a MOVE statement, for example) is the 18-digit value of -/+999999999999999999, rather than the maximum storable 19-digit value of -9223372036854775808 or +9223372036854775807. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 76 Data Division • USAGE Clause How NATIVE-n and BINARY/COMPUTATIONAL Formats Differ The significant difference between a NATIVE-n data item (which occupies n character positions by definition) and a COMPUTATIONAL data item that happens to occupy n character positions is that the COMPUTATIONAL item has the number of decimal digits declared by its PICTURE clause. Although a NATIVE-n data item and a certain COMPUTATIONAL data item both occupy n character positions, they cannot necessarily assume the same set of values. For example, a NATIVE-2 data item and a COMPUTATIONAL data item with PICTURE 9999 both occupy 2 character positions, but any value larger than 9999 is truncated on the left before it is assigned to the COMPUTATIONAL data item, whereas the NATIVE-2 data item can be assigned any value in the range -32768 through +32767. A program can specify a NATIVE-n data item as an operand anywhere that it can specify a BINARY/COMPUTATIONAL item (of equivalent size in character positions), such as in arithmetic expressions, MOVE statements, and so on. In all cases, the value of the item is interpreted as a signed integer. • How NATIVE-n and COMPUTATIONAL-5 Formats Differ The difference between a NATIVE-n data item and a COMPUTATIONAL-5 data item is that the NATIVE-n data item is 2-byte-aligned and the COMPUTATIONAL-5 data item is byte-aligned and requires a PICTURE clause (see PICTURE clause). • POINTER Data Items ° Clauses not allowed A group or elementary data item described with a USAGE POINTER clause cannot have any other clauses except VALUE IS NULL or VALUE IS NULLS. The clause VALUE IS NULL or VALUE IS NULLS initializes the pointer to a value (all ones) that causes an address fault if the pointer is referenced. ° How HP COBOL pointers differ from HP C and Pascal pointers An HP COBOL POINTER data item is not the same as a pointer in HP C or Pascal. An HP COBOL POINTER data item merely provides a container for an address. You can access an HP COBOL POINTER data item only in a conditional expression, a SET statement, or as a parameter in the USING phrase of a CALL or ENTER statement. The statement MOVE "ABC" TO PTR1 where PTR1 is an HP COBOL pointer, does not move the value “ABC” to the address that PTR1 contains. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 77 Data Division SIGN Clause For an HP COBOL pointer to accomplish what an HP C or Pascal pointer accomplishes, you must declare a base data item in the Linkage Section. You must not put the base data item in the USING phrase of the PROCEDURE DIVISION heading (that is, you must not pass the base data item as a parameter). SIGN Clause The SIGN clause specifies the position and mode of representation of the operational sign for a numeric data item. It can only be used for DISPLAY items with an S in the PICTURE character-string. This precludes the use of the SIGN clause with USAGE NATIVE-n or USAGE POINTER. LEADING SIGN IS TRAILING SEPARATE CHARACTER VST100.vsd Usage Considerations: • Function of the SIGN Clause The representation of every signed numeric data item includes an operational sign. When the data item is USAGE BINARY or USAGE COMPUTATIONAL, the compiler automatically chooses the appropriate sign convention in accordance with the item’s internal representation. When the data item is USAGE DISPLAY, the SIGN clause determines the position and representation of the sign. When no SIGN clause is used, SIGN TRAILING is assumed. When the SEPARATE phrase is present, the sign is maintained as a separate character to be considered in the size of the item. A plus (+) for a positive value or a minus (-) for a negative value is placed at the beginning or end of the item’s value, depending on the presence of LEADING or TRAILING. If the sign character position contains a value other than plus (+) or minus (-), any operation that uses the item as a numeric sending item has undefined results. If the SEPARATE phrase is absent, negative values are represented by a modification of the high-order bit of the high-order or low-order digit of the stored number (depending on the presence of LEADING or TRAILING). The sign is not considered in the size of the item. For positive values of the data item, the value of the sign bit is 0; for negative values, the value of the sign bit is 1. Note. If you move a data item with an included sign to another item with a group move, the character with a negative sign is not a legitimate COBOL character. This can cause problems. Use an item with an included sign only in operations that expect numeric data. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 78 Data Division • OCCURS Clause for Fixed-Size Tables Use of SIGN With Elementary or Data Structures The SIGN clause can appear in the description of an elementary item or a data structure. When it appears in the description of an elementary item, it specifies the sign attributes for that item. The SIGN clause never applies to a data structure, whose category is always alphanumeric. When it appears in the description of a data structure, it specifies the sign attributes of every signed numeric item belonging to that group, except as noted. • A Lower-Level SIGN Clause Overrides an Upper-Level One A SIGN clause appearing in the data description entry of a data structure or a numeric data item overrides the SIGN clause of any data structure to which that item is subordinate; therefore, when more than one SIGN clause apparently applies to a data item, the one specified at the lowest level in the hierarchy takes precedence over the ones specified at a higher level. • Data Structure With SIGN Clause Must Include DISPLAY Numeric When the data description entry of a data structure includes the SIGN clause, at least one subordinate elementary item must be numeric and be described with a PICTURE character-string containing S. All such items must be USAGE DISPLAY. • Elementary Item With SIGN Clause Must Be DISPLAY Numeric When the data description entry of an elementary item includes the SIGN clause, its category must be numeric, it must be described with a PICTURE characterstring containing S, and it must be USAGE DISPLAY. • The SIGN clause cannot be used for national data items. OCCURS Clause for Fixed-Size Tables The OCCURS clause defines tables (sets of repeated items), eliminating the need for separate item entries. These tables can contain a fixed number of elements or can vary within given limits. The OCCURS clause without a DEPENDING phrase defines a fixed-size table. OCCURS max TIMES key-order index INDEXED BY VST104.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 79 Data Division OCCURS Clause for Fixed-Size Tables max is an integer literal that specifies the number of elements in the table. key-order ASCENDING DESCENDING KEY IS key VST105.vsd determines whether the table elements are arranged in ascending or descending order of key values. key is either the name of the entry containing the OCCURS clause or the name of an entry subordinate to the entry containing the OCCURS clause. index is a name for a compiler-created item used to select an element from the table. Each index must be unique in the program because you cannot qualify it. Usage Considerations*: • The OCCURS Clause Describes a Table The OCCURS clause specifies that the data-name with which it is associated (the one following the level number in the same data description entry) identifies a table containing multiple occurrences of the elementary item or data structure described by its entry. When the data description entry does not define a name (that is, FILLER is specified either explicitly or implicitly), the table is anonymous and its elements cannot be referred to directly. Except for the OCCURS clause itself, all of the entry’s clauses apply to each occurrence of the item described. • The INDEXED Phrase Declares Index-Names The presence of an INDEXED phrase serves also to declare one or more indexnames for the table. The names thus declared must not be separately declared elsewhere. These, and only these, index-names can be used as the subscript when an index-name is used to select a particular occurrence of this table. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 80 Data Division • OCCURS Clause for Fixed-Size Tables KEY Phrase Each key (key in the syntax diagram) must reference a data item that is subordinate to the table, except that the first key in a list can reference the table itself. No OCCURS clause can apply to a key unless it also applies to the table. As a consequence, a key cannot be or belong to a table that is subordinate to the table of which it is a key. An OCCURS statement can have a maximum of 31 keys. The representation of the reference to the key in this context does not include subscripts. The KEY phrase indicates that within the table occurrences, the values referenced by the keys are arranged in a consistent order. When the key appears in an ASCENDING phrase, the values are arranged in ascending order of occurrence numbers (that is, the value associated with an occurrence is never less than the value associated with any preceding occurrence). When the key appears in a DESCENDING phrase, the values are arranged in descending order (that is, the value associated with an occurrence is never greater than the value associated with any preceding occurrence). This characteristic is relevant only during the execution of a SEARCH ALL statement that references the table. All of the KEY phrases taken together define a single list, within which the keys appear in decreasing order of search significance. • Subscripts Each appearance of a table’s data-name must include an appropriate subscript, except when the entire table is desired (this only occurs in the SEARCH statement and some intrinsic functions). References appearing in a REDEFINES clause or a KEY phrase of the OCCURS clause are not considered operands and must not include subscripts. • References to Subordinates Must be Subscripted If the data-name is a data structure, then all items belonging to the group must also be subscripted whenever they are used as operands; however, subordinate datanames used in the KEY phrase, or as objects of a REDEFINES clause, are not considered operands and must not be subscripted or indexed. • OCCURS Limited to Certain Level Numbers The OCCURS clause must not be specified for a data description entry having a level number of 01, 66, 77, or 88. • OCCURS Forbidden for Redefined Data Elements The OCCURS clause cannot appear in a data description entry whose data-name is specified in a REDEFINES clause of some subsequent data description entry; therefore, an entire table cannot be redefined. It is possible, however, to redefine subordinate data items of table elements. (See REDEFINES Clause.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 81 Data Division • OCCURS Clause for Fixed-Size Tables Multidimensional Tables Data items subordinate to the subject of an entry described with an OCCURS clause can themselves contain an OCCURS clause; therefore, tables can consist of multiple occurrences of subordinate tables for a maximum of seven levels. A data description entry containing either type of OCCURS clause can be followed by subordinate entries containing the OCCURS clause for fixed-size tables; however, a data description entry with an OCCURS DEPENDING clause (discussed in the next topic) cannot be subordinate to a group entry described with either type of OCCURS clause. • Order of Subscripts in References Up to seven subscripts can be used with one data item. When more than one subscript is used, they are written to the right of the table name, in the order of more inclusive to less inclusive dimensions of the data organization (that is, the first subscript matches the table having the lowest level number). All qualification must precede any subscripts (see VEHICLE in Example 7-17). • Index is a Variant of Subscript In COBOL, an index is a variant of a subscript. The program can define an indexed table within a nonindexed table (or the reverse). Both indexes and subscripts can be augmented with an increment or a decrement. That is, if a table is described: 01 A-TABLE. 03 ROWE OCCURS 20 TIMES INDEXED BY R. 05 KOLUMN OCCURS 10 TIMES. 07 ELEMENT PIC X. then a statement in the program could refer to any of these (assuming X, R, and Y had acceptable values): ELEMENT ( R , 5 ) ELEMENT ( 3 , Y - 3 ) ELEMENT ( R + 1 , X + 2 ) • Applying Index-Names to Other Tables If you use an index-name specified in the INDEXED phrase of one table to refer to an element of another table in the program, the compiler reports an error. You must use the SET statement to the index-name associated with one table to the occurrence-number designated by the index-name associated with a different table. In Example 7-17, MY-TABLE is appropriate for the SEARCH ALL statement. The order of the table is governed by FIRST-ITEM. It can just as well be declared to be governed by MY-TABLE, FIRST-A, FIRST-B, FIRST-B-1, FIRST-B-2, or SECONDITEM. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 82 Data Division OCCURS Clause for Variable-Size Tables Example 7-17. Fixed-Size Table 01 MY-TABLE-RECORD. 02 MY-TABLE OCCURS 100 TIMES ASCENDING KEY IS FIRST-ITEM. INDEXED MY-INDEX 05 FIRST-ITEM. 08 FIRST-A PICTURE 99. 08 FIRST-B. 10 FIRST-B-1 PICTURE 99. 10 FIRST-B-2 PICTURE 99. 05 SECOND-ITEM PICTURE X(6). 01 VEHICLE. 03 MODEL OCCURS 9 TIMES. 05 STYLE OCCURS 12 TIMES. 07 COLOR OCCURS 15 TIMES PICTURE 9(10). 05 LOCATION PICTURE X(25). These identifiers specify elements of the table VEHICLE in Example 7-17: MODEL (3) STYLE OF MODEL (3, 11) COLOR OF STYLE OF MODEL (3, 11, 14) OCCURS Clause for Variable-Size Tables The OCCURS clause with a DEPENDING phrase defines a variable-size table. OCCURS min TO max TIMES depend DEPENDING ON key-order INDEXED index BY VST106.vsd min is an integer literal that specifies the minimum number of table elements. Its value is in the range 0 through max. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 83 Data Division OCCURS Clause for Variable-Size Tables max is an integer literal that specifies the maximum number of table elements. depend is an integer data item that controls the size of the table. As depend increases or decreases, the number of table elements increases or decreases. When the table size decreases, elements beyond the element whose ordinal position is specified by the new value of depend are lost—even if the next statement increases the table to include them. When the table grows, you must assign values to the new elements prior to using them. key-order ASCENDING DESCENDING KEY IS key VST105.vsd determines whether table elements are arranged in ascending or descending order of key values. key is either the name of the entry containing the OCCURS clause or the name of an entry subordinate to the entry containing the OCCURS clause. index is a name for compiler-created item used to select an element from the table. Each index must be unique in the program because you cannot qualify it. Usage Considerations: • • See the usage considerations for OCCURS Clause for Fixed-Size Tables. Depending Item The depending item (depend in the syntax diagram) must reference an integer numeric data item that is capable of containing the value of max. The storage space associated with the depending item cannot be contained within or overlap the storage space associated with the table whose occurrences it controls; therefore, the depending item cannot be described as a subordinate of the variable-occurrence data item. If the table is external, the depending item must also be external. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 84 Data Division OCCURS Clause for Variable-Size Tables At any point during execution of the object program-unit, the current value of the depending item represents the number of occurrences in the table; therefore, its value must never be less than min or greater than max during execution of a statement that references the table, any of its subordinate items, or any data structure that contains the table. You can use the CHECK compiler directive to verify that the depending item has an acceptable value. • Concept of a Variable-Size Item Any data structure containing a variable-occurrence table has a variable size. When such an item is referenced as an operand, its value normally includes only those table elements whose occurrence numbers are less than or equal to the value of the depending item at the start of the operation; however, when the data structure is used as a receiving operand and the depending item is itself a subordinate of the data structure (so that the operation changes its value), the size of the receiving operand is the maximum size of the data structure; that is, the operation proceeds as if the depending item contained the value of max. • Changing the Depending Item Affects Table Values Whenever the value of the depending item is increased, occurrences of the table are dynamically appended to each affected variable-size data structure; however, the portion of the item’s value contained in these new occurrences has an unpredictable content unless the same or a subsequent operation assigns a known value to that portion. Whenever the value of the depending item is reduced, the values of table members whose occurrence numbers exceed the new limit are lost. Even after a subsequent increase in the value of the depending item restores these occurrences to the table, their values are not predictable and they must not be used as operands until known values are assigned. • OCCURS DEPENDING Incompatible with REDEFINES A variable-occurrence data item cannot be specified as a redefinition or as part of a redefinition; that is, an OCCURS DEPENDING clause cannot appear in a data description entry that includes a REDEFINES clause or that is subordinate to a data description entry that includes a REDEFINES clause. • OCCURS DEPENDING Cannot Be Nested and Must Be Last A data description entry with an OCCURS DEPENDING clause can only be followed, within its record description, by descriptions of subordinate items; that is, only one table with a variable number of occurrences can appear in a single record description entry, and the data items it contains must be the last data items in the record. Note, however, that a fixed-occurrence data item can be subordinate to a variable-occurrence data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 85 Data Division SYNCHRONIZED Clause Example 7-18. Variable-Size Table 01 ACTIVITY-TABLE-RECORD. 03 ACTIVITY-COUNT PICTURE 99. 03 ACTIVITY-TABLE OCCURS 10 TO 20 TIMES DEPENDING ON ACTIVITY-COUNT INDEXED BY SAVE-INX-1 SAVE-INX-2. 05 ACTIVITY-ENTRY PICTURE 999. Example 7-19. Fixed-Size Table as an Element of a Variable-Size Table 01 DISPOSAL-COMPANIES. 03 H-COUNT PICTURE 99. 03 HAULER OCCURS 1 TO 12 TIMES DEPENDING ON H-COUNT. 05 VEHICLE OCCURS 15 TIMES. 07 V-NUMBER PICTURE 9(5). 07 CAPACITY-CU-FT PICTURE 9(4). 07 SERVICE-SCHEDULE PIC X. ... SYNCHRONIZED Clause The SYNCHRONIZED clause forces alignment of an elementary item on the most natural computer storage boundary. The elementary item cannot be a pointer or a national data item. Efficiency improves if data is aligned on natural computer memory boundaries, because additional object code is sometimes required to store or retrieve data when 2 bytes of the same word belong to different data items. Also, when a data item is stored within 2-byte boundaries, the complexity of code to process it can decrease. The SYNCHRONIZED clause is usually unnecessary, because the automatic alignment is also the most natural: each level-77 item of the Working-Storage Section and Extended-Storage Section and each level-01 item is aligned on a physical 2-byte boundary. (A TNS word is 16 bits and a TNS/R word is 32 bits.) Both automatic and forced alignment can cause the compiler to generate implicit FILLER data. SYNCHRONIZED SYNC LEFT RIGHT VST101.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 86 Data Division JUSTIFIED Clause Usage Considerations: • LEFT and RIGHT The optional keywords LEFT and RIGHT have no effect in HP COBOL. • Where You Can Use the SYNCHRONIZED Clause You can use the SYNCHRONIZED clause only in the data description entry of an elementary item that does not have a USAGE POINTER clause. You cannot imply or specify the SYNCHRONIZED clause for national data items. • DISPLAY Data Items That the SYNCHRONIZED Clause Does Not Affect The SYNCHRONIZED clause does not affect DISPLAY items at levels other than 01 or 77. They are composed of one or more character positions and stored as a corresponding number of 8-bit bytes aligned on byte or 2-byte boundaries, whether or not they are described with the SYNCHRONIZED clause. • COMPUTATIONAL or BINARY Data Items If the program is not compiled with the PORT directive, then a data item is aligned on a 2-byte boundary unless it is described with the SYNCHRONIZED clause. If it is described with the SYNCHRONIZED clause, it is aligned on a 2-byte boundary if its size is less than 4 bytes, and on a 4-byte boundary if its size is 4 bytes or larger. If the program is compiled with the PORT directive, and the COMPUTATIONAL or BINARY data item is not described with the SYNCHRONIZED clause, it is bytealigned. JUSTIFIED Clause The JUSTIFIED clause causes nonstandard positioning of data within a receiving item. It can appear only in the data description of an elementary item that meets these criteria: • • • Its category is alphabetic or alphanumeric. It is not subordinate to any data structure that has associated condition-names. It is not subordinate to any data structure that is described with a VALUE clause. JUSTIFIED JUST RIGHT VST107.vsd When a receiving data item is described with the JUSTIFIED clause, the standard alignment rules do not apply. Instead, a sending item too big for the receiving item is truncated on the left. If the sending item is smaller, its rightmost character is aligned with the rightmost character of the receiving field and the value is extended to the left with space characters. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 87 Data Division BLANK WHEN ZERO Clause Usage Considerations: • Effect of RIGHT on Compilation The optional keyword RIGHT has no effect on the compilation, and serves only to provide emphasis. • Trailing Spaces Are Not Ignored Trailing spaces in a data item are not ignored when the data item is moved to a right-justified field. For example, 77 F1 PIC X(3) JUSTIFIED RIGHT. 77 F2 PIC X(2) VALUE "A". MOVE F2 TO F1. gives F1 the value " A " not the value " A" Note. The JUSTIFIED clause has no effect on initialization by the VALUE clause. BLANK WHEN ZERO Clause The BLANK WHEN ZERO clause fills an item with spaces when its value is 0. BLANK ZERO WHEN VST246.vsd You can use the BLANK WHEN ZERO clause only with elementary numeric or elementary numeric edited data items. This clause revises the category of a numeric item to numeric edited; therefore, the item must be USAGE DISPLAY. Note. The BLANK WHEN ZERO clause has no effect on initialization by the VALUE clause. The BLANK WHEN ZERO clause cannot be used for national data items. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 88 Data Division VALUE Clause VALUE Clause This form of the VALUE clause assigns an initial value to an elementary data item or data structure described in the Working-Storage Section or Extended-Storage Section. For the form of the VALUE clause that assigns an initial value to a condition-name in any section of the Data Division, see Descriptions of Condition-Names for Values (Level 88). VALUE literal IS VST108.vsd literal is a literal or a figurative constant whose value is the initial value of the data item. Usage Considerations: • Restrictions on Use of the VALUE Clause Do not use a VALUE clause in the description of: • ° ° A data item described with an EXTERNAL clause ° A data structure that has a subordinate item described with a JUSTIFIED or SYNCHRONIZED clause, a USAGE clause other than USAGE DISPLAY (the default), or (except for a condition-name) a VALUE clause An elementary data item described with a USAGE INDEX or REDEFINES clause or subordinate to a data structure described with a VALUE or REDEFINES clause Restrictions on the Value of literal ° Numeric data items If the data item is numeric, literal must be a numeric literal or the figurative constant ZERO, ZEROS, or ZEROES. The keyword ALL cannot appear in the figurative constant. If literal is a numeric literal, its value must not require the truncation of nonzero digits; that is, the number of significant fraction digits in literal cannot exceed the number of fraction digits in the numeric data item, and the number of significant integral digits in literal cannot exceed the number of integral digits in the numeric data item. If literal is a signed numeric literal, it must either be NATIVE-n or have an associated signed numeric PICTURE character-string. Initialization follows standard alignment rules for numeric data items. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 89 Data Division ° VALUE Clause Nonnumeric data items If the data item is nonnumeric, literal must be nonnumeric or a figurative constant. The keyword ALL can appear in the figurative constant. The value of literal cannot exceed the size indicated by the data item’s PICTURE clause. Editing characters in the PICTURE clause are included when the size of the item is determined, but do not effect initialization; therefore, the value of literal must conform to the edited form. Initialization follows standard alignment rules for alphanumeric data items. The BLANK WHEN ZERO and JUSTIFIED clauses do not affect initialization. ° Pointer data items If the data item is described with a USAGE POINTER clause, literal must have the value NULL or NULLS. ° Data structures If the data item is a data structure, literal must be either a figurative constant or a nonnumeric literal. A data structure is initialized without consideration for its subordinate elementary or data structure items. If the data structure is described with one or more OCCURS clauses, every occurrence of the repeated item is initialized with the specified value. If an OCCURS clause has a variable number of occurrences, the initialization proceeds as if the data structure has its maximum number of occurrences. Example 7-20. VALUE Clauses 01 01 MAIN-HEADING. 05 FILLER PIC XX 05 FILLER PIC X(8) 05 FILLER PIC XX 05 FILLER PIC X(6) ... COUNTERS. 05 NO-OF-READS PIC 9(5) 05 NO-OF-WRITES PIC 9(5) VALUE VALUE VALUE VALUE SPACES. "DIVISION". SPACES. "REGION". VALUE ZEROS. VALUE ZEROS. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 90 Data Division Descriptions That Rename Items (Level 66) Descriptions That Rename Items (Level 66) The RENAMES clause assigns a new data-name to an item or to two or more contiguous items in a record. RENAMES does not cause allocation of storage. You can put level-66 items in any section of the Data Division. new-name 66 THROUGH RENAMES . old-name end-name THRU VST109.vsd new-name is the alias for an elementary item or a data structure. old-name is either the name of a data structure or the name of the first of several items to be given an alias. It can be qualified. end-name is the last group name or last item name included in the alias name. It can be qualified. The level-66 data description entry in Example 7-21 renames several items in a record so that you can refer to the items by one name. Example 7-21. Level-66 Data Description Entry 05 05 05 66 CARD-CODES. 10 STORE-CODE PIC 9. 10 STATE-CODE PIC 9(4). ACCOUNT-NUMBER PIC 9(6). CHECK-DIGIT PIC 9. CARD-NUMBER RENAMES CARD-CODES THRU CHECK-DIGIT. Usage Considerations: • RENAMES Stands Alone Because RENAMES merely renames a group of existing data items and does not redescribe any of their characteristics, no other clauses can be used with it. One or more RENAMES entries can be written for a logical record. They can occur in any order but must immediately follow all other data description entries for the record. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 91 Data Division • Descriptions That Rename Items (Level 66) Restrictions on Names old-name and end-name must be data areas within the same logical record and must be different. No part of the storage area referenced by end-name can occupy character positions preceding the beginning of the storage area referenced by old-name. The area referenced by end-name can overlap that referenced by old-name, but must extend beyond it; therefore, end-name cannot be subordinate to old-name. old-name and end-name cannot be the names of data entries with level number 01, 66, 77, or 88. Neither old-name nor end-name can have an OCCURS clause in its data definition or be subordinate to an item whose description has an OCCURS clause. • Level-66 item is Elementary or Group When end-name appears, new-name is a data structure including all elementary items starting with old-name (if it is an elementary item) or the first elementary item in old-name (if it is a data structure) and concluding with end-name (if it is an elementary item) or the last elementary item in end-name (if it is a data structure). When end-name does not appear, new-name merely renames old-name and is a data structure only if old-name is a data structure. The new item inherits all characteristics of the old item. • Restrictions on Data Area If end-name appears, its data area can overlap that of old-name but must extend beyond it; however, no part of the data area described by end-name can occupy character positions preceding the beginning of the area described by oldname. Because no part of the data area described by old-name can occupy character positions following the end of the area described by end-name, endname cannot be subordinate to old-name. No item within the renamed area can have a variable size. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 92 Data Division Descriptions of Noncontiguous Elementary Items (Level 77) Descriptions of Noncontiguous Elementary Items (Level 77) In the Working-Storage or Extended-Storage Section, you do not need to use the record structure to define elementary items that bear no hierarchical relationship to one another. Instead, you can classify and define them as noncontiguous elementary items. Use a separate data description entry that begins with the special level number 77 for each of these items. data-name-1 77 FILLER REDEFINES data-name-2 PICTURE clause INDEX USAGE IS SIGN clause OCCURS clause SYNCHRONIZED clause JUSTIFIED clause BLANK WHEN ZERO clause VALUE clause VST110.vsd data-name-1 is the name of the noncontiguous elementary item. FILLER is a place holder for a data item to which the program never refers. data-name-2 is the name of a data item being redefined. See REDEFINES Clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 93 Data Division Descriptions of Noncontiguous Elementary Items (Level 77) PICTURE clause is as described in PICTURE Clause. INDEX describes an index data item—a data item that occupies four character positions and whose value is the occurrence number of a table element. This value cannot be used in computations. If a level-77 description contains INDEX, then it cannot include the SYNCHRONIZED, JUSTIFIED, or BLANK WHEN ZERO clause. SIGN clause is as described in SIGN Clause. OCCURS clause is as described in OCCURS Clause for Fixed-Size Tables or OCCURS Clause for Variable-Size Tables. SYNCHRONIZED clause is as described in SYNCHRONIZED Clause. Do not use the SYNCHRONIZED clause with INDEX. JUSTIFIED clause is as described in JUSTIFIED Clause. Do not use the JUSTIFIED clause with INDEX. BLANK WHEN ZERO clause is as described in BLANK WHEN ZERO Clause. Do not use the BLANK WHEN ZERO clause with INDEX. VALUE clause is as described in VALUE Clause. Do not use the VALUE clause with INDEX. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 94 Data Division Descriptions of Condition-Names for Values (Level 88) Descriptions of Condition-Names for Values (Level 88) You can assign a name to a specific value, set of values, or range of values that a data item can have and use that name as a condition in a conditional statement. The name is called a condition-name, and the data item associated with it is called a conditional variable. To do this, you must put one or more level-88 items (each including a condition-name and a VALUE clause specifying a value or a range of values for that condition-name) immediately after the data description of the conditional variable. You can put level-88 items in any section of the Data Division. 88 condition-name VALUE IS VALUES ARE value-1 THROUGH value-2 THRU VST112.vsd condition-name is the name of the condition value. value-1 is a literal. It is either a single value or the first in a range of values tested by the condition. value-2 is a literal and is the final value in a range of values tested by the condition. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 95 Data Division Descriptions of Condition-Names for Values (Level 88) Example 7-22. Condition-Names for Values (Level 88) Declaration: 05 RETURN-CODE PIC 99. 88 END-OF-FILE 88 ERROR-ON-READ 88 PERMANENT-ERROR 88 ERROR-ON-WRITE VALUE VALUE VALUE VALUE 01. 02. 03. 04. Statement using one of the condition-names: IF END-OF-FILE PERFORM END-UP-OPERATION CLOSE FILE-IN END-IF Definition of an item that has a range of values: 05 tax-code 88 tax-range PIC 99. VALUES ARE 00, 03, 07 THROUGH 11. Statement testing if tax-code is 00, 03, 07, 08, 09, 10, or 11: IF NOT TAX-RANGE PERFORM TAX-ERROR-ROUTINE. Example 7-23. VALUE Clauses for a Level-88 Data Item 01 ZIP-CODE. 03 ZIP-FIRST-3 PICTURE 999. ... 88 NEW-YORK VALUE IS 090 THRU 098, 100 THRU 149. 88 PENNSYLVANIA VALUE IS 150 THRU 196. ... Usage Considerations: • Condition-Name Description Location All condition-name entries for a particular conditional variable must immediately follow the entry describing that variable. • Cannot Use With Certain Descriptions A condition-name can be associated with any data description entry, even if specified explicitly or implicitly as FILLER, with these exceptions: ° ° ° ° Level-66 items Level-88 items Index data item Data structure having any subordinate item described with the JUSTIFIED or SYNCHRONIZED clause, or which are not USAGE DISPLAY HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 96 Data Division Descriptions of Condition-Names for Values (Level 88) As the syntax presentation shows, the only clause permitted in a condition-name entry is the VALUE clause containing the value, values, or range of values associated with the condition-name; therefore, the characteristics of the conditionname are implicitly those of the condition variable. • Setting a Condition-Name to TRUE You can set the value of a condition-name to TRUE with the SET TO statement. See Nonpointer Data Items. • Numeric data items If an item is in the numeric category, all literals in the VALUE clause must be numeric literals or figurative constants ZERO, ZEROS, or ZEROES (the keyword ALL cannot appear in this context), and they must be in the range of values set by the PICTURE character-string of the conditional variable. A signed numeric literal only applies to a signed numeric conditional variable. A numeric literal must not have a value that would require the truncation of nonzero digits; therefore, the number of significant fraction digits in the numeric literal cannot exceed the number of fraction digits in the data item, and the number of significant integral digits in the numeric literal cannot exceed the number of integral digits in the data item. • Nonnumeric data items If an item is not in the numeric category, all literals of VALUE must be nonnumeric literals or figurative constants (the ALL form of figurative constant is legal in this context), and must not exceed the size of the conditional variable. • Multiple Values More than one value or a range of values can be given for a condition-name entry. Whenever THROUGH is used, the left-hand literal must be less than the right-hand literal. • Overlap The values of different condition-names associated with the same conditional variable are permitted to overlap; therefore, it is possible to construct sets of condition names associated with one conditional variable in which more than one condition-name has the same truth value. HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 97 Data Division Descriptions of Condition-Names for Values (Level 88) HP COBOL Manual for TNS and TNS/R Programs —522555-006 7- 98 8 Procedure Division The Procedure Division is optional, but a program without a Procedure Division does nothing except initialize data. The Procedure Division is composed of statements, which specify the actions to be taken by the program. The program does its work by executing the statements in their appropriate sequence. The way you organize the statements not only governs the order in which they execute but also can contribute to your program’s readability and maintainability. You can organize statements into sentences, sentences into paragraphs, and sentences and/or paragraphs into sections. A paragraph, a group of successive paragraphs, a section, or a group of successive sections can be executed as a unit called a procedure. Figure 8-1. Relationship of Statements, Sentences, Paragraphs, and Sections procedure(s) section(s) paragraph(s) sentence(s) statement(s) VST508.vsd The Procedure Division can optionally include a Declaratives Portion. The Declaratives Portion is a set of sections at the beginning of the Procedure Division. These sections are executed if specified conditions arise during the execution of statements outside the Declaratives Portion. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8 -1 Procedure Division Procedure Division Components and Syntax Topics: • • • • • • • • Procedure Division Components and Syntax Execution of the Procedure Division Common Semantic Rules Common Phrases Input-Output Arithmetic Operations Conditional Expressions Concatenation Expressions Procedure Division Components and Syntax PROCEDURE DIVISION USING parameter . declaratives-portion paragraph section VST113.vsd USING marks the beginning of a parameter list in a called program. The CALL statement in the calling program must contain a corresponding USING phrase. parameter is the identifier of a data item in the Linkage Section. See Linkage Section and CALL. declaratives-portion is described in Declaratives Portion. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8 -2 Procedure Division Procedure Division Components and Syntax section is described in Sections. Example 8-1. Procedure Division PROCEDURE DIVISION. DRIVER SECTION. DRIVE. PERFORM 100-INITIALIZATION PERFORM 200-PROCESS-REQUESTS UNTIL JOB-IS-DONE PERFORM 300-TERMINATION. 100-INITIALIZATION SECTION. OPEN-FILES. OPEN INPUT MESSAGE-IN OPEN OUTPUT MESSAGE-OUT OPEN INPUT BASE-FILE. FINISH-UP-INIT. MOVE "READY" TO WATCH-WORD. ... 200-PROCESS-REQUESTS SECTION. READ-DOLLAR-RECEIVE. READ MESSAGE-IN ... PROCESS-INPUT-DATA. ... 300-TERMINATION SECTION. CLOSE-AND-QUIT. CLOSE MESSAGE-IN MESSAGE-OUT BASE-FILE STOP RUN. Topics: • • • • • • Statements Sentences Paragraphs Sections Procedures Declaratives Portion HP COBOL Manual for TNS and TNS/R Programs —522555-006 8 -3 Procedure Division Statements Statements A statement is a syntactically valid combination of words and symbols beginning with a COBOL verb. Where a statement ends depends on its context. Table 8-1. Where Statements End Statement is … Statement ends … in a sequence of statements and is not the last one immediately before the verb of the next statement inside another statement either immediately before the keyword that begins the next portion of a containing statement or at the period separator that terminates its containing sentence isolated or the last statement in a sequence See Scope of Statements. Figure 8-2. Statement Examples CLOSE MY-FILE statement IF SOME-COND MOVE 1 TO X MOVE 2 TO Y statement statement MOVE 3 TO Z . statement statement ADD 1 TO A-COUNT ON SIZE ERROR DISPLAY "TILT" STOP RUN END-ADD statement statement statement VST509.vsd Table 8-2. Statement Types Statement Type Definition Imperative Specifies an unconditional action for the process to take Conditional Specifies that the truth value of a condition is to be determined and that the subsequent action of the run unit depends on this truth value Delimited-scope Terminates in its explicit scope terminator Compiler-directing Causes the compiler to take some specific action during compilation HP COBOL Manual for TNS and TNS/R Programs —522555-006 8 -4 Procedure Division Statements Topics: • • • • Imperative Statement Conditional Statement Delimited-Scope Statement Scope of Statements Imperative Statement An imperative statement specifies an unconditional action for the process to take. Each imperative statement begins with an imperative verb. Table 8-3. Imperative Verbs ACCEPT DISPLAY MULTIPLY1 STOP ADD 1 DIVIDE1 OPEN STRING3 ALTER ENTER7 PERFORM SUBTRACT1 CALL3 EXIT8 READ4 UNLOCKFILE6 CANCEL GO TO RELEASE UNLOCKRECORD6 CHECKPOINT6,9 INITIALIZE REWRITE2 UNSTRING3 CLOSE INSPECT SET WRITE5 COMPUTE1 LOCKFILE6 SORT CONTINUE MERGE START2 DELETE2 MOVE STARTBACKUP6,9 1. Without SIZE ERROR or NOT SIZE ERROR phrase or else with a scope terminator 2. Without INVALID KEY or NOT INVALID KEY phrase or else with a scope terminator 3. Without OVERFLOW, EXCEPTION, or NOT EXCEPTION phrase or else with a scope terminator 4. Without AT END, NOT AT END, INVALID KEY, or NOT INVALID KEY phrase or else with a scope terminator 5. Without INVALID KEY, NOT INVALID KEY, END-OF-PAGE, or NOT END-OF-PAGE phrase or else with a scope terminator 6. HP extension 7. In HP COBOL, analogous to CALL but used only to call non-COBOL routines 8. Limited to appearing alone in a paragraph conditional statement. This is because it can include phrases that are or are not executed depending upon the value of a a condition (for example, the delimited-scope IF statement) or upon the occurrence of an exception (for example, the delimited-scope READ statement). 9. Before RVU D46.00 and G06.00, software product revision T8107AAT (run-time library T8108AAR), the NMCOBOL compiler ignores this directive and issues a warning. An individual delimited-scope statement or a sequence of two or more imperative statements is considered to be an imperative statement under the rules for statement formation; therefore, when imperative-statement appears in a statement, it refers to one or more consecutive imperative statements and/or delimited-scope statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8 -5 Procedure Division Statements Example 8-2. Imperative Statement MOVE "Birnham Wood" TO DUNSINANE Conditional Statement A conditional statement specifies that the truth value of a condition is to be determined and that the subsequent action of the run unit depends on this truth value. Any of these statements is a conditional statement (unless it ends with an explicit scope delimiter): • • • • • • • An EVALUATE, IF, RETURN, or SEARCH statement A READ statement with the AT END or INVALID KEY phrase A WRITE statement with the INVALID KEY or END-OF-PAGE phrase A DELETE, REWRITE, or START statement with the INVALID KEY phrase An arithmetic statement (ADD, COMPUTE, DIVIDE, MULTIPLY, or SUBTRACT) with the SIZE ERROR phrase A STRING or UNSTRING statement with the OVERFLOW phrase A CALL statement with the EXCEPTION phrase (or the OVERFLOW phrase, which is obsolete for the CALL statement) The NOT AT END, NOT INVALID KEY, NOT END-OF-PAGE, NOT SIZE ERROR, and NOT EXCEPTION phrases also make their parent statement a conditional statement. There is no NOT OVERFLOW phrase. Any conditional statement can be preceded by an imperative statement or any sequence of statements specified as equivalent to an imperative statement by the rules given in Imperative Statement. Unless it is contained within an IF statement, a conditional statement must be the last or only statement in a sentence; however, any statements listed previously can be written as a delimited-scope statement. For clarity and convenience, you are encouraged to avoid conditional statements entirely and use equivalent delimitedscope statements instead. In Example 8-3, the period ends both the IF and the AT END phrase. If there were an operation that the program had to perform after the read operation succeeded, but only when DONE-WITH-MASTER was false, you would have to package the READ statement in a separate paragraph. Then you could end the AT END phrase with a period that did not also end the IF statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8 -6 Procedure Division Statements Example 8-3. Conditional Statement IF NOT DONE-WITH-MASTER READ MASTER-FILE AT END MOVE DONE-VALUE TO MASTER-FLAG. Compare Example 8-3 to Example 8-4. Delimited-Scope Statement A delimited-scope statement is any statement that terminates in its explicit scope terminator. An explicit scope terminator is a reserved word used to delimit the scope of a conditional statement or in-line PERFORM statement. Table 8-4. Explicit Scope Terminators END-ADD END-EVALUATE END-RETURN END-SUBTRACT END-CALL END-IF END-REWRITE END-UNSTRING END-COMPUTE END-MULTIPLY END-SEARCH END-WRITE END-DELETE END-PERFORM END-START END-UNSTRING END-DIVIDE END-READ END-STRING The form of each explicit scope terminator includes the verb from the statement that it terminates. Explicit scope terminators can appear only as specified in the general formats for statements. When the appropriate explicit scope terminator follows a conditional statement, it is considered to be a delimited-scope statement instead. In Example 8-4, if there were no END-READ scope terminator, the PERFORM would be part of the AT END phrase of the (conditional) READ statement. Example 8-4. Delimited-Scope Statement IF NOT DONE-WITH-MASTER READ MASTER-FILE AT END MOVE DONE-VALUE TO MASTER-FLAG END-READ PERFORM PROCESS-MASTER-RECORD UNTIL DONE-WITH-MASTER END-IF Under the rules for statement execution, a delimited-scope statement is handled in the same manner as a conditional statement. This is because it can include phrases that are or are not executed depending upon the value of a condition (for example, the delimited-scope IF statement) or upon the occurrence of an exception (for example, the delimited-scope READ statement). HP COBOL Manual for TNS and TNS/R Programs —522555-006 8 -7 Procedure Division Statements Compiler-Directing Statement A compiler-directing statement is a COPY, REPLACE, or USE statement. It causes the compiler to take some specific action during compilation. A sentence that contains a compiler-directing statement cannot contain any other statements. Note. In some implementations of COBOL, the ENTER verb marks the beginning of an embedded routine in some other language. For this reason, ENTER is classified as a compilerdirecting verb in those implementations. The ENTER statement as implemented by HP COBOL is similar to a CALL statement but calls a routine compiled from a language other than COBOL. The COPY statement directs the compiler to include additional source text at that point in the program. The REPLACE statement directs the compiler to replace source program text. The USE statement directs the compiler to include logic in the object program that calls the designated declarative section if the condition described in the USE statement arises during execution. Example 8-5. Compiler-Directing Statement COPY NEIGHBORS-ANSWER Scope of Statements When the formation rules for one statement cause it to contain other statements, you must show the compiler the scope of both the contained and the containing statements by using scope terminators. Scope terminators either explicit or implicit. Explicit scope terminators are defined and listed under Delimited-Scope Statement. Implicit scope terminators occur at the end of a sentence and at the end of a contained statement. • • At the end of any sentence, the separator period that terminates the scope of all previous statements not yet terminated is an implicit terminator. Within any statement containing another statement, the next phrase of the containing statement following the contained statement is the implicit terminator of the scope of any unterminated contained statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8 -8 Procedure Division Statements The detailed rules for scope termination are: • A conditional statement is composed of other statements. When no delimitedscope statements occur in the conditional statement, the next phrase of the conditional statement terminates the contained statement. In this example, the ELSE phrase implicitly terminates the statement of the THEN phrase and the separator period implicitly terminates the ELSE phrase: IF CREDIT THEN PERFORM POST-CREDIT ELSE PERFORM POST-DEBIT. • When the last statement in a sentence is a conditional statement, the period separator that terminates the sentence implicitly terminates the conditional statement. In this example, the paragraph BOTTOM-LINE consists of a single sentence. The period separator that ends the sentence ends the IF statement: BOTTOM-LINE. MOVE NET-SALES TO NET-S OF SALES-REC-DISPLAY MOVE NET-PROFIT TO NET-P OF SALES-REC-DISPLAY IF NET-PROFIT < 0 DISPLAY "Get Cracking!" UPON DIST-MGR-TUBE. • When statements are contained within other statements, a period separator that terminates the sentence also implicitly terminates the scope of any contained statements not yet terminated otherwise. In this example, the period separator terminates both the READ and the IF statements: IF AUXILIARY-INPUT-TAPE READ AUX-TAPE AT END PERFORM AUX-TAPE-ENDED NOT AT END PERFORM PROCESS-AUX-REC. • A conditional statement can be nested within an IF statement, but not within any other form of conditional statement. The preceding example shows a conditional READ statement nested within an IF statement. It is not possible, for example, to have a READ statement with an AT END phrase and no END-READ terminator (making it a conditional statement) within another such READ statement’s AT END phrase. Both must be provided with scope terminators as shown in this example: READ PRIMARY-FILE AT END READ SECONDARY-FILE AT END DISPLAY "End of second file" END-READ END-READ HP COBOL Manual for TNS and TNS/R Programs —522555-006 8 -9 Procedure Division • Sentences When a delimited-scope statement is contained within another delimited-scope statement with the same verb, each explicit scope terminator terminates the statement begun by the most recently preceding, and as yet unpaired, occurrence of that verb. In this example, the first END-IF ends the second IF statement: IF A NOT > B PERFORM PHASE-1 IF A = B PERFORM PHASE-1X ELSE PERFORM PHASE-1Y END-IF PERFORM PHASE-2 ELSE PERFORM PHASE-5 END-IF Sentences A sentence is one or more statements terminated by a period separator. statement . VST114.vsd statement is described in Statements. A sentence that contains a compiler-directing statement cannot contain any other statements. When the compiler acts upon the COPY statement, that statement and its terminating period are logically replaced by whatever text the statement specified. The COPY sentence can therefore appear to be within another sentence, but once the compiler acts upon the COPY statement, the COPY sentence itself is replaced by text from a COPY library and the period separator has disappeared. When you use the delimited-scope statements of COBOL, you can write an entire paragraph with only one required period—the one at the end of the paragraph. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 10 Procedure Division Paragraphs Paragraphs A paragraph groups related sentences and statements together and identifies them by one name. Using the name, GO TO, PERFORM, SORT and MERGE statements can transfer control to the paragraph. paragraph-name . sentence VST115.vsd paragraph-name is either a COBOL word consisting of up to 30 alphanumeric characters or an integer of up to 30 digits. sentence is described in Sentences. A sentence ends with a period; therefore, a paragraph ends with the period at the end of its last sentence. Example 8-6. Paragraph With One Sentence CHK-REPORT-YY. IF CURRENT-YY IS LESS THAN 0 OR GREATER THAN 99 DISPLAY "REPORT YEAR IS NOT BETWEEN 00 AND 99, " "REENTER YEAR" ACCEPT CURRENT-YY GO TO CHK-REPORT-YY. Example 8-7. Paragraph With Several Sentences CONVERT-REPORT-DATE-TO-SERIAL-DAY. MOVE CURRENT-YY TO REPORT-SERIAL-YEAR. MOVE 0 TO DIVIDE-RESULT LEAP-YEAR. DIVIDE REPORT-SERIAL-YEAR BY 4 GIVING DIVIDE-RESULT REMAINDER LEAP-YEAR. IF LEAP-YEAR EQUAL TO 0 MOVE 1 TO LEAP-YEAR ELSE MOVE 0 TO LEAP-YEAR. ADD CURRENT-DD DAYS-TO-DATE(CURRENT-MM) GIVING REPORT-SERIAL-DAYS. IF REPORT-SERIAL-DAYS IS GREATER THAN 59 ADD LEAP-YEAR TO REPORT-SERIAL-DAYS. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 11 Procedure Division Paragraphs Usage Considerations: • Paragraph Headers Not Restricted to Area A The HP COBOL compilers accept paragraph headers that do not begin in area A; the compiler recognizes a statement by its initial verb. When the compiler recognizes the end of a sentence (by detecting the terminating period) and is prepared to accept another sentence or a paragraph, it accepts any legal paragraph header or section header whether it begins in area A or after it. • End of a Paragraph A paragraph ends immediately before the next paragraph header or section header, at the end of the Procedure Division, or when it is the last paragraph in the Declaratives Portion of the Procedure Division, at the keywords END DECLARATIVES. • Multiple Paragraph Headers (Null Paragraphs) A paragraph header can be followed immediately by another paragraph header: CHECK-THE-INPUT. GET-THE-FIRST-RECORD. READ IN-FILE ... In this case, CHECK-THE-INPUT is a null paragraph, so GO TO CHECK-THE-INPUT is equivalent to GO TO GET-THE-FIRST-RECORD but PERFORM CHECK-THE-INPUT returns control immediately to the statement following the PERFORM. • Paragraph Form Only for Use With the ALTER Statement There is a simpler form of the paragraph used in conjunction with an ALTER statement. For details, see ALTER. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 12 Procedure Division Sections Sections A section groups related sentences and paragraphs together and identifies them by one name. Using the name, GO TO, PERFORM, SORT and MERGE statements can transfer control to the section. section-name . SECTION segment-number sentence paragraph VST116.vsd section-name is either a COBOL word consisting of up to 30 alphanumeric characters or an integer of up to 30 digits. segment-number is a numeric literal of 1 or 2 digits. sentence is described in Sentences. paragraph is described in Paragraphs. Usage Considerations: • Section Format ° Beginning After the period separator that precedes the first paragraph of a section, do not put anything on the same text line except space characters or a USE statement. ° End A section ends at the next section header, at the physical end of the Procedure Division, or at the keywords END DECLARATIVES. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 13 Procedure Division • Procedures Standard COBOL Format To conform to the COBOL standard, observe these rules. (HP COBOL compilers do not require that you follow these rules.) ° If you use sections, put all paragraphs in sections If the Procedure Division contains sections, put every paragraph in a section. (This means that if the Procedure Division contains a Declaratives Portion, which always contains at least one section, then each paragraph in the Procedure Division must be in a section.) ° Start each section on a separate line and follow section header immediately by paragraph header Start each section on a separate line, with the section-name beginning in area A and nothing but space characters preceding it. • Independent Segments An independent segment is a section whose segment-number is greater than 49. Independent segments are relevant only to the ALTER statement, which you are advised not to use because the 1985 COBOL standard classifies it as an obsolete element. (Use a MOVE statement and a conditional GO TO statement instead.) Procedures A procedure is a paragraph, a group of successive paragraphs, a section, or a group of successive sections executed as a unit under the control of a PERFORM statement. paragraph section VST415.vsd paragraph is described in Paragraphs. section is described in Sections. There is a distinct difference between procedure-name and procedure. A procedurename refers to a paragraph or section in the source program. A procedure-name is either a section-name or a paragraph-name (which can be qualified by a sectionname). A procedure is a paragraph, a group of successive paragraphs, a section, or a group of successive sections to be executed as a unit. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 14 Procedure Division Declaratives Portion The term procedure can also refer to the set of paragraphs or sections executed under control of a PERFORM procedure-name or a PERFORM procedure-name THROUGH procedure-name statement. When the term is used in this dynamic sense, one procedure can contain or overlap another procedure. The rules of COBOL do not require that the relationships between members of this set of be obvious; that is, the set of paragraphs executed by a PERFORM statement is determined by control flow, not solely by the order of the paragraphs in the source file. Declaratives Portion The optional Declaratives Portion is one or more sections at the beginning of the Procedure Division, bracketed by the keyword DECLARATIVES and the keywords END DECLARATIVES, that are executed individually when certain conditions arise during execution of statements in the rest of the Procedure Division. The Declaratives Portion is reserved for debugging routines and input-output error routines specified by USE statements. When used, this area must be coded immediately after the Procedure Division heading. DECLARATIVES section-name . . SECTION segment-number use-sentence paragraph DECLARATIVES END section . VST117.vsd section-name segment-number are described in Sections. use-sentence is a sentence containing only a USE statement. paragraph is described in Paragraphs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 15 Procedure Division Execution of the Procedure Division section is described in Sections. Example 8-8. Procedure Division with a Declaratives Portion PROCEDURE DIVISION. DECLARATIVES. IN-FILES-USE SECTION. USE AFTER STANDARD ERROR PROCEDURE ON IN-FILE. IN-FILES-PARA. ... END DECLARATIVES. BEGIN-MY-PROGRAM SECTION. ... Execution of the Procedure Division Execution of a run unit begins with the first procedure (that is, section or paragraph) of the Procedure Division, excluding any declarative sections. Except where specific rules indicate otherwise, sections are executed in the order in which they appear within the source program. Similarly, paragraphs are executed in the order in which they appear within their sections, sentences are executed in the order in which they appear within their paragraphs, and statements are executed in the order in which they appear within their sentences. Topics: • • • • • • Statement Execution Sentence Execution Paragraph Execution Section Execution Procedure Execution Declaratives Portion Execution Statement Execution An individual imperative statement is always executed in its entirety. If the statement is followed within its sentence by another statement, control then passes to that statement; otherwise, control passes to the next executable sentence. A conditional statement or a delimited-scope statement is not necessarily executed in its entirety. Instead, the truth value of the condition in the statement causes the object program to select between alternate paths of control. Because the specific possibilities depend upon the particular statement, they are discussed along with the individual statement descriptions. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 16 Procedure Division Sentence Execution The compiler-directing statements COPY, REPLACE, and USE do not participate in execution; therefore, control is never transferred to or from these statements. Sentence Execution A sentence containing only imperative statements is always executed in its entirety. Normally, control then passes to the next sentence in the paragraph that contains an imperative or conditional statement. Exceptions to this rule are: • • • When the last statement in the sentence is a GO TO statement, control is transferred unconditionally to the specified paragraph or section. When the last statement in the sentence is a STOP RUN statement, execution of the run unit, and thus the program, terminates. When the last statement in the sentence is an EXIT PROGRAM statement, control is transferred in accordance with the rules for that statement. If the sentence is not followed within its paragraph by any other sentence that contains an imperative, conditional, or delimited-scope statement, and none of the preceding cases applies, then control passes to the first executable sentence in another paragraph. The paragraph to which control passes is determined by the rules described under Paragraph Execution. A sentence containing a conditional or delimited-scope statement is not necessarily executed in its entirety. After executing any initial imperative statements, the execution of the conditional or delimited-scope statement causes the object program to select the appropriate path of control. Control is never transferred to or from sentences that consist of a compiler-directing statement. Paragraph Execution Execution of a paragraph begins with the execution of the first sentence containing an imperative, conditional, or delimited-scope statement. Except for the nested execution of other procedures or programs (for example, by the execution of PERFORM or CALL statements) control remains within the paragraph until either: • • The execution of a GO TO, STOP RUN, or EXIT PROGRAM statement transfers control out of the paragraph. The final executable sentence of the paragraph completes without explicitly transferring control to some other procedure. In this case, control passes to the next paragraph of the same section if one exists or to the next section in the source program, except in these situations: 1. The rules for the implicit transfer of control among procedures, described later, can cause control to revert to some other paragraph or section instead. 2. If no such reversion occurs, and no next section exists, execution of the program terminates. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 17 Procedure Division Section Execution During the execution of a paragraph, control passes to successive sentences unless this order is modified by a conditional or delimited-scope statement or a GO TO, STOP RUN, CALL, ENTER, or EXIT PROGRAM statement. Execution of a paragraph that does not have any sentences involves only the passing of control described for Item 2. Section Execution Execution of a section normally consists of serial execution of its paragraphs; however, this order can be modified by explicit transfer statements (for example, a GO TO statement) and the rules for implicit transfer of control. Execution of the section terminates when either: 1. The execution of a GO TO, STOP RUN, or EXIT PROGRAM statement transfers control out of the section. 2. The final paragraph of the section completes without explicitly transferring control to some other section. In this case, control passes to the next section of the source program, except in these situations: • • The rules for the implicit transfer of control among procedures, described later, can cause control to revert to some other section instead. If no such reversion occurs, and the section is the last one in the source program, the execution of the program terminates. Execution of a section that does not have any paragraphs involves only the passing of control described for Item 2. Implicit Transfer of Control The mechanism that transfers control from statement to statement in the sequence in which they appear in the source program is an implicit transfer of control. This mechanism applies unless it is overridden by an explicit transfer of control or the absence of a next executable statement to which control can be passed. Explicit Transfer of Control An explicit transfer of control consists of execution of one of these statements: • • • • • • • Conditional CALL ENTER Delimited-scope statement EXIT PROGRAM (when executed in a called program) GO TO PERFORM HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 18 Procedure Division Section Execution COBOL provides these types of implicit transfers of control that override the statementto-statement mechanism: 1. When a paragraph is being executed under control of another COBOL statement (for example, MERGE, PERFORM, SORT, and USE), and it is the last paragraph in the range of the controlling statement, an implied transfer of control occurs from the last statement in the paragraph to the control mechanism of the controlling statement. If several controlling statements are active, the transfer is to the last statement executed. Furthermore, if a paragraph is being executed under the control of a PERFORM statement that causes iterative execution and that paragraph is the first one in the range of the PERFORM statement, an implicit transfer of control occurs between the control mechanism associated with the PERFORM statement and the first executable statement in the paragraph for each iterative execution of the paragraph. 2. When a SORT or MERGE statement is executed, an implicit transfer of control occurs to any associated input or output procedures. Another implicit transfer of control occurs after the execution of such a procedure, as described in Item 1. 3. When the execution of any COBOL statement causes the condition described in the USE statement of a declarative section, an implicit transfer of control occurs to that section. Another implicit transfer of control occurs after the execution of the declarative section, as described in Item 1. The statement-to-statement transfers of control ignore the existence of COPY, REPLACE, and USE statements. Although control never passes to a USE statement itself, the existence of a USE statement generates the control mechanism for implicit transfers of control to and from the section in which it appears. The term next executable statement refers to the next COBOL statement to which a process is to transfer control according to the rules given previously and the rules associated with each language element in the Procedure Division. There is no next executable statement in these situations: 1. The execution of the last statement in a program does not cause an explicit transfer of control, and the paragraph in which it appears is not being executed under the control of some other COBOL statement. Following the execution of such a statement, execution of the program terminates. When it is a called program, control reverts to the calling program as if an EXIT PROGRAM statement were executed; otherwise, execution of the run unit terminates as if a STOP RUN statement were executed. 2. The program contains no Procedure Division. Execution of such a program proceeds as if it contained a Procedure Division with a single paragraph consisting of a CONTINUE statement. Control then passes from the program as described in Item 1. 3. An EXIT PROGRAM statement is executed within a called program. In this case, control reverts to the calling program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 19 Procedure Division Procedure Execution 4. A STOP RUN statement is executed within any program. In this case, execution of the run unit terminates. 5. The last statement in the Declaratives Portion of a program completes execution without causing an explicit transfer of control, and its paragraph is not the designated end of a PERFORM … THROUGH procedure group. Following the execution of such a statement in these circumstances, control reaches the end of the Declaratives Portion, causing execution of both the program and the run unit to terminate abnormally. Both the program and the run unit terminate abnormally because execution of a declarative section is expected to be done by a PERFORM statement with these characteristics: • • An explicit PERFORM statement in the Declaratives Portion or somewhere in the rest of the Procedure Division An implicit PERFORM statement executed due to either the use of the COBOL debugging module or an input-output statement’s encountering an error In the latter case, if the error was recoverable, control returns to the statement following the input-output statement; if the error was not recoverable, execution of the run unit terminates. If you transfer control directly to a procedure in a declarative section from a GO TO statement anywhere in the Procedure Division, there is no next executable statement when execution reaches the end of the declarative section. Procedure Execution A procedure is a paragraph, a group of successive paragraphs, a section, or a group of successive sections executed as a unit. See Paragraph Execution and Section Execution. Declaratives Portion Execution The sections of the Declaratives Portion are executed individually when certain conditions arise during execution of statements in the rest of the Procedure Division (see Section Execution). HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 20 Procedure Division Common Semantic Rules Common Semantic Rules The semantic rules about operand identification and overlapping operands apply to several statements. Their explanations use these terms: Term Definition Sending data item A data item whose value is to be used in an operation Receiving data item A data item to which the result of an operation is to be assigned Intermediate data item A conceptual signed numeric data item used as a temporary repository for the result being developed during the execution of an arithmetic operation Operand Identification An operand in a statement is either an identifier (which specifies a data item directly) or a condition-name associated with a conditional variable (which specifies a data item indirectly). In either case, the particular data item must be identified before the operand can be used in executing the statement. Operand identification proceeds in this order: 1. Qualifiers If an operand contains qualifiers, the compiler uses them to determine the correct interpretation of the operand name. 2. Subscripts If an operand contains subscripts, the run-time routines evaluate them from left to right. 3. Size If an operand has variable size, the run-time routines determine its appropriate size. The appropriate size is usually the operand’s current actual size, but if the operand is a receiving item, its appropriate size is sometimes its maximum size. For details, see OCCURS Clause for Variable-Size Tables. 4. Reference Modifier If the operand contains a reference modifier, the run-time routines evaluate the reference modifier. Unless the rules for a statement state otherwise, identification of each operand in a statement occurs exactly once as the first operation (or series of operations) in the execution of that statement. The identification of an operand only determines which data item is specified, it does not evaluate or affect the content of the data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 21 Procedure Division Overlapping Operands Overlapping Operands When a sending and a receiving data item in a statement overlap—that is, when they share part or all of their storage areas but are not defined by the same data description entry—the result of the statement is undefined. Results are also undefined for some statements in which sending and receiving data items are defined by the same data description entry. Such cases are noted in the descriptions of those statements. Common Phrases These phrases are common to several different statements: • • • • • CORRESPONDING Phrase ROUNDED Phrase SIZE ERROR Phrase FROM Phrase INTO Phrase CORRESPONDING Phrase For the purposes of this discussion, d1 and d2 are identifiers in a statement containing a CORRESPONDING phrase and: • • • Both d1 and d2 designate group (but not level 66) data items. The data description entries of d1 and d2 do not contain USAGE INDEX clauses. The data description entries of one or both of d1 and d2 can include REDEFINES or OCCURS clauses or be subordinate to items whose data description entries include these clauses. A pair of data items, one subordinate to d1 and one subordinate to d2, correspond if they follow these rules: • • • • Both data items have the same data-name and the same potential set of qualifiers up to, but not including, d1 and d2. Neither data item has the data-name FILLER. The data description entries of the items do not contain REDEFINES, RENAMES, OCCURS, or USAGE INDEX clauses. In a MOVE statement, at least one of the data items is an elementary data item, and it is legal to move the sending item to the receiving item. In an ADD or SUBTRACT statement, both items are elementary numeric data items. If a data item does not qualify as a corresponding item, then none of its subordinates qualify either. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 22 Procedure Division ROUNDED Phrase In Example 8-9, assume that the records A and H obey all of the preceding rules. The statement MOVE CORRESPONDING A TO H is equivalent to this series of MOVE statements: MOVE MOVE B OF A G OF F OF A TO TO B OF H G OF F OF H Example 8-9. CORRESPONDING Phrase 01 A 03 03 03 01 B 07 07 E F 04 C D H 05 05 05 G F 08 B C 09 09 09 G E D G ROUNDED Phrase When the number of fraction digits in the result of an arithmetic operation exceeds the number of fraction digits in the receiving item, the excess digits must be deleted by either truncation or rounding. Also, when one or more low-order integer positions in a receiving item are represented by P in the item’s PICTURE character-string, equivalent digits in a result value must be deleted by truncation or rounding. When the ROUNDED phrase is not specified, excess digits are deleted by truncation; that is, the digits are simply discarded. If rounding is specified, the absolute value of the retained portion of the value is increased by 1 whenever the most significant digit of the excess is greater than or equal to 5. In these examples, the caret (^) represents the assumed decimal point: Actual Result PICTURE Character-String of Receiving Item Rounded Value 5^71489 9V999 5^715 7650^ 99PP 77 3^141592654 9V99 3^14 SIZE ERROR Phrase The size error condition indicates a problem in computation, such as a loss of precision. The SIZE ERROR and NOT SIZE ERROR phrases of the ADD, COMPUTE, DIVIDE, MULTIPLY, and SUBTRACT statements enable you to test whether the arithmetic operation caused the size error condition to arise. You cannot test for the size error condition with an IF statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 23 Procedure Division SIZE ERROR Phrase The situations that cause the size error condition are: • Exponentiation If the program attempts to raise zero to the zero power, or if no real number exists as the result of the exponentiation, the arithmetic operation is terminated and the size error condition arises. • Division If the program attempts to divide any value by zero, the arithmetic operation is terminated and the size error condition arises. • Overflow If, after decimal point alignment, the absolute value of a result exceeds the largest value that can be contained in the receiving data item, a size error condition arises. The size error condition applies to intermediate and final results. If the ROUNDED phrase is specified, rounding occurs before checking for a size error. When a size error condition occurs, the subsequent action depends on whether the SIZE ERROR and NOT SIZE ERROR phrases are specified. Usage Considerations: • SIZE ERROR Phrase and TRAP2 Directive Note. The NMCOBOL compiler, which has traps set by default, ignores the TRAP2 directive and issues a warning. The SIZE ERROR phrase catches size errors in COMPUTATIONAL arithmetic that the TRAP2 directive (which is the default) does not; however, the SIZE ERROR phrase generates more code than the TRAP2 directive does. In Example 8-10, C=A+B causes a size error that the TRAP2 directive does not catch, but that the SIZE ERROR phrase does catch. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 24 Procedure Division SIZE ERROR Phrase Example 8-10. SIZE ERROR Phrase and TRAP2 Directive WORKING-STORAGE SECTION. 77 A PIC 99 COMP VALUE 99. 77 B PIC 99 COMP VALUE 88. 77 C PIC 99 COMP. 77 D PIC 99 COMP. PROCEDURE DIVISION. ... * TRAP2 directive does not catch this size error: COMPUTE C = A + B. COMPUTE D = C - B. DISPLAY D. * ON SIZE ERROR phrase catches this size error: COMPUTE C = A + B ON SIZE ERROR DISPLAY "Too Big" NOT ON SIZE ERROR DISPLAY "Acceptable". ... • COMPUTATIONAL Data Items If an arithmetic computation stores a value in a COMPUTATIONAL data item, and the decimal representation of that value exceeds the number of decimal places in the item’s PICTURE clause (as in C = A + B in the preceding example), a later attempt to use that value (as in D = C - B in the preceding example) can cause arithmetic overflow. HP COBOL can retrieve a number larger than 9,999 from a PICTURE S9(4) COMPUTATIONAL field (even though the storage unit is 2 bytes and can therefore accommodate values from -32,767 through +32,767), but arithmetic overflow is likely. The largest value HP COBOL can use in a 4-byte COMPUTATIONAL item is 999,999,999 (not 2,147,483,647). The largest value HP COBOL can use in an 8-byte COMPUTATIONAL item is 999,999,999,999,999,999 (not 9,223,372,036,854,775,807). If you need the full capacity of 2-byte, 4-byte, and 8-byte storage, describe the item as USAGE NATIVE-2, NATIVE-4, or NATIVE-8 (with no PICTURE) or COMPUTATIONAL-5. • SIZE ERROR and Multiple Results When a statement includes more than one receiving item, the decision to assign a result value or cause a size error condition is determined independently for each such item; therefore, if the size error condition does not occur for a particular receiving item, that item is assigned its correct result value even when the size error condition exists for one or more other receiving items of the same statement (unless the run terminates abnormally because of an arithmetic overflow). HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 25 Procedure Division • SIZE ERROR Phrase Values Undefined When SIZE ERROR Phrase is Absent When a size error condition occurs during execution of a statement for which the SIZE ERROR phrase is not specified, a trap 2 (arithmetic overflow) occurs unless a NOTRAP2 directive has suspended arithmetic overflow trapping. If a NOTRAP2 directive has suspended arithmetic overflow trapping, results are undefined. Note. The NMCOBOL compiler, which has traps set by default, ignores the NOTRAP2 directive and issues a warning. Use the NOTRAP2 directive only during the process of conversion from COBOL 74 to HP COBOL. It is provided to enable programs that do not include SIZE ERROR phrases to be compiled and executed in HP COBOL without investing programmer time in analyzing the potential for overflow problems. The availability of this directive might be discontinued in HP COBOL after a period of time. • Values Remain Untouched When SIZE ERROR Phrase is Present When a size error condition occurs during execution of an arithmetic statement for which the SIZE ERROR phrase is specified, the value of the affected receiving data items is not altered. That is, these data items retain whatever values they held before the size error condition arose. Unaffected data items receive new values as expected. The program has no mechanism by which it can determine which data items were the cause of the size error condition. • SIZE ERROR, NOT SIZE ERROR, and Transfer of Control After completion of the execution of the arithmetic operations, if the size error condition occurred, the imperative statement in the SIZE ERROR phrase is executed. If execution of the imperative statement causes explicit transfer of control (due to a procedure branching or conditional statement) control is transferred according to the rules for that statement; otherwise, when the imperative statement has been executed, control passes to the end of the arithmetic statement and the NOT SIZE ERROR phrase (if any) is ignored. When no size error condition occurs during the execution of an arithmetic statement, the SIZE ERROR phrase (if any) is ignored, and control passes to the NOT SIZE ERROR phrase (if one is present) or to the end of the arithmetic statement. If execution of the imperative statement causes explicit transfer of control (due to a procedure branching or conditional statement), control is transferred according to the rules for that statement. • CORRESPONDING Phrase and the Size Error Condition When the CORRESPONDING phrase appears in an ADD or SUBTRACT statement and any of the individual operations produces a size error condition, the imperative statement in the SIZE ERROR phrase is not executed until all the individual additions or subtractions are completed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 26 Procedure Division FROM Phrase FROM Phrase The FROM phrase is an optional component of the RELEASE, REWRITE, and WRITE statements, all of which specify a record-name as their primary operand. The identifier in the FROM phrase and the record-name must not reference the same storage area or overlapping storage areas. The result of executing a statement that specifies the FROM phrase is equivalent to the execution of these statements in this order: 1. “MOVE identifier TO record-name” executed in accordance with the rules specified for the MOVE statement 2. The same RELEASE, REWRITE, or WRITE statement without the FROM phrase After execution of the actual statement is complete, the information in the storage area specified by the identifier is available, even though the information in the area specified by record-name is not available (except as specified by the SAME AREA clause). INTO Phrase The INTO phrase is an optional component of the READ and RETURN statements, both of which specify a file name as their primary operand. This phrase can be specified in a READ or RETURN statement only if either: • • The specified file has only one associated record description entry. The data description entry for the data item specified by the identifier in the INTO phrase and all record description entries associated with the file describe data structures or elementary alphanumeric items. The storage area specified by the identifier in the INTO phrase must not be the same as or overlap the record area associated with the file identified by the file name. The result of executing a statement that specifies the INTO phrase is equivalent to: 1. Execution of the same READ or RETURN statement without the INTO phrase (which obtains a logical record of the file) 2. After successful execution of the READ or RETURN statement, assignment of the current record in the file record area to the data item specified by the identifier in accordance with the rules for the MOVE statement; therefore (except for a destination described with the JUSTIFIED clause), long records are truncated at the right, and short records are padded at the right with spaces according to the standard alignment rules. The size of the current record is the size of the record when it was written (see RECORD CONTAINS Clause). The record is then available in both the record area of the file and the storage area associated with the data item specified by the identifier. The move operation does not occur unless execution of the READ or RETURN statement was successful. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 27 Procedure Division Input-Output Input-Output These topics are common to several input-output statements: • • • • I-O Status Code Diagnosing Input-Output Errors Recovering from Input-Output Errors Timed Input and Output I-O Status Code Each file-control entry can include a FILE STATUS clause that designates a 2character file-status data item declared elsewhere in the program as the receptacle for that file’s I-O status code. The leftmost character position of the file-status data item is Status Key 1. The rightmost character position of the file-status data item is Status Key 2. Whenever a program executes a CLOSE, DELETE, LOCKFILE, OPEN, READ, REWRITE, START, UNLOCKFILE, UNLOCKRECORD, or WRITE statement for a file that has a FILE STATUS clause, the run-time routines record the I-O status code in the specified file-status data item. The storage operation occurs prior to the execution of any applicable USE procedure or any applicable imperative statement associated with the input-output statement (in AT END, NOT AT END, INVALID KEY, or NOT INVALID KEY phrases). The I-O status code indicates the success or failure of the input-output statement, and (if failure), the reason for the failure. Table 8-6 through Table 8-11 show the possible values of the file-status data item. Topics: • • Status Key 1 Status Key 2 HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 28 Procedure Division I-O Status Code Status Key 1 The leftmost character position of the file-status data item is known as Status Key 1 and is set for these conditions. Table 8-5. Status Key 1 Values Value Condition Explanation 0 Successful completion The input-output operation was completed without error. 1 At-end condition A sequential READ statement was unsuccessfully executed as a result of one of: • • 2 Invalid-key condition The physical end of the file was reached. An optional file was not present. The input-output statement was unsuccessfully executed as a result of one of: • • • • Sequence error Duplicate key No record found Boundary violation 3 Permanent error The input-output statement was unsuccessfully executed as a result of a boundary violation for a sequential file or as a result of an input-output error, such as data check, parity error, or transmission error. 4 Logic error The input-output statement was unsuccessfully executed because the program attempted an improper sequence of input-output operations or because a user-defined limit was violated. 9 Implementor-defined error Implementor-defined error means the input-output statement was unsuccessfully executed as a result of one of: • • Program logic error File description inconsistent with associated file HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 29 Procedure Division I-O Status Code Status Key 2 The rightmost character position of the file-status data item is known as Status Key 2 and further describes the results of an input-output operation. Table 8-6. Status Key 2 Values: Successful Completion I-O Status Code File Exception Condition “00” The input-output statement executed successfully, and no further information concerning the input-output operation is available. “02” The input-output statement executed successfully, but a duplicate key is detected in one of these ways: • • For a READ statement, the key value for the current key of reference is equal to the value of that same key in the next record within the current key of reference For a REWRITE or WRITE statement, the record just written created a duplicate key value for at least one alternate record key for which duplicates are allowed. “04” A READ statement executed successfully, but the length of the record being processed does not conform to the fixed file attributes for that file. “05” The input-output statement executed successfully; however, for an OPEN statement, the referenced optional file is not present at the time the OPEN statement is executed (if the open mode is I-O or EXTEND, the file has been created). “07” The input-output statement executed successfully, but a requested option could not be done for of one of these reasons: • • “97” For a CLOSE statement with the NO REWIND, REEL or UNIT REMOVAL phrase or for an OPEN statement with the NO REWIND phrase, the referenced file does not reside on a reel/unit medium. For an OPEN statement that references a file that qualifies for HP COBOL Fast I-O, sufficient memory for HP COBOL Fast I-O was not available. The input-output statement is successfully executed, but the circumstances were not entirely as expected. For an OPEN statement, either the referenced file has labels and LABEL RECORDS OMITTED was specified, or it does not have labels and LABEL RECORDS STANDARD was specified. For a READ statement, the retrieved record is currently locked, whether through some other file name of the run unit or by some other process. For a START statement, the start operation performed a read operation to validate a position, and the record that was read was locked. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 30 Procedure Division I-O Status Code Table 8-7. Status Key 2 Values: Unsuccessful Completion—At-End Condition I-O Status Code File Exception Condition “10” A sequential READ statement is attempted and no next logical record exists in the file because the logical end of the file has been reached. “14” A sequential READ statement is attempted for a relative file, but the relative record number cannot be assigned to the relative key data item described for the file without a loss of significance. Table 8-8. Status Key 2 Values: Unsuccessful Completion—Invalid-Key Condition I-O Status Code File Exception Condition “21” A sequence error exists for a sequentially-accessed Indexed file. The prime record key value has been changed by the program between the successful execution of a READ statement and the execution of the next REWRITE statement for that file, or the ascending sequence requirements for successive record key values are violated. “22” An attempt has been made to write or rewrite a record that would create a duplicate relative key, a duplicate prime record key, or a duplicate alternate record key for which uniqueness is required. “23” An attempt has been made to access a record identified by a key, and that record does not exist in the file. “24” An attempt has been made to write beyond the externally-defined boundaries of a relative or indexed file, or a sequential WRITE statement is attempted for a relative file but the relative record number cannot be assigned to the relative key data item described for the file without a loss of significance. Table 8-9. Status Key 2 Values: Unsuccessful Completion—Permanent Error Condition (page 1 of 2) I-O Status Code File Exception Condition “30” A permanent error exists and no further information is available concerning the input-output operation. “34” A permanent error exists because of a boundary violation. This condition indicates that an attempt has been made to write beyond the externally-defined boundaries of a sequential file. “35” A permanent error exists because an OPEN statement with the INPUT, I-O, or EXTEND phrase is attempted on a required file that is not present. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 31 Procedure Division I-O Status Code Table 8-9. Status Key 2 Values: Unsuccessful Completion—Permanent Error Condition (page 2 of 2) I-O Status Code File Exception Condition “37” A permanent error exists because an OPEN statement is attempted on a file that is required to be a disk file but is supported on some other medium. “38” A permanent error exists because an OPEN statement is attempted on a file previously closed with lock. “39” The OPEN statement is unsuccessful because a conflict has been detected between the fixed file attributes and the attributes specified for that file in the program. Table 8-10. Status Key 2 Values: Unsuccessful Completion—Logic Error Condition (page 1 of 2) I-O Status Code File Exception Condition “41” An OPEN statement is attempted for a file already in the open mode, or for one in a set of files that resides on a multiple file reel set when some other file in that set is already in the open mode. “42” A CLOSE, LOCKFILE, or UNLOCKFILE statement is attempted for a file not in the open mode. “43” In the sequential access mode, the last input-output statement executed for the file prior to the execution of a DELETE or REWRITE statement was not a successfully executed READ statement. “44” A boundary violation exists for one of these reasons: • • “46” An attempt is made to write or rewrite a record that is larger than the largest record description entry specified for the associated file name or smaller than the smallest record allowed by the RECORD clause of the associated file name. An attempt is made to rewrite a record to a Sequential file and the record is not the same size as the record being replaced. A sequential READ statement is attempted on a file open in the input or I-O mode and no valid next record has been established for one of these reasons: • • The preceding START statement was unsuccessful. The preceding READ statement was unsuccessful but did not end at an atend condition. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 32 Procedure Division Diagnosing Input-Output Errors Table 8-10. Status Key 2 Values: Unsuccessful Completion—Logic Error Condition (page 2 of 2) I-O Status Code File Exception Condition “47” The execution of a READ or START statement is attempted on a file not open in the Input or I-O mode. “48” The execution of a WRITE statement is attempted on a file not open in the I-O, Output, or Extend mode. “49” The execution of a DELETE or REWRITE statement is attempted on a file not open in the I-O mode. Table 8-11. Status Key 2 Values: Unsuccessful Completion—Conditions Defined by HP I-O Status Code File Exception Condition “90” A Logic Error has occurred; it is not one of those defined under the “4x ” codes, and no recovery is possible. “91” An I-O Error from which recovery might be possible has occurred. Diagnosing Input-Output Errors The I-O status code returned to the program indicates what type of input-output error occurred. The run-time routines send diagnostic messages for permanent error conditions and logic error conditions to the home terminal (or designated execution-log file), regardless of whether an error is recoverable. You must examine the I-O status code and to determine whether an unsuccessful input-output operation must cause the program to terminate abnormally or allow it to continue processing. To facilitate program execution and error recovery, the COBOL run-time input-output errors are classified as either: • • Program Logic Errors External Errors Program Logic Errors A program logic error is considered nonrecoverable and causes the program to terminate abnormally after execution of any applicable declarative section. This type of error causes I-O status code “4x ” where x is a decimal digit, or I-O status code “90” (for errors defined by HP). HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 33 Procedure Division Diagnosing Input-Output Errors External Errors An external error is recoverable if the program includes an associated declarative section; otherwise, an external error causes the program to terminate abnormally. The types of recoverable input-output errors are: • • An external error that has an associated operating system input-output error causes I-O status code “30”. The run-time routine then calls the FILEERROR procedure to check whether an operation can be retried. If the operation is not retried, the operating system reports an error, giving the file name and the filesystem error number, which the run-time routine includes in an error message that it delivers to the process’s log file (usually the home terminal). An external input-output failure that is not related to an operating system error causes the return of I-O status code “91”. The format of the run-time error message depends on the environment. For details, see Section 48, Run-Time Diagnostic Messages. The run-time routines can also generate warnings, indicating that a minor error condition exists. A warning message is issued, but no declaratives or error actions are executed, and the program continues. Each COBOL run unit contains a special register called GUARDIAN-ERR, a COMPUTATIONAL data item defined as PIC 9(4) COMPUTATIONAL. The process updates this register each time it executes an input-output statement. The value of GUARDIAN-ERR is delivered to the run-time routines by the operating system upon its completion of the requested input-output statement. Do not use the library routine COBOLFILEINFO or the Guardian routine FILEINFO to retrieve the error, because they can return incorrect values. Note. GUARDIAN-ERR augments, but does not replace, the I-O status code. The value of GUARDIAN-ERR derives only from the operating system. The run-time routines merely make the value available for the process to examine after the process has examined the appropriate I-O status code. Table 8-12 is provided for your guidance only. The final authority on the meaning of the values of GUARDIAN-ERR is the current documentation of the operating system. Table 8-12 is not exhaustive; values other than those shown for GUARDIAN-ERR might be returned. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 34 Procedure Division Diagnosing Input-Output Errors Table 8-12. I-O Status Codes Augmented by GUARDIAN-ERR (page 1 of 5) Status Code GUARDIAN-ERR Value COBOL Statement(s) Cause of Status Code “00” 0 All Operation was successful 6 READ sequential Read from $RECEIVE and system message was read. Operation was still successful “04” 0 READ Record on file shorter than expected “05” 11 OPEN Open for INPUT, I-O, or EXTEND— OPTIONAL specified and file does not exist 14 OPEN Open for INPUT, I-O, or EXTEND— OPTIONAL specified and device does not exist for a temporary file 0 OPEN Insufficient memory for HP COBOL Fast I-O 0 CLOSE NO REWIND, OPEN NO REWIND NO REWIND on a device that is not a tape 0 CLOSE REEL REEL/UNIT on a device that is not a tape “10” 1 READ sequential End of file “21” 0 WRITE (indexed file) Sequence violation 11 REWRITE with sequential access Record does not exist 23 REWRITE with sequential access Relative key out of bounds 46 REWRITE with sequential access Invalid key specified 10 REWRITE Alternate key without duplicates already exists 10 WRITE Record already exists “07” “22” xxx = Whatever file-system error is returned HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 35 Procedure Division Diagnosing Input-Output Errors Table 8-12. I-O Status Codes Augmented by GUARDIAN-ERR (page 2 of 5) Status Code GUARDIAN-ERR Value “23” “24” COBOL Statement(s) Cause of Status Code 0 READ random (relative file) The position not as expected 0 START On an optional file that is missing or record at that position not desired one 1 START Record not found before EOF 1 READ random (relative or indexed file) Record does not exist or relative file has reached end 11 DELETE, READ random, REWRITE Record does not exist 23 DELETE, READ random, REWRITE, START Relative key out of bounds 46 DELETE, READ random, REWRITE, START Invalid key specified 23 WRITE Relative key out of bounds 45 WRITE File is full 46 WRITE Invalid (duplicated) key specified) xxx = Whatever file-system error is returned HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 36 Procedure Division Diagnosing Input-Output Errors Table 8-12. I-O Status Codes Augmented by GUARDIAN-ERR (page 3 of 5) Status Code GUARDIAN-ERR Value COBOL Statement(s) Cause of Status Code “30” xxx CLOSE Fatal error on WRITE to write final block, or to write held spacing or record for print files, or attempt to write tape marks on tape failed xxx CLOSE REEL Reel swap failed xxx DELETE Attempt to position failed, or attempt to delete record failed, or attempt to reposition after deletion failed xxx LOCK, UNLOCK Attempt to lock/unlock file or record failed xxx LOCK, UNLOCK Wait on preread of file failed xxx OPEN System open failed; position for EXTEND failed; purge for existing file failed; create for nonexistent file failed; or other system call failed xxx READ random System error on read xxx READ sequential System error on read; reel swap failed xxx REWRITE System error on position request; replace failed xxx START System error on position request xxx WRITE System error on various operations 11 OPEN Opening for OUTPUT, I-O or EXTEND on file with alternate keys when no FUP CREATE has been done to create file 18 OPEN The node that file is on is not up 40 LOCKFILE, READ, START Operation timed out 73 LOCKFILE, READ, START Record in file locked 45 CLOSE, WRITE File is full “34” xxx = Whatever file-system error is returned HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 37 Procedure Division Diagnosing Input-Output Errors Table 8-12. I-O Status Codes Augmented by GUARDIAN-ERR (page 4 of 5) Status Code GUARDIAN-ERR Value COBOL Statement(s) Cause of Status Code “35” 11 OPEN Opening for INPUT, I-O, or EXTEND on nonexistent file: OPTIONAL not specified 14 OPEN Opening for INPUT, I-O, or EXTEND on temporary file: device does not exist, and OPTIONAL not specified “37” 0 OPEN Opening for INPUT or OUTPUT: device won’t support it “38” 0 OPEN File is locked “39” 0 OPEN File is not disk or is an unstructured disk file and organization is not sequential or file has alternate keys LINAGE specified on file that is not a printer or process Multiple files specified on a device that is not a tape OUTPUT specified on an EDIT file Record too large for file buffer size Fixed length records not specified for unstructured file Organization does not match file type Key specs for file do not match program key specs “41” 0 OPEN File is not closed “42” 0 CLOSE Attempt to close an unopened file 0 LOCKFILE, UNLOCKFILE Attempt to access an unopened file “43” 0 DELETE, REWRITE (sequential access) No successful READ “44” 0 REWRITE New record has different size than replaced one “46” 0 READ sequential Current position undefined “47” 0 READ, START File is not opened for INPUT or I-O xxx = Whatever file-system error is returned HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 38 Procedure Division Recovering from Input-Output Errors Table 8-12. I-O Status Codes Augmented by GUARDIAN-ERR (page 5 of 5) Status Code GUARDIAN-ERR Value “48” COBOL Statement(s) Cause of Status Code 0 WRITE (sequential access) Indexed or relative file not open for OUTPUT and not open EXTEND sequential access 0 WRITE (random or dynamic access) Indexed or relative file not open for I-O 0 WRITE (sequential file) File was not opened for OUTPUT, EXTEND, or I-O “49” 0 DELETE, REWRITE File was not opened for I-O “90” 0 LOCKFILE, READ, START File was not opened for nowait I-O, and TIME LIMIT was specified 0 WRITE Wrong file type for ADVANCING operations xxx OPEN Unable to initialize EDIT file 0 OPEN No buffer space available in user data space xxx READ sequential Unable to read EDIT file 0 READ sequential Read with lock and preread on 9 READ, START A locked record was read or nominated in a START statement 0 OPEN The program described a file as having standard labels, and no standard label was found “91” “97” xxx = Whatever file-system error is returned Recovering from Input-Output Errors When a process executes an I-O statement against a given file, either the I-O operation is successful or it is not. In either case, if there is an I-O status data item associated with the file, the run-time routines store an I-O status code there. (See I-O Status Code.) After the run-time routines store the I-O status code, the behavior of the process depends on the nature of the exception and on the presence of any exception handling phrases, or if no exception handling phrases are present, then on the presence of an applicable declarative procedure. Topics: • • At-End Condition or Invalid-Key Condition Other Error Conditions HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 39 Procedure Division Recovering from Input-Output Errors At-End Condition or Invalid-Key Condition If the error condition is the at-end condition or the invalid-key condition, the file is not affected (that is, if the statement was an output statement, the contents of the file remain unchanged). The run-time routines then perform these actions in this order: 1. If the statement that caused the condition includes any positive exception handling phrase (AT END or INVALID KEY), transfer control to that phrase’s imperative statement. Ignore any USE AFTER EXCEPTION procedure and any negative exception handling phrases (NOT AT END, NOT INVALID KEY). If control reaches the end of the AT END or INVALID KEY phrase, transfer control to the statement immediately following the terminating period or scope terminator of the I-O statement that caused the exception condition. 2. If the statement that caused the condition does not include a positive exception handling phrase, but does include a negative exception handling phrase (NOT AT END or NOT INVALID KEY), ignore any USE AFTER EXCEPTION procedure and any negative exception handling phrases. Transfer control to the statement immediately following the terminating period or scope terminator of the I-O statement that caused the exception condition. 3. If all exception handling phases (AT END, NOT AT END, INVALID KEY, or NOT INVALID KEY) are absent but a declarative procedure of the form USE AFTER EXCEPTION is associated with the file, execute that procedure. 4. If control reaches the end of declarative procedure, transfer control to the statement immediately following the terminating period or scope terminator of the I-O statement that caused the exception condition. 5. If neither exception handling phrases nor declarative procedures apply, transfer control to the statement immediately following the terminating period or scope terminator of the I-O statement that caused the exception condition. Other Error Conditions If the execution is unsuccessful for a reason other than an at-end or invalid-key condition, the behavior of the program depends on the presence or absence of a declarative procedure for the file in question. If there is such a declarative procedure, the behavior of the program also depends on the presence or absence of any negative exception handling phrase (NOT AT END or NOT INVALID KEY). When the run-time routines have recognized the exception condition, generated a runtime diagnostic message, and stored the I-O status code, they take these actions in this order: 1. If a declarative procedure of the form USE AFTER EXCEPTION is associated with the file, execute the declarative procedure. Then, if recovery from the exception is not possible (the I-O status code is “90” or Status Key 1 is “4”), terminate the process. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 40 Procedure Division Timed Input and Output If recovery from the exception is possible (either when Status Key 1 is “3,” or when it is “9” and Status Key 2 is not “0”), and the declarative procedure has not voluntarily terminated execution of the process, continue the execution: a. If the statement that caused the condition includes any negative exception handling phrase (NOT AT END or NOT INVALID KEY), transfer control to that phrase’s imperative statement. Ignore any positive exception handling phrases (AT END, INVALID KEY). b. If the statement that caused the condition does not include any negative exception handling phrase, transfer control to the statement immediately following the terminating period or scope terminator of the I-O statement that caused the exception condition. 2. If no applicable declarative procedure exists, terminate the process. Timed Input and Output Timed input-output prevents the deadlock that can occur when processes require concurrent access to shared data files. Timed I-O is enabled for a file when the file is opened with an OPEN statement containing a TIME LIMIT phrase. When timed I-O is enabled for a file, you can use a TIME LIMIT phrase in a LOCKFILE, READ, or START statement that applies to the file. The time limit is the number of seconds within which the operation must finish. A negative time limit means “wait indefinitely” (until the contention is resolved or the waiting process is terminated by an external agency). Topics: • • • • Expired Time Limit Overhead Fatal Error $RECEIVE Timeout Expired Time Limit An expired time limit indicates a potential deadlock. The programmed recovery action (declarative procedure) must release any locks held by the program and restart the execution of the current request. If no declarative procedure applies to the file when the operation terminates, the program terminates abnormally. If a declarative procedure does apply to the file and the time limit expires, the declarative procedure is performed and program execution continues with the statement following the one terminated. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 41 Procedure Division Arithmetic Operations The value of the file position indicator becomes undefined when an operation exceeds its time limit. Because you cannot determine where in the operation the time limit was exceeded, you cannot necessarily try the operation again immediately at the current record. Overhead When a file is opened with timed I-O enabled, each I-O statement incurs more overhead than a file opened without a time limit. Avoid using timed I-O unnecessarily. When a file is being read with APPROXIMATE positioning, the value used for time limit must take into account that a READ can take somewhat longer than expected. This can occur when a nonexistent record is sought, because the operating system searches through the file looking for the next defined record before reporting the absence of the record sought. Fatal Error If a file is opened without the TIME LIMIT phrase, and the TIME LIMIT phrase is specified in a LOCKFILE, READ, or START statement with a nonnegative value for the time limit, a run-time error is reported to the process’s home terminal, and the process terminates abnormally with the I-O status code “90”. $RECEIVE Timeout A process that must avoid unnecessary suspension when checking for messages on $RECEIVE can use timed I-O. If the READ statement specifies the time limit 0 and no message is present, the request times out immediately. Arithmetic Operations Many different statements tell the compiler to perform arithmetic operations, either because they are arithmetic statements or because they include arithmetic expressions. The arithmetic statements are: • • • • • ADD COMPUTE DIVIDE MULTIPLY SUBTRACT HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 42 Procedure Division Common Features of Arithmetic Statements Topics: • • • Common Features of Arithmetic Statements Arithmetic Expressions Arithmetic Precision Common Features of Arithmetic Statements This section describes the common features of the arithmetic statements, which are: • • • • • Data Conversion and Alignment Composite of Operands Intermediate Data Items Multiple Results Incompatible Data Data Conversion and Alignment The data descriptions of the operands need not be the same; any necessary conversion and decimal point alignment is supplied by the COBOL compiler throughout the calculation. Composite of Operands The maximum size of each arithmetic operand is 18 decimal digits, independent of any decimal point. When the computer performs arithmetic, it must handle operands of different data descriptions. To discuss the restrictions on arithmetic operations, the COBOL community coined the term “composite of operands.” The composite of operands for a given operation is a fictitious data item. It has as many positions in its integer portion (to the left of the decimal point) as the operand that has the largest number of integer positions, and as many positions in its fraction portion (to the right of the decimal point) as the operand that has the largest number of fraction positions. For example, in the data descriptions 01 01 01 A PIC S9(8)V9(4) B PIC S9(2)V9(7) C PIC S9(4)V9(9) the composite of operands for an arithmetic operation involving only A, B, and C would have a data description of S9(8)V9(9), or 17 digits. The composite of operands for an arithmetic statement other than COMPUTE must not exceed a size of 18 decimal digits. For arithmetic expressions or COMPUTE statements, the composite of operands does not apply. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 43 Procedure Division Common Features of Arithmetic Statements Intermediate Data Items For each arithmetic operation, an intermediate data item holds the result value until that value is either used as an operand in another operation or assigned to a receiving data item. The size of the intermediate data item depends on the operations and data items used in the operation and varies from 16 bits (about four digits) to 128 bits (about 39 digits). If the algebraic size of the result exceeds the capacity of this intermediate data item, a binary, floating-point, intermediate data item is used and the compiler issues warning 85. Because floating-point arithmetic has a maximum precision of 16 digits and often is not exact, the result might be incorrect in the rightmost digit or digits. Multiple Results The ADD, COMPUTE, DIVIDE, MULTIPLY, and SUBTRACT statements can have multiple results from performing arithmetic necessary to arrive at the final result to be stored in the receiving item. During execution, multiple results are the same as the results produced by a sequence of statements that either combine the value of an intermediate data item with a single result or transfer the value to a receiving item. These statements are in the same left-to-right order as that of the multiple results in the actual statement. For example, the results of the statement ADD A B C TO C D (C) E are equivalent to those of the statements ADD ADD ADD ADD A B C GIVING TEMP TEMP TO C TEMP TO D (C) TEMP TO E TEMP is the intermediate data item. Any subscripts specified in a reference to a receiving item are evaluated just prior to the assignment operation for that item. Incompatible Data Normally, whenever the contents of a data item are used in the Procedure Division and the current contents of that data item are not compatible with the class and size specified by its PICTURE clause, the result of the reference is undefined; that is, the semantic rules of the COBOL language apply only when operands have values corresponding to their descriptions. The single exception to this rule is the class condition, which exists specifically to permit testing whether or not an operand’s value corresponds to its description. The presence of incompatible data can cause execution of the run unit to terminate abnormally. Some computations can generate a negative zero (for example, when the value of an expression is -0.05, and this value is stored in a variable that is described as PICTURE S99V9). When the program uses the value negative zero, it ignores the sign. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 44 Procedure Division Arithmetic Expressions Arithmetic Expressions num-id + - num-lit arith-expr arith-expr + * / ** ( arith-expr ) VST739.vsd num-id is the identifier of a numeric data item. num-lit is a numeric literal. arith-expr is an arithmetic expression. The value of an arithmetic expression is a numeric value. Arithmetic expressions can appear in: • • • • • • ENTER statements EVALUATE statements Reference modifiers Sign conditions Relation conditions Function arguments The values computed when arithmetic expressions are evaluated are transitory and are not stored for later use by the program. Topics: • • • Operands Arithmetic Operators Formation and Evaluation Rules HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 45 Procedure Division Arithmetic Expressions Operands An operand is a numeric literal, the identifier of a numeric data item, or any arithmetic expression enclosed within balanced left and right parentheses. The identifiers and literals appearing in an arithmetic expression must represent numeric data items and numeric literals upon which arithmetic can be performed. Arithmetic Operators Each operator in Table 8-13 must be preceded and followed by a separator (usually spaces or parentheses). Table 8-13. Arithmetic Operators Operator Symbol Kind Meaning + Unary Multiplication by +1 Binary Addition Unary Multiplication by -1 Binary Subtraction * Binary Multiplication / Binary Division ** Binary Exponentiation - The minus sign (-) and the plus sign (+) must be preceded by a space or a left parenthesis and followed by a space. The exponentiation sign (**) cannot contain an embedded space, but it can be split across two lines through the use of the hyphen continuation character. A plus (+) or minus (-) appearing as the first character of a numeric literal is the sign character of that literal, not an arithmetic operator. For example, +2 is not an arithmetic expression. In contrast, a plus (+) or minus (-) followed by a separator is interpreted as a binary operator when preceded by an operand or as a unary operator when not preceded by an operand. For example, X + 2 represents a simple arithmetic expression. The presence of a sign character in a numeric literal does not affect its use as an operand; therefore, both X + + 2 and X + 2 are valid and, in this case, equivalent expressions. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 46 Procedure Division Arithmetic Expressions Formation and Evaluation Rules Parentheses can be used to specify the order in which the elements of an expression are to be evaluated. Expressions within parentheses are evaluated first. Within nested parentheses, evaluation proceeds from the least inclusive set to the most inclusive set. When parentheses are not used, or parenthesized expressions are at the same level of inclusiveness, the hierarchical order of execution is shown in Table 8-14. Table 8-14. Hierarchy of Operators Hierarchy Operators 1st Unary plus and minus 2nd Exponentiation 3rd Multiplication and division 4th Addition and subtraction When no parentheses are present to specify otherwise, the order of execution of consecutive operations of the same hierarchical level is from left to right. Table 8-15 shows some expressions that appear to be ambiguous and the COBOL interpretation of them. Table 8-15. Precedence in Arithmetic Expressions Ambiguous Interpretation *C (A / B) * C A/B/C (A / B) / C A ** B ** C (A A/B A+B/C+D ** E * F - G ** B) ** C ((A + (B / C)) + ((D ** E) * F)) - G You can use arithmetic parentheses to: • Override the normal hierarchical sequence of execution in expressions whose evaluation must not follow the normal precedence, for example: A / ( B * C ) • Clarify the hierarchical sequence of execution for the benefit of the reader, for example: PRIN + ( INT * PERIOD ) It is recommended that division be the last operation performed in an expression, if possible; otherwise, execution can be slow and precision can be lost. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 47 Procedure Division Arithmetic Precision Table 8-16. Operator-Operand Combinations Successor Element First Element Variable Binary Operator + - * / ** Unary Operator + or - ( ) Identifier or literal No Yes No No Yes Binary Operator + - * / ** Yes No Yes Yes No Unary Operator + or - Yes No No Yes No ( Yes No Yes Yes No ) No Yes No No Yes An arithmetic expression must begin with an operand (which can be a parenthetical expression) or a unary operator followed by an operand. Parentheses must always appear in balanced pairs such that each left parenthesis precedes its corresponding right parenthesis within the expression. Any operand can be preceded by a unary operator. These rules apply to evaluation of the exponentiation operator in an arithmetic expression: • • • • If the value of the base (left-hand) operand is 0, the power (right-hand) operand must have a value greater than 0; otherwise, the size error condition exists. If the evaluation yields both a positive and a negative real number, the value returned as the result is the positive number. If the result of the evaluation is not a real number or is not representable by the computer system on which the operation is evaluated, the size error condition exists. COBOL accepts noninteger as well as integer exponents. Arithmetic Precision The precision of ADD, SUBTRACT, MULTIPLY, and DIVIDE statements can be fairly easily stated. The precision of arithmetic expressions is substantially more complex, because the compiler must create intermediate data items as it evaluates the expression. Arithmetic expressions occur only in the COMPUTE, ENTER, and EVALUATE statements, the relation and sign conditions, function arguments, and in reference modification. In discussing precision, we ignore the presence of a scale factor or of any decimal point; the arithmetic processing records and handles these elements separately. After the computation is performed with integral values, the decimal point and scale factor (if any) are then provided for the result. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 48 Procedure Division Arithmetic Precision The largest value HP COBOL can store is the unsigned COMPUTATIONAL-5 value 18,446,744,073,709,551,615. The largest value HP COBOL can store associated with a DISPLAY or COMPUTATIONAL data item (independent of any decimal point or scale factor) is the 20-digit number which is the highest value for an unsigned 64-bit number. In evaluating arithmetic expressions, COBOL can manipulate intermediate values having up to 128 bits (about 39 digits). These topics explain arithmetic precision as it applies to: • • • • • SIZE ERROR ADD and SUBTRACT Statements MULTIPLY Statement DIVIDE Statement Arithmetic Expressions SIZE ERROR As explained in SIZE ERROR Phrase, the size error condition indicates a problem in computation. It arises when an arithmetic overflow occurs or when a program attempts to divide by zero, raise zero to the zero power, or raise a negative number to a power that produces other than a real number value. If no SIZE ERROR clause is present in the statement where the condition arises, the process can terminate abnormally with an arithmetic overflow or it can store invalid values into result items (mainly in items of USAGE COMPUTATIONAL). ADD and SUBTRACT Statements Each data item in an ADD or SUBTRACT statement, except the one after GIVING, is called an addend. In the statement ADD P Q R S T GIVING W the addends are P, Q, R, S, and T. In the statement ADD P Q R S T TO X Y the addends are P, Q, R, S, T, X, and Y. The number of accurate fraction digits maintained during evaluation is determined by the addend having the greatest number of fraction digits. All remaining intermediate result representation space is used for nonfraction digits. The computed result is always completely accurate unless an internal overflow occurs, raising the size error condition; therefore, all digits in the value assigned to a receiving data item are accurate unless the size error condition occurs for that data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 49 Procedure Division Arithmetic Precision MULTIPLY Statement The number of fraction digits in the product is the sum of the number of fraction digits in the two operands. The number of accurate nonfraction digits in the product is the sum of the nonfraction digits in the two operands. The computational method used verifies that an internal overflow never occurs for a MULTIPLY statement; therefore, all digits in the value assigned to a receiving data item are accurate unless the size error condition occurs for that data item. DIVIDE Statement Because division is a rather complicated mathematical operation, and because the computer is performing scaled integer arithmetic instead of floating-point arithmetic, the rules stating the precision of HP COBOL division are somewhat complicated. • Effect of GIVING When the GIVING phrase is present, a single quotient is computed. The appropriate number of fraction digits in that quotient is determined from the receiving operand having the greatest number of fraction digits. When no GIVING phrase is present, a separate quotient is computed for each receiving data item. Such a DIVIDE statement with multiple receiving data items is exactly equivalent to a sequence of DIVIDE statements, each having a single receiving data item and all having the same divisor. The appropriate number of fraction digits in each quotient is determined from the corresponding receiving data item. • Effect of Decimal Point Placement Under the mathematical rules for division, fraction digits in the divisor cause the significant digit positions of the quotient to appear shifted to the left with respect to the significant digit positions of the dividend. This corresponds to moving the decimal point of the dividend to the right the same number of positions as would be necessary to make the divisor an integer: 1.00/0.3 = 10.0/03 = 03.3 Put another way, each divisor fraction digit cancels a trailing digit position in the dividend, which then reappears as a leading digit position in the quotient. This causes a problem when the actual dividend has fewer fraction digits than the sum of the number of digits in the divisor’s fraction and the number of digits in the appropriate quotient’s fraction. Suppose you want to divide two data items described as: DIVIDEND DIVISOR PICTURE 9(10)v9(5) USAGE DISPLAY PICTURE 9(4)v9(7) USAGE DISPLAY If the computer aligns them by scaling each up by 7 decimal places, it has to extend the dividend’s fraction with 2 additional digit positions filled with zeros. It would be dividing a 17-digit integer by an 11-digit integer. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 50 Procedure Division Arithmetic Precision Because the sum of the number of actual dividend digits and the number of appended zero digits cannot exceed 36, there are very few combinations of operands in a DIVIDE statement for which it is impossible to append enough zeros. • Size Error All digits in the value assigned to the receiving data item are accurate unless either the size error condition occurs for that data item or at least one trailing digit is fictitious (that is, set to 0 because it was not generated by the division operation). Arithmetic Expressions HP COBOL maintains intermediate results during the evaluation of arithmetic expressions. Arithmetic expressions occur only in the COMPUTE statement, the EVALUATE statement, the relation condition, the sign condition, the reference modifier, the parameters of the ENTER statement, and function arguments. Note. The precision of COBOL arithmetic computation has limitations. The COMPUTE statement is particularly sensitive. Use of an appropriate sequence of the ADD, SUBTRACT, MULTIPLY, and DIVIDE statements permits you to attain the precision you desire, provided that the PICTURE clauses describing the operands do not imply potential values of exaggerated significance. There is no guarantee that the result of an arithmetic expression will be the same in different implementations. The evaluation of an arithmetic expression is the result of the evaluation of a sequence of intermediate results. The maximum number of digits held for an intermediate result is 36. If this number is exceeded, the compiler might use binary floating-point arithmetic (and issue warning 85). The size error condition applies to both final results and intermediate results. These abbreviations are used to explain intermediate operations: Abbreviation Description IR Number of integer places carried for an intermediate result. DR Number of decimal places carried for an intermediate result. OP1 First operand in an arithmetic expression, which has the form 9(I1)V9(D1), where I1 is the number of integer places carried and D1 is the number of decimal places carried for the first operand. OP2 Second operand in an arithmetic expression, which has the form 9(I2)V9(D2), where I2 is the number of integer places carried and D2 is the number of decimal places carried for the second operand. OPR Desired result, which has the form 9(IR)V9(DR), where IR is the number of places carried for the integer result, and DR is the number of places carried for the decimal result. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 51 Procedure Division Arithmetic Precision The number of decimal places in the intermediate result (DR) is chosen first, then the number of integer places in the intermediate result is determined from that and the characteristics of the two operands. HP COBOL guarantees that the mathematical significance of results will be at least as good as application of these rules implies. Decimal Places (Worst-Case Precision) Operation DR is the greater/greatest of … IR is the lesser of … OP1 + OP2 OP1 - OP2 D1 and D2 (The greater of I1 and I2) + 1) and (36 - DR) OP1 * OP2 D1 and D2 (I1 + I2) and (36 - DR) OP1 / OP2 D1 - D2, the D of the composite of all the result fields, and 1 (I1 + D2) and (36 - DR) OP1 ** OP2 D1 or D2 (The greater of I1 or I2) and (36 - DR) Note. If (I1+D2+DR) > 36, the compiler uses floating-point arithmetic (and issues warning 85). When an arithmetic expression involves a division operation, the intermediate results are evaluated in these steps: 1. The actual division 2. The adjustment of that result for use in further computations Therefore, in each of these instances of the arithmetic expression “A1/A2+A3*A4,” COMPUTE AX = A1/A2 + A3 * A4 IF A1/A2 + A3 * A4 LESS THAN AX GO TO ... the division is performed before further evaluation of either of the preceding statements. If the division operation is not the last operation in the expression and the divisor is not 2, 4, 5, 8, or a power of 10, the division is carried out to 36 digits. As many fractional digits as possible are kept. This number can be truncated depending on subsequent operations. In some cases adjustment is not possible, so the compiler uses binary floating-point arithmetic (and issues warning 85). Since the precision of floating-point arithmetic is 16 digits and numbers cannot always be represented exactly, the result might be slightly larger or smaller than the exact number. You might have to use individual operations or revise the expression to guarantee accurate results. To obtain the maximum accuracy in an arithmetic expression that involves a division, use parentheses or revise the expression as necessary to assure that the division is the last operation performed. For example, you can rewrite the expression “a / b * c" as "(a * c) / b". When a conditional expression compares a variable and an expression, the number of decimal places carried for the variable is used for the number of decimal places carried for the expression. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 52 Procedure Division Conditional Expressions When a conditional expression compares two expressions, the compiler determines the smallest number of decimal places suitable for each of the expressions and then uses the larger of those numbers of decimal places. In a COMPUTE statement, the number of decimal places of the composite of operands of the receiving fields is the number of decimal places of the expression. If ROUNDED is specified on any operand, one additional decimal position is used in the computation, then the rounding is applied to the result. Conditional Expressions Many different statements include conditional expressions. A conditional expression is a syntactically correct combination of simple conditions, logical operators, and parentheses that can be evaluated to a truth value. The truth value determines which of two paths of control the object program takes. The simplest form of a conditional expression is a simple condition. Complex conditions are combinations of simple conditions and any of the logical operators NOT, AND, and OR. COBOL allows you to abbreviate sequences of complex relation conditions. You can use balanced sets of parentheses to control or clarify the order of evaluation within a conditional expression. Topics: • • • • Simple Conditions Complex Conditions Abbreviated Combined Relation Conditions Condition Evaluation Rules Simple Conditions A simple condition has a truth value of TRUE or FALSE. Enclosing a simple condition within parentheses does not affect its truth value. The simple conditions are: • • • • • • • Relation Conditions in General Relation Conditions With Nonpointer Operands Relation Conditions With Pointer Operands Class Conditions Condition-Name Conditions (Conditional Variables) Switch-Status Conditions Sign Conditions HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 53 Procedure Division Simple Conditions Relation Conditions in General A relation condition causes a comparison of two operands. The relation condition has a truth value of TRUE if the relation exists between the operands; otherwise, it has a truth value of FALSE. Usage Considerations: • Terminology In the preceding syntax diagrams, the left-hand operand is called the subject of the condition; the right-hand operand is called the object of the condition. • Where Pointer Relations Are Allowed A relation with pointer operands is allowed in EVALUATE, IF, PERFORM, and SEARCH VARYING statements. It is not allowed in SEARCH ALL statements, because pointer data items have no meaningful order. • Cannot Compare Literal With Literal At least one nonpointer operand must be an index-name, identifier, or arithmetic expression containing at least one reference to a data item; that is, the relation must include at least one nonliteral element. • Operators The relational operators specify the type of comparison to be made in the relation condition, as this table shows. NOT and the component following it are considered to be a single relational operator. For example, NOT EQUAL is a truth test for an unequal comparison. In this table, optional words are in brackets. Relational Operator Words Symbol Meaning GREATER [THAN] > Greater than NOT GREATER [THAN] NOT > Not greater than LESS [THAN] < Less than NOT LESS [THAN] NOT < Not less than EQUAL [TO] = Equal to NOT EQUAL [TO] NOT = Not equal to GREATER [THAN] OR EQUAL [TO] >= Greater than or equal to LESS [THAN] OR EQUAL [TO] <= Less than or equal to HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 54 Procedure Division • Simple Conditions Numeric Comparisons Numeric comparisons are made with respect to the algebraic values of the operands. The number of digits present in the representation of an operand is not significant. Comparison of numeric operands is permitted regardless of the manner in which their usage is described. Unsigned numeric operands are considered positive for purposes of comparison. Zero is considered a unique value regardless of its sign. • Nonnumeric Comparisons For nonnumeric operands, or one numeric and one nonnumeric operand, a comparison is made with respect to the program collating sequence (see OBJECTCOMPUTER Paragraph). ° ° One operand is numeric: ° The numeric operand must be a numeric literal or a reference to a numeric data item; therefore, it cannot be an arithmetic expression. COBOL requires the operand to be an integer and, if a data item, to have DISPLAY usage. HP COBOL removes both of these restrictions. ° When the nonnumeric operand is either an elementary data item or a nonnumeric literal, the numeric operand is handled as though it were moved to an elementary alphanumeric data item, and the value of this item were then compared to the nonnumeric operand. The size of this conceptual data item is the same as the number of digit positions in the numeric operand. The numeric operand is handled as if it were an unsigned integer; therefore any sign or assumed decimal point is deleted by the conceptual move, and no COMPUTATIONAL items are converted to usage DISPLAY. ° When the nonnumeric operand is a data structure, the numeric operand is handled as though it were moved to a data structure, and the value of this item were then compared to the nonnumeric operand. The size of this conceptual data item is the same as the number of character positions occupied by the numeric operand. Because the operand is handled as if it were alphanumeric, the sign of the numeric operand (if any) is not deleted by the conceptual move, and no COMPUTATIONAL usage items are converted to DISPLAY usage. Operand size The size of an operand is the total number of characters it contains. Operands can be of equal or unequal size. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 55 Procedure Division ° Simple Conditions Operands of equal size If the operands are of equal size, the process compares characters in corresponding character positions, starting with the leftmost character position and continuing until it either encounters a pair of unequal characters or exhausts the operands. The process determines that the operands are equal if all character pairs in the operands are equal; otherwise, the process compares the first pair of unequal characters it encounters to determine their relative position in the collating sequence active for the comparison. The operand that contains the character that has a higher position in the collating sequence is considered to be the greater operand. ° Operands of unequal size If the operands are of unequal size, comparison proceeds as though the shorter operand were extended on the right by sufficient spaces to make the operands of equal size. • Index-Name and Index Data Item Comparisons Relation tests can be made between these operands: ° Two index-names The result is the same as if the corresponding occurrence numbers were compared. ° An index-name and a numeric data item or numeric literal The occurrence number that corresponds to the value of the index-name is compared to the value of the data item or literal. ° An index data item and an index-name or another index data item The actual values are compared without conversion. Neither an index-name nor an index data item can be compared with any operand other than those mentioned in the preceding rules. • National Data Items and National Literals A national data item or a national literal can be compared only to another national data item or a national literal. The first three simple relation conditions in Example 8-11 are equivalent. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 56 Procedure Division Simple Conditions Example 8-11. Simple Relation Conditions I + 1 > HIGH-I (I + 1) > HIGH-I HIGH-I < (I + 1) TAXABLE-INCOME GREATER THAN ZERO LAW-NAME = "MURPHY" "POOL" NOT EQUAL TROUBLE-SOURCE A-INDEX NOT > 23 Relation Conditions With Nonpointer Operands subject relationship object IS VST118.vsd subject object is an identifier, a literal, an arithmetic expression, an index-name. relationship GREATER NOT LESS THAN EQUAL TO > < = GREATER LESS OR THAN EQUAL TO >= <= VST119.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 57 Procedure Division Simple Conditions Relation Conditions With Pointer Operands pointer-subject relationship pointer-object IS VST602.vsd pointer-subject pointer-object ADDRESS OF identifier-1 identifier-2 NULL NULLS VST603.vsd identifier-1 is a level-01 or level-77 data item defined in the Linkage Section or Data Division. identifier-2 is a data item with USAGE POINTER. NULL NULLS is a null address (all 1s) that causes an address fault if a pointer with that value is referenced. NULL or NULLS can be used for pointer-subject or pointer-object, but not both. relationship EQUAL IS NOT TO = VST604.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 58 Procedure Division Simple Conditions Class Conditions The class condition determines whether the operand is numeric, alphabetic, lowercase alphabetic, uppercase alphabetic, or contains only characters in the set defined by a CLASS clause in the SPECIAL-NAMES paragraph of the Environment Division. identifier IS NOT NUMERIC ALPHABETIC ALPHABETIC-LOWER ALPHABETIC-UPPER class-name VST120.vsd identifier is the identifier of a data item for which either: • • It is described as USAGE DISPLAY. It is of the numeric class, and its usage is not DISPLAY. class-name is the name of a class described in the SPECIAL-NAMES paragraph. Usage Considerations: • NOT Modifier When NOT appears, the compiler considers it and the next keyword to form a single class condition. For example, NOT NUMERIC is a truth test that determines if the operand is nonnumeric. • NUMERIC and NOT NUMERIC You cannot use the NUMERIC and NOT NUMERIC tests with either: ° ° An alphabetic data item A data structure that contains any elementary item not described as USAGE DISPLAY or whose description indicates the presence of an operational sign HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 59 Procedure Division Simple Conditions If the description of the tested item does not indicate the presence of an operational sign, the item belongs to the numeric class only if: ° The content of the item is numeric (consists entirely of the digit characters 0 through 9 ). ° No operational sign is present. If the description of the tested item indicates the presence of an operational sign, the item belongs to the numeric class only if: • ° The content of the item is numeric (consists entirely of the digit characters 0 through 9 ). ° The item is not described as USAGE DISPLAY, and the content of the item consists entirely of a valid representation for the usage. If a PICTURE clause is specified, its numeric value is within the range of values implied by the PICTURE clause. ALPHABETIC and NOT ALPHABETIC You cannot use the ALPHABETIC and NOT ALPHABETIC tests with a numeric data item. Normally, the tested item belongs to the alphabetic class only if its content consists entirely of some combination of the alphabetic characters A through Z, a through z, and space. When the CHARACTER-SET clause specifies a program character set other than USASCII or UK, the set of characters that constitute the alphabetic class is extended as appropriate (see OBJECTCOMPUTER Paragraph). • ALPHABETIC-LOWER and NOT ALPHABETIC-LOWER You cannot use the ALPHABETIC-LOWER and NOT ALPHABETIC-LOWER tests with a numeric data item. The tested item belongs to the alphabetic-lower class only if its content consists entirely of the lowercase alphabetic characters a through z and space. When the CHARACTER-SET clause specifies a program character set other than USASCII or UK, the set of characters that constitute the alphabetic class is extended as appropriate (see OBJECT-COMPUTER Paragraph). • ALPHABETIC-UPPER and NOT ALPHABETIC-UPPER You cannot use the ALPHABETIC-UPPER and NOT ALPHABETIC-UPPER tests with a numeric data item. The tested item belongs to the alphabetic-upper class only if its content consists entirely of the uppercase alphabetic characters A through Z and space. When the CHARACTER-SET clause specifies a program character set other than USASCII or UK, the set of characters that constitute the alphabetic class is extended as appropriate (see OBJECT-COMPUTER Paragraph). HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 60 Procedure Division • Simple Conditions Class-name and NOT Class-name You cannot use the class-name and NOT class-name tests with a numeric data item. The result of the test is TRUE if the content of the data item consists entirely of the characters listed in the definition of the class-name in the SPECIAL-NAMES paragraph; otherwise the result is FALSE. Class conditions are useful for field validation: PART-NUMBER IS NUMERIC REPLY-FIELD IS NOT ALPHABETIC DIAGNOSTIC-MESSAGE IS NOT ALPHABETIC-UPPER If the SPECIAL-NAMES paragraph includes the description CLASS VOWEL IS "A" "E" "I" "O" "U" "a" "e" "i" "o" "u". the procedure division can use this condition for validation: SOME-FIELD IS VOWEL Condition-Name Conditions (Conditional Variables) In a condition-name condition, a conditional variable is tested to determine whether or not its value is equal to one of the values or within one of the ranges of values associated with a condition-name. Usage Considerations: • Condition-Name Conditions The rules for comparing a conditional variable with the literal values corresponding to a condition-name are the same as those specified for relation conditions. The result of the test is TRUE if either of these relations is satisfied: ° The value of the conditional variable equals one of the single values corresponding to the condition-name. ° The value of the conditional variable falls within one of the ranges of values, including the end values, corresponding to the condition-name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 61 Procedure Division Simple Conditions Example 8-12. Conditional Variables WORKING-STORAGE SECTION. 01 ZIP-CODE. 03 ZIP-FIRST-3 PICTURE 999. ... 88 NEW-YORK VALUE IS 090 THRU 098, 100 THRU 149. 88 PENNSYLVANIA VALUE IS 150 THRU 196. ... PROCEDURE DIVISION. ... ELSE IF NEW-YORK MOVE "NY" TO STATE-FROM-ZIP ELSE IF PENNSYLVANIA MOVE "PA" TO STATE-FROM-ZIP ... IF STATE-INPUT NOT = STATE-FROM-ZIP PERFORM QUERY-ZIP-OR-STATE-CORRECTION. Switch-Status Conditions A switch-status condition determines whether an external switch is on or off. The particular switch and the ON or OFF value associated with the condition must be named in the SPECIAL-NAMES paragraph of the Environment Division. Usage Considerations: • TRUE Value The result of the test is TRUE if the switch is set to the position corresponding to the one identified by the condition-name; otherwise, the result of the test is FALSE. • Setting External Switches Set external switch value by using the PARAM command of the command interpreter (see SPECIAL-NAMES Paragraph) or by the SET statement (see SET). Example 8-13. External Switches SPECIAL-NAMES. SWITCH-1 IS IN-SWITCH ON OFF SWITCH-2 IS OUT-SWITCH ON OFF ... PROCEDURE DIVISION. ... IF TAPE-INPUT OPEN ELSE OPEN IF TAPE-OUTPUT OPEN ELSE OPEN ... STATUS STATUS STATUS STATUS IS IS IS IS TAPE-INPUT DISK-INPUT TAPE-OUTPUT DISK-OUTPUT. INPUT TAPE-SOURCE INPUT DISK-SOURCE. OUTPUT TAPE-SINK OUTPUT DISK-SINK. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 62 Procedure Division Simple Conditions Sign Conditions The sign condition determines whether the algebraic value of an arithmetic expression is less than, greater than, or equal to zero. arithmetic-expression IS NOT POSITIVE NEGATIVE ZERO VST121.vsd arithmetic-expression is an arithmetic expression, as described in Arithmetic Expressions. Usage Considerations: • NOT Modifier When NOT appears, it and the next keyword are considered to form a single sign condition. For example, NOT ZERO is a truth test that determines if the operand value is nonzero (is positive or negative). • Definition An operand is positive if its value is greater than zero, negative if its value is less than zero, and zero if its value is equal to zero. • Expression Cannot Be Composed Entirely of Literals The arithmetic expression must contain at least one variable operand (at least one operand that is not a literal). Example 8-14. Sign Conditions ( A - 10 ) IS POSITIVE B NOT ZERO HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 63 Procedure Division Complex Conditions Complex Conditions A complex condition is a combination of simple conditions and any of the logical operators NOT, AND and OR. Its truth value is the one that results from the interaction of the stated logical operators on the individual truth values of the simple conditions or conditions enclosed within parentheses. Table 8-17. Logical Operators Operator Symbol Kind Meaning NOT Unary Logical negation (reversal of truth value): The truth value is TRUE if the condition is FALSE, FALSE if the condition is TRUE AND Binary Logical conjunction: The truth value is TRUE if both conjoined conditions are TRUE, FALSE if one or both conjoined conditions are FALSE OR Binary Logical inclusive OR: The truth value is TRUE if one or both included conditions are TRUE, FALSE if both included conditions are FALSE A complex condition formed by applying the unary operator NOT to a simple or parenthetical condition is called a negated condition. A complex condition formed by applying the binary operator AND or OR to two conditions (either of which can be simple or parenthetical) is called a combined condition. Negated Conditions NOT simple-condition ( condition ) VST122.vsd simple-condition is described in Simple Conditions. condition is a simple or complex condition. The truth value of a negated condition is the opposite of the truth value of the operand condition. You do not need to use parentheses when you use either AND or OR exclusively in a combined condition. When you use a mixture of AND, OR, and NOT, you can use parentheses to effect a final truth value. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 64 Procedure Division Complex Conditions Combined Conditions condition AND condition OR VST123.vsd condition is a simple or complex condition. Table 8-18. Conditions, Logical Operators, and Parentheses Location in Conditional Expression In a left-to-right sequence of elements Element First Last When not first, element can be immediately preceded only by When not last, element can be immediately followed only by simplecondition Yes Yes AND, NOT, OR, ( AND, OR, ) AND or OR No No simple-condition, ) NOT, (, simple-condition NOT Yes No AND, OR, ( (, simple-condition ( Yes No AND, NOT, OR, ( NOT, (, simple-condition ) No Yes simple-condition, ) AND, OR, ) As Table 8-18 shows, you can use the element pair OR NOT, but you cannot use the pair NOT OR. Also, you can use NOT, but you cannot use NOT NOT. Within the combined condition, parentheses must always be in balanced pairs, so that each left parenthesis precedes its corresponding right parenthesis. These combined conditions are valid: LARRY AND MOE AND (CURLY OR SHEMP) All four are condition-names— level-number 88. I < E AND (E NOT > C) All three symbols are alphanumeric data items. NOT ((A IS POSITIVE) OR (B IS POSITIVE)) Both A and B are numeric data items. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 65 Procedure Division Abbreviated Combined Relation Conditions Abbreviated Combined Relation Conditions COBOL enables you to abbreviate a sequence of complex relation conditions. For example, you can use A NOT EQUAL B OR C instead of having to use (A NOT EQUAL B) OR (A NOT EQUAL C) You can abbreviate any condition in a sequence except the first one by omitting either of these: • The subject, for example: A NOT EQUAL B OR NOT EQUAL C • The relational operator and the subject, for example: A NOT EQUAL B OR C The subject is the term to the left of the operator. For more information, see Usage Considerations:. rel-condition combined-part VST124.vsd rel-condition is a relational condition. combined-part AND OR object NOT rel-operator VST125.vsd rel-operator is a relational operator. object is an identifier, a literal, an arithmetic expression, or an index-name. This abbreviation technique is available when a group of the characteristics shown in Table 8-19 is present. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 66 Procedure Division Abbreviated Combined Relation Conditions Table 8-19. Abbreviated Combined Relation Conditions Characteristics Example Simple relation conditions or negated simple relation conditions A=C are combined using AND and OR operators NOT A = B OR A = C in which a relation condition subject or subject and relational operator is repeated and there are no parentheses (except those delimiting subscripts or reference modifiers) within the sequence. When these conditions are met, any relation condition except the first one in the series can be abbreviated in one of these ways: • • NOT A = B “A =” is repeated The first “A =” Omit the subject. NOT A = B OR = C Omit the subject and the relational operator. NOT A = B OR C When either abbreviated form is used, the omitted subject is considered to be the same as the last explicitly stated subject, and the omitted operator is considered to be the same as the last explicitly stated operator. If any portion of such an abbreviated condition is enclosed in parentheses, all the subjects and operators required for the evaluation of that portion must be included in the same set of parentheses. Usage Considerations: • Abbreviation in a Sequence of Relation Conditions Within a sequence of relation conditions, both of the preceding forms of abbreviation can be used. The effect of using such abbreviations is as if the last preceding stated subject were inserted in place of the omitted subject, and the last stated relational operator were inserted in place of the omitted relational operator. This insertion of an omitted subject or relational operator terminates once a complete simple condition is encountered within a complex condition. • NOT as Modifier or Operator The reserved word NOT in an abbreviated combined relation condition is interpreted as a part of the relational operator if the word immediately following NOT is GREATER, >, LESS, <, EQUAL, or =; otherwise, NOT is interpreted as a logical operator, and the implied insertion of a subject or relational operator results in a negated relation condition. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 67 Procedure Division Condition Evaluation Rules Examples of abbreviated combined and negated relation conditions and expanded equivalents: Abbreviated Combined Relation Condition Expanded Equivalent A > B AND NOT < C OR D ((A > B) AND (A NOT < C)) OR (A NOT < D) A NOT EQUAL B OR C (A NOT EQUAL B) OR (A NOT EQUAL C) NOT (A GREATER B OR < C) NOT ((A GREATER B) OR (A < C)) NOT (A NOT > B AND C AND NOT D) NOT ((((A NOT > B) AND (A NOT > C)) AND (NOT (A NOT > D)))) (A + B - C) > D AND NOT < E OR F (A + B - C) > D AND (A + B - C) NOT < E OR (A + B - C) NOT < F Condition Evaluation Rules Parentheses can be used to specify the order in which individual conditions are to be evaluated when it is necessary to depart from the implied evaluation precedence. Conditions within parentheses are evaluated first. Within nested parentheses, evaluation proceeds from the least inclusive condition to the most inclusive condition. When parentheses are not used, or parenthetical conditions are at the same level of inclusiveness, this hierarchical order of logical evaluation is implied until the final truth value is determined: • • • • • • Values are established for arithmetic expressions. Truth values for simple conditions are established in this order: ° ° ° ° ° Relation Class Condition-name Switch-status Sign Truth values for negated simple conditions are established. Truth values for combined conditions are established, first by applying the AND logical operators, then by applying the OR logical operators. Truth values for negated combined conditions are established. When the sequence of evaluation is not completely specified by parentheses, the order of evaluation of consecutive operations of the same hierarchical level is from left to right. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 68 Procedure Division Concatenation Expressions Using this order of evaluation, once a truth value for an entire complex condition is established, evaluation of the condition ceases. For example, in the complex condition A NOT < 1 AND A NOT > 10 AND B (A) > 5 no attempt is made to fetch B(A) if A is not a valid subscript, because determination that the first condition is FALSE guarantees that the complete complex condition is FALSE. Concatenation Expressions The value of a concatenation expression is the concatenation of the value of its operands. It is the equivalent of a literal of the same class and value, and can be used anywhere that a literal of that class can be used, except in a COPY or REPLACE statement. literal-1 & figurative-constant literal-2 figurative-constant concatenation-expr VST801.vsd literal-1 is either a simple nonnumeric literal, a hexadecimal nonnumeric literal, or a national literal. For information about these literals, see: • • • Simple Nonnumeric Literals Hexadecimal Nonnumeric Literals National Literals literal-2 is either a simple nonnumeric literal, a hexadecimal nonnumeric literal, or a national literal of the same class (alphanumeric or national) as literal-1. figurative-constant is a figurative constant that does not include the word ALL. For information about figurative constants, see Figurative Constants. concatenation-expr is a concatenation expression of the same class (alphanumeric or national) as literal-1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 69 Procedure Division Concatenation Expressions Table 8-20. Maximum Length of Result of Concatenation Expression Class of Operands Length of Result Alphanumeric 160 alphanumeric character positions National 80 national character positions A figurative constant occupies one character position. Table 8-21. Class of Result of Concatenation Expression Number of Operands That Are Figurative Constants Class of Result 0 Same class as the operands (neither of which is a figurative constant) 1 Same class as the other operand (which is not a figurative constant) 2 Alphanumeric Example 8-15. Concatenation Expressions "A zero-terminated string" & X"0" "Another way of getting a zero-terminated string" & LOW-VALUE "A string terminated by the zero digit" & ZERO BLANK & BLANK & "Two leading blanks in the result" "The symbolic constant" & COPYRIGHT & "is defined in SPECIAL-NAMES paragraph" HP COBOL Manual for TNS and TNS/R Programs —522555-006 8- 70 9 Procedure Division Verbs This section describes the COBOL verbs that you can use in the Procedure Division, in alphabetic order. The descriptions of some verbs, such as ADD and INSPECT, show more than one syntax format. For descriptions of the COPY and REPLACE verbs, which you can use in any divisions, see COPY Statement and REPLACE Statement. ACCEPT Form Description ACCEPT With Mnemonic-Name Delivers small amounts of data to a process from a terminal or another process ACCEPT With DATE, DAY, DAY-OF-WEEK, or TIME Phrase Retrieves the numeric representation of the date, day, day of the week, or time from the operating system ACCEPT With Mnemonic-Name ACCEPT with a mnemonic-name delivers small amounts of data to a process from a terminal or another process. accept-name ACCEPT FROM mnemonic-name VST126.vsd accept-name is the identifier of an elementary item or data structure (not an index-name, index data item, special register, or national data item) in which the process can store accepted data. mnemonic-name identifies a terminal or another process from which the process can accept data. You must associate mnemonic-name with a terminal or file name in the Environment Division (see SPECIAL-NAMES Paragraph). Note. If mnemonic-name is associated with CONSOLE in the SPECIAL-NAMES paragraph, you cannot use it in an ACCEPT statement. CONSOLE maps to $0, an outputonly device. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -1 Procedure Division Verbs ACCEPT With Mnemonic-Name Usage Considerations: • Differences in the OSS and Guardian Environments In the OSS environment but not in the Guardian environment: ° ° • No prompt is given for an ACCEPT statement. If an ACCEPT statement includes mnemonic-name, it must be the OSS pathname of a Guardian process or terminal. If mnemonic-name is an OSS device, the compiler issues a warning and the default input device (#IN) is used instead. If mnemonic-name Is Not Specified If you omit the phrase FROM mnemonic-name, the process accepts data from its default input device or default input-output device. (See Specifying Default Input and Output Devices or Specifying a Default Input-Output Device.) The default input device or default input-output device is usually the home terminal, except in a Pathway environment where the COBOL run unit is functioning as a server. In that case, the server class command SET SERVER determines the default input device or default input-output device (see the TS/MP System Management Manual). • Specifying the Default Input-Output Device as mnemonic-name If you want the process to accept data from its default input-output device, omit the FROM phrases from the ACCEPT statements and specify a default input-output device before executing the program. (See Specifying Default Input and Output Devices or Specifying a Default Input-Output Device.) Do not specify the default input-output device as the mnemonic-name, because this causes the process to terminate abnormally. • If mnemonic-name Is Not Open If mnemonic-name specifies a process that has not been opened by an earlier ACCEPT or DISPLAY statement, or specifies a terminal, then the accepting process opens the process or terminal that mnemonic-name specifies as if it were a file. • If Process Cannot Open or Accept Data From mnemonic-name If the process cannot open or accept data from the terminal or process that mnemonic-name specifies, the process tries to accept data from its home terminal. If the home terminal is also unavailable, the process assigns the value 0 to each numeric or numeric edited receiving item and fills any other category of receiving item with spaces. • Cursor Placement When mnemonic-name Is a Terminal If mnemonic-name specifies a terminal that was the object of a DISPLAY NO ADVANCING statement, then the ACCEPT statement sets the cursor at the location following that where the display operation ended; otherwise, the ACCEPT statement prompts with a question mark (?) and awaits input. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -2 Procedure Division Verbs • ACCEPT With Mnemonic-Name Whether Process Closes mnemonic-name or Leaves It Open If mnemonic-name specifies a terminal that was not the object of a DISPLAY NO ADVANCING statement, then the process closes the terminal after accepting data from it. If mnemonic-name specifies another process or a terminal that was the object of a DISPLAY NO ADVANCING statement, then the process leaves the other process or terminal open. • Case Sensitivity The ACCEPT statement does not change the letters in the accepted data from lowercase to uppercase or from uppercase to lowercase when it stores them in accept-name. To perform such a conversion, use the INSPECT CONVERTING statement. • Alphabetic, Alphanumeric, and Alphanumeric Edited Data If accept-name is an alphabetic, alphanumeric, or alphanumeric edited data item, the process collects data in an intermediate data item using one or more read operations. Each read operation collects zero or more characters from the process or terminal that mnemonic-name specifies, up to the maximum physical record size for that process or terminal (a typical maximum physical record size for a terminal is 80 characters). If a read operation gets a null response (that is, if the user enters only a carriage return), the ACCEPT statement appends space characters to the intermediate data item until its length is that of accept-name. If a response is not null but contains fewer characters than the maximum physical record size of the process or terminal that mnemonic-name specifies, the ACCEPT statement appends space characters to the response until its length is that of accept-name. The ACCEPT statement constructs the intermediate item by appending responses in the order in which it receives them, and continues to execute read operations until it has filled accept-name or received a null response. Finally, the ACCEPT statement moves the value of the intermediate item to accept-name, following the rules for the MOVE statement. • Numeric and Numeric Edited Data If accept-name is a numeric or a numeric edited data item, the process collects data with one read operation. The response to the read operation must be in numeric literal format (see Decimal Numeric Literals and Hexadecimal Numeric Literals). A null response or a response containing only spaces is invalid for a numeric or a numeric edited accept-name. If the response to the read operation is not in numeric literal format, the ACCEPT statement reprompts with: ** Improper numeric value. Resupply input ** HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -3 Procedure Division Verbs ACCEPT With Mnemonic-Name If the response is in numeric literal format, the ACCEPT statement converts it to a numeric literal in an intermediate data item and then moves the value of the intermediate data item to accept-name. If accept-name has no fractional part, any necessary truncation of the intermediate data item value deletes the rightmost digits of the value; otherwise, the transfer of the data from the intermediate item to accept-name follows the rules for the MOVE statement. Example 9-1. ACCEPT Statement Reading From a Terminal WORKING-STORAGE SECTION. 01 COMMAND-IN PICTURE X(7) 88 ADD-C 88 UPDATE-C 88 DELETE-C 88 EXIT-C ... PROCEDURE DIVISION. ... DISPLAY "ENTER COMMAND" ACCEPT COMMAND-IN IF ADD-C ... VALUE VALUE VALUE VALUE VALUE SPACES. "ADD". "UPDATE". "DELETE". "EXIT". In Example 9-2, the ACCEPT statement reads an alphanumeric value into an accept-name whose length (60 characters) exceeds the record size of the terminal (40 characters). Example 9-2. ACCEPT Statement Reading Alphanumeric Data WORKING-STORAGE SECTION. 01 HEADING-IN PICTURE X(60) VALUE SPACES. ... PROCEDURE DIVISION. ... DISPLAY "Enter heading (up to 60 characters)" ACCEPT HEADING-IN DISPLAY HEADING-IN MOVE HEADING-IN TO HEADING-OUT ... Figure 9-1 shows the run-time interactions at the terminal. The user’s responses to the ACCEPT statement’s prompts are in bold font. When the user enters the fortieth character with no carriage return, the ACCEPT statement prompts again. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -4 Procedure Division Verbs ACCEPT With Mnemonic-Name Figure 9-1. ACCEPT Statement Collecting Alphanumeric Data 1 2 3 4 1234567890123456789012345678901234567890 Enter heading (up to 60 characters). ?Certification of Karl Michael Weaver as a? COBOL analyst Certification of Karl Michael Weaver as a COBOL analyst Column Display Accept line 1 Accept line 2 Display VST526.vsd Example 9-3. ACCEPT Statement Reading Numeric Data ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP System. OBJECT-COMPUTER. HP System. SPECIAL-NAMES. FILE "#TERM" IS USER-TERMINAL. ... WORKING-STORAGE SECTION. 01 PROGRAM-CODE PICTURE 999V99. ... PROCEDURE DIVISION. DEMO. PERFORM UNTIL PROGRAM-CODE = 0 DISPLAY "ENTER RUN CODE" UPON USER-TERMINAL ACCEPT PROGRAM-CODE FROM USER-TERMINAL DISPLAY "CODE RECEIVED: " PROGRAM-CODE UPON USER-TERMINAL END-PERFORM ... Figure 9-2 shows run-time interactions at the home terminal (#TERM). The user’s responses to the ACCEPT statement’s prompts are in bold font. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -5 Procedure Division Verbs ACCEPT With DATE, DAY, DAY-OF-WEEK, or TIME Phrase Figure 9-2. ACCEPT Statement Collecting Numeric Data ENTER RUN CODE ?123 CODE RECEIVED: 123.00 Low-order zeros assumed ENTER RUN CODE ?12345 CODE RECEIVED: 345.00 High digits lost, by MOVE rules ENTER RUN CODE ?1.2345 Low digits lost, by MOVE rules CODE RECEIVED: 001.23 ENTER RUN CODE Null value entered ? ** Improper numeric value. Resupply input ** ?1.23 CODE RECEIVED: 001.23 VST527.vsd ACCEPT With DATE, DAY, DAY-OF-WEEK, or TIME Phrase ACCEPT with a DATE, DAY, DAY-OF-WEEK, or TIME phrase retrieves the numeric representation of the date, day, day of the week, or time from the operating system. Note. A simpler alternative is the CURRENT-DATE Function. ACCEPT accept-name FROM DATE YYYYMMDD DAY YYYYDDD DAY-OF-WEEK TIME VST127.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -6 Procedure Division Verbs ACCEPT With DATE, DAY, DAY-OF-WEEK, or TIME Phrase accept-name is the identifier of the data item to which the representation of the day, date, day of the week, or time is moved (following the rules for the MOVE statement). Typical definitions for the data items are: Data Item DATE DAY Typical Definitions Without YYYYMMDD PICTURE 9(6) or PICTURE 99B99B99 With YYYYMMDD PICTURE 9(8) or PICTURE 9999B99B99 Without YYYYDDD PICTURE 9(5) or PICTURE 99B999 With YYYYDDD PICTURE 9(7) or PICTURE 9999B999 DAY-OF-WEEK PICTURE 9 TIME PICTURE 9(8) or PICTURE 99B99B99B99 DATE delivers the current date. YYYYMMDD Without YYYYMMDD, DATE behaves as if it were a data item described with the PICTURE character-string 9(6) organized as yymmdd where yy is the year of the century; for example, July 10, 1992, is represented as 920710. With YYYYMMDD, DATE behaves as if it were a data item described with the PICTURE character-string 9(8) organized as yyyymmdd; for example, July 10, 1992, is represented as 19920710. DAY delivers the current year and serial day number. YYYYDDD Without YYYYDDD, DAY behaves as if it were a data item described with the PICTURE character-string 9(5) organized as yyddd; for example, January 23, 1992, is represented as 92023. With YYYYDDD, DAY behaves as if it were a data item described with the PICTURE character-string 9(7) organized as yyyyddd; for example, January 23, 1992, is represented as 1992023. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -7 Procedure Division Verbs ACCEPT With DATE, DAY, DAY-OF-WEEK, or TIME Phrase DAY-OF-WEEK delivers the value of the current day of the week expressed as an integer between 1 and 7, inclusive. The value 1 represents Monday, 2 represents Tuesday, and so on. TIME delivers the current time of day. TIME behaves like a data item described with the PICTURE character-string 9(8) organized as four pairs of digits—hhmmsscc, where hh is the hour (based on a 24-hour clock), mm is the minutes, ss is the seconds, and cc is the hundredths of seconds. For example, 2:41 p.m. is expressed as 14410000. The minimum value of TIME is 00000000; the maximum value is 23595999. In Example 9-4, ACCEPT statements tell the executing process to store the current day of the week (integer) in DAY-SUB, the current date (yymmdd ) in TODAYS-DATE, the current time (hhmmsscc ) in TIME-RIGHT-NOW, and 40 characters from the home terminal in USER-REPLY. Example 9-4. ACCEPT Statements Reading Current Data and Time WORKING-STORAGE SECTION. 01 DATE-AND-TIME-FIELDS. 05 DAY-SUB PIC 9 VALUE 05 TODAYS-DATE PIC 9(6) VALUE 05 TIME-RIGHT-NOW PIC 9(8) VALUE 77 USER-REPLY PIC X(40) VALUE ... PROCEDURE DIVISION. ... ACCEPT DAY-SUB FROM DAY-OF-WEEK ACCEPT TODAYS-DATE FROM DATE ACCEPT TIME-RIGHT-NOW FROM TIME ACCEPT USER-REPLY ZERO. ZERO. ZERO. SPACES. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -8 Procedure Division Verbs ADD ADD Form Description ADD TO Adds the sum of one or more numeric values to one or more result data items; for example, ADD A B C TO D E stores A+B+C+D in D and stores A+B+C+E in E Adds two or more numeric values and replaces the current value of one or more result data items with that sum; for example, ADD GIVING ADD A B C GIVING D E stores A+B+C in both D and E ADD CORRESPONDING Adds numeric elements of one data structure to corresponding numeric elements of another data structure (not recommended) ADD TO ADD TO adds the sum of one or more numeric values to one or more result data items; for example, ADD A B C TO D E stores A+B+C+D in D and stores A+B+C+E in E. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -9 Procedure Division Verbs ADD TO addend ADD TO result ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-ADD VST128.vsd addend is a numeric literal or the identifier of an elementary numeric data item. result is the identifier of an elementary numeric data item to which addend or the sum of the addends is added. ROUNDED specifies that result is to be rounded before being stored. imperative-stmt-1 is an imperative statement to be executed if a size error occurs during the addition of addends or the storing of a result. imperative-stmt-2 is an imperative statement to be executed if no size error occurs during the addition of addends or the storing of a result. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 10 Procedure Division Verbs ADD TO END-ADD ends the scope of the ADD statement and makes it a delimited-scope statement. If you omit END-ADD but include the SIZE ERROR or NOT SIZE ERROR phrase, the ADD statement is a conditional statement and ends at the next period separator. Usage Considerations: • Specifying the Same Data Item for More Than One Result For each result, the sum of the addends is added to the current value of result, and that new sum becomes the new value of result (after rounding if rounding was specified). If more than one result specifies the same data item, the final value of that item reflects multiple additions of the intermediate sum. For example, if the initial value of A is 2, then the statement ADD 5 TO A A A changes the value of A to 7, and then 12, and finally 19. • Operand Identification Order For each result, operand identification occurs just prior to the add-and-store operation; therefore, in the statement ADD A B C TO I I X(I) the subscript is not evaluated until A+B+C is added to I twice. • Arithmetic Operations See Arithmetic Operations for information on data conversion and alignment, intermediate results, multiple results (and subscript evaluation), and incompatible data. • Precision See ADD and SUBTRACT Statements for information on precision of addition. • ROUNDED, SIZE ERROR, and NOT SIZE ERROR Phrases See ROUNDED Phrase and SIZE ERROR Phrase for information on these phrases. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 11 Procedure Division Verbs ADD GIVING ADD GIVING ADD GIVING adds two or more numeric values and replaces the current value of one or more result data items with that sum; for example, ADD A B C GIVING D E stores A+B+C in both D and E. addend ADD addend GIVING TO result ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-ADD VST129.vsd addend is a numeric literal or the identifier of an elementary numeric data item. result is the identifier of an elementary numeric data item to which addend or the sum of the addends is added. ROUNDED specifies that result is to be rounded before being stored. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 12 Procedure Division Verbs ADD GIVING imperative-stmt-1 is an imperative statement to be executed if a size error occurs during the addition of addends or the storing of a result. imperative-stmt-2 is an imperative statement to be executed if no size error occurs during the addition of addends or the storing of a result. END-ADD ends the scope of the ADD statement and makes it a delimited-scope statement. If you omit END-ADD but include the SIZE ERROR or NOT SIZE ERROR phrase, the ADD statement is a conditional statement and ends at the next period separator. Usage Considerations: • Changing Addend Values The ADD GIVING statement does not change the value of an addend unless you also specify that addend for result. • See these usage considerations in ADD TO: ° ° ° ° Operand Identification Order Arithmetic Operations Precision ROUNDED, SIZE ERROR, and NOT SIZE ERROR Phrases HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 13 Procedure Division Verbs ADD CORRESPONDING ADD CORRESPONDING ADD CORRESPONDING adds numeric elements of one data structure to corresponding numeric elements of another data structure. Caution. ADD CORRESPONDING is not recommended, because minor changes to one data structure can change the correspondence between its elements and those of the other data structure, and this is difficult to detect. ADD CORRESPONDING group-1 TO group-2 CORR ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-ADD VST130.vsd CORRESPONDING CORR are equivalent and specify that the values of corresponding elementary items of two data structures are to be added. group-1 is the identifier of a data structure in which some or all of the elementary items are numeric. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 14 Procedure Division Verbs ADD CORRESPONDING group-2 is the identifier of a data structure in which some or all of the elementary items are numeric. The value of each elementary numeric item in group-2 that corresponds to an elementary numeric item in group-1 is replaced by the sum of the two corresponding items, as in the ADD TO statement. ROUNDED specifies that result is to be rounded before being stored. imperative-stmt-1 is an imperative statement to be executed if a size error occurs during the addition of addends or the storing of a result. imperative-stmt-2 is an imperative statement to be executed if no size error occurs during the addition of addends or the storing of a result. END-ADD ends the scope of the ADD statement and makes it a delimited-scope statement. If you omit END-ADD but include the SIZE ERROR or NOT SIZE ERROR phrase, the ADD statement is a conditional statement and ends at the next period separator. Usage Considerations: • Definition of Correspondence See CORRESPONDING Phrase. • ADD CORRESPONDING Statement Generates ADD TO Statements Each pair of corresponding elementary data items, group-1-item and group-2-item, generates an ADD TO statement equivalent to this: ADD group-1-item TO group-2-item [ROUNDED] • Problem Adding Names to Group Data Items When adding names to group data items that appear in ADD CORRESPONDING statements, verify that the new name will not be included in unintended addition operations. • See these usage considerations in ADD TO: ° ° ° ° Operand Identification Order Arithmetic Operations Precision ROUNDED, SIZE ERROR, and NOT SIZE ERROR Phrases HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 15 Procedure Division Verbs ALTER Correspondence depends on the names of the elementary items, not on the physical order of the elementary items. In Example 9-5, all data item names correspond except STAPLES and PAPER. Add operations skip STAPLES and PAPER. Example 9-5. ADD CORRESPONDING Statement WORKING-STORAGE SECTION. 01 CABINET-SUPPLIES. 05 PAPER-CLIPS PIC 99. 05 WRITING-TOOLS. 10 PENCILS PIC 99. 10 PENS PIC 99. 10 ERASERS PIC 99. 10 PAPER PIC 99. 05 STAPLES PIC 99. 01 STOCKROOM-SUPPLIES. 05 WRITING-TOOLS. 10 PENCILS PIC 99. 10 ERASERS PIC 99. 10 PENS PIC 99. 05 PAPER-CLIPS PIC 99. 05 PAPER PIC 99. ... PROCEDURE DIVISION. ... ADD CORRESPONDING CABINET-SUPPLIES TO STOCKROOM-SUPPLIES. ALTER Note. The 1985 COBOL standard classifies ALTER as obsolete, so you are advised not to use it. Instead, use a flag, a conditional GO TO statement, and a MOVE statement. ALTER changes the destination of a GO TO statement, which can cause maintenance problems. ALTER TO paragraph-name destination PROCEED TO VST131.vsd paragraph-name is the name of a paragraph that contains only an unconditional GO TO statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 16 Procedure Division Verbs ALTER destination is the name of a paragraph or section to which the GO TO statement in paragraph-name transfers control. Usage Considerations: • Maintenance Problems ALTER can cause maintenance problems because it enables a GO TO statement to transfer control anywhere in the program. When you read the source code, the only clue you have that the destination was altered is that the GO TO statement is alone in a paragraph. • Using a Flag, Conditional GO TO, and MOVE Instead of ALTER Suppose that you want to initialize a routine the first time it is called, but not each time it is called. You could either use an ALTER statement as Example 9-6 does (not recommended) or a flag, a conditional GO TO statement, and a MOVE statement as Example 9-7 does (recommended and no less efficient). Example 9-6. ALTER Statement PROCEDURE DIVISION. ROUTINE-1. GO TO INITIALIZATION-ROUTINE. INITIALIZATION-ROUTINE. ... ALTER ROUTINE-1 TO PROCEED TO ROUTINE-2. GO TO ROUTINE-2. ROUTINE-2. ... Example 9-7. Alternative to ALTER Statement DATA DIVISION. WORKING-STORAGE SECTION. 77 FLAG VALUE IS 1. PROCEDURE DIVISION. ROUTINE-1. GO TO INITIALIZATION-ROUTINE ROUTINE-2 DEPENDING ON FLAG. INITIALIZATION-ROUTINE. ... MOVE 2 TO FLAG. GO TO ROUTINE-2. ROUTINE-2. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 17 Procedure Division Verbs • CALL paragraph-name in an Independent Segment If paragraph-name is in an independent segment (a section whose segmentnumber is greater than 49), these restrictions apply: • ° Every ALTER statement that references the paragraph-name must be in a section that has the same segment-number as the section containing paragraph-name. ° If the destination is in a section that does not have the same segmentnumber as the section containing paragraph-name, these restrictions apply: ° An ALTER statement in the Declaratives Portion cannot refer to a paragraph-name or destination in the other portion of the Procedure Division. ° An ALTER statement cannot be used to establish a potential transfer of control between the Declaratives Portion and the other portion of the Procedure Division. ° An ALTER statement cannot refer to a paragraph-name or destination in any debugging declarative procedure unless the ALTER statement itself is in a debugging declarative procedure. ° An ALTER statement cannot be used to establish a potential transfer of control between a debugging declarative procedure and a nondebugging declarative procedure. Canceling the Effects of ALTER Statements The effect of an ALTER statement persists until the execution of either: ° ° Another ALTER statement with the same destination A CANCEL statement in which program-name is the program containing the paragraph in which destination appears. CALL CALL’s behavior is determined by the PORT directive. If the program is not compiled with the PORT directive, CALL transfers control from one COBOL program to another COBOL program. The called program can be in the current compilation unit or can be extracted from an object file, provided that the entry point called is in a code block created by a COBOL compiler on an HP system. To transfer control from a COBOL program to a program written in another language in the absence of the PORT directive, use ENTER (see ENTER). If the program is compiled with the PORT directive and runs in the CRE, CALL behaves like the X/Open CALL statement (which is not an element of COBOL). The HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 18 Procedure Division Verbs CALL X/Open CALL statement transfers control from an HP COBOL program to a program written in another language. Note. If you use the X/Open CALL statement in the OSS environment, see Mixed-Language Programs. If the called program is not a function, or the calling program was compiled by the COBOL85 compiler with the ENV LIBRARY directive, the X/Open CALL statement does not change the value of RETURN-CODE. If the value of the function is greater than 99,999, arithmetic overflow occurs. If the called program is not a function, or was compiled by the COBOL85 compiler with the ENV LIBRARY directive, the called program cannot change the value of RETURNCODE. If a called program changes the value of RETURN-CODE, the calling program can access that value when control returns to the calling program. If the program was not compiled with the PORT directive, RETURN-CODE is inaccessible. CALL called-entity END-CALL USING phrase on-phrase not-on-phrase historical-on-phrase VST132.vsd called-entity program-name OF file-mnemonic IN identifier VST133.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 19 Procedure Division Verbs CALL program-name is the program-name in the called program’s PROGRAM-ID paragraph. It can be expressed as a nonnumeric literal (enclosed in quotation marks) or the actual name (not enclosed in quotation marks). The form enclosed in quotation marks is recommended. If the program is not compiled with the PORT directive or does not run in the CRE, the called program must be a COBOL program. If the program is compiled with the PORT directive and runs in the CRE, the called program can have been compiled with any of these HP compilers: Architecture HP Compilers TNS C COBOL85 FORTRAN Pascal TAL TNS/R C C++ NMCOBOL pTAL file-mnemonic is the alias for the object file to be searched for the called program. The association between file-mnemonic and the object file is established by the File-Mnemonic clause of the SPECIAL-NAMES paragraph. The filemnemonic is not part of program-name and is not a qualifier that can make program-name unique. For the NMCOBOL compiler, file-mnemonic must specify either: • • A linkfile An archive file identifier can be used only if you are calling a COBOL program. It is an alphanumeric identifier whose value, the program-name in the called program’s PROGRAM-ID paragraph, is not known until run time. The compiler ignores leading and trailing spaces in program-name and converts it to uppercase. You must include the called program in the run unit, usually with a separate bind or link step. All parameters are passed as extended addresses; therefore, formal parameters in the called program must not specify ACCESS MODE STANDARD. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 20 Procedure Division Verbs CALL USING phrase USING parameter-1 REFERENCE BY CONTENT VALUE parameter-2 VST134.vsd USING marks the beginning of the parameter list. The Procedure Division header of the called program must contain a corresponding USING phrase. REFERENCE specifies that the called program uses the actual data item of the calling program. If the called program changes the value of the parameter, it changes the value of the data item in the calling program. REFERENCE applies to all the parameters that follow it until a CONTENT or VALUE phrase appears. This is the default. CONTENT specifies that the calling program makes a copy of the data item and passes the address of the copy to the called program. If the called program changes the value of the parameter, it does not change the value of the data item in the calling program. CONTENT applies to all the parameters that follow it until a REFERENCE or VALUE phrase appears. VALUE specifies that the calling program passes the value of the data item to the called program. Nothing that the called program does with the value affects the data item in the calling program. VALUE applies to all the parameters that follow it until a REFERENCE or CONTENT phrase appears. If you specify VALUE, the called program must be not be written in COBOL and you must compile the calling program with the PORT directive and either the ENV COMMON or ENV LIBRARY directive. VALUE is not an element of COBOL. If you also compile the calling program with a FIPS directive with NONSTANDARDEXT in the flag-option-list, the compiler issues a warning message if it finds the keyword VALUE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 21 Procedure Division Verbs CALL parameter-1 is a data item defined in the Linkage, File, Working-Storage, or ExtendedStorage Section. It must be one of: • • • • An elementary data item A level-01 data item A level-77 data item A data item whose level is other than 01 or 77 is aligned on a 2-byte boundary If parameter-1 is subscripted, its first occurrence must be on a 2-byte boundary and the number of occurrences must be even. The number of parameter-1 s must be the same as the number of parameters defined in the USING phrase of the called program. The size of each parameter must be the same as the size of the corresponding parameter in the called program. See Linkage Section. If the called program is not written in COBOL, parameter-1 must be exactly the data type that the called program expects. parameter-2 is a data item defined in the Linkage, File, Working-Storage, or ExtendedStorage Section. It must be one of these data types: parameter-2 Corresponding Formal Parameter Numeric data item described as COMP-5 with PICTURE S9(4) or NATIVE-2 16-bit data item Numeric data item described as COMP-5 with PICTURE S9(9) or NATIVE-4 32-bit data item (2 words for a TNS program, 1 word for a native program) Numeric data item described as COMP-5 with PICTURE S9(18) or NATIVE-8 64-bit data item (four words for a TNS program, 2 words for a native program) 1-character alphanumeric data item Single character If you are concerned about portability, use COMP-5 rather than NATIVE-2, NATIVE-4, or NATIVE-8. on-phrase EXCEPTION excp-imperative-statement ON VST615.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 22 Procedure Division Verbs CALL historical-on-phrase excp-imperative-statement EXCEPTION ON OVERFLOW VST135.vsd excp-imperative-statement is an imperative statement to be executed when an exception prevents calling the specified program. Note. Although you can specify excp-imperative-statement in any CALL statement, it only works when the called program is a COBOL program. For programs written in languages other than COBOL, it is ignored. not-on-phrase NOT EXCEPTION ON non-excp-imperative-statement VST528.vsd non-excp-imperative-statement is an imperative statement to be executed when the specified program completes its execution and returns control to the program that called it. END-CALL ends the scope of the CALL statement and makes it a delimited-scope statement. If you omit END-CALL but include the EXCEPTION or NOT EXCEPTION phrase, the CALL statement is a conditional statement and ends at the next period separator. Usage Considerations: • Currently Active Program The currently active programThe currently active program, the one containing the CALL statement, is the calling program; the program identified by program-name or by the value of identifier is the called program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 23 Procedure Division Verbs • CALL Effect of CALL Statement Without PORT Directive If the object form of the called program is included in the run unit that contains the calling program, or if the called program is in the user library, execution of the CALL statement transfers control from the calling program to the called program. When the called program executes an EXIT PROGRAM statement or allows control to pass beyond the end of its Procedure Division, control returns to the calling program. If a NOT ON EXCEPTION phrase (not-on-phrase ) is specified, control passes to non-excp-imperative-statement and execution continues according to the rules for that statement. Unless that statement transfers control elsewhere, control passes from that statement to the end of the CALL statement. If the object form of the called program is not included in the run unit, the action of the CALL statement depends on the presence or absence of an EXCEPTION phrase (on-phrase or historical-on-phrase ). If an EXCEPTION phrase is specified, control passes to excp-imperative-statement. If an EXCEPTION phrase is not specified, the run unit terminates abnormally with a failure message. • Determining Which Program a CALL program-name Statement Calls The steps for determining which program the CALL statement calls follow. 1. The value of program-name—the program name—is stripped of leading and trailing spaces and is converted to uppercase. (All COBOL program names are converted to uppercase for the purpose of matching.) 2. If the program name from Step 1 is that of a COBOL program that was compiled in this compilation unit, then that program is the called program. 3. If the program name from Step 1 is not that of a program that was compiled in this compilation unit, then the program searches for a program by that name in these places, in this order: a. The file associated with file-mnemonic (if file-mnemonic is specified) b. The files on the primary search list (established by the SEARCH directive) c. The files on the tertiary search list (established by the CONSULT directive) d. For a TNS program, the TNS user library (established by the LIBRARY directive) e. The files associated with SEARCH DEFINEs 4. If the program name from Step 1 is that of a program in one of the preceding files, that program is the called program. 5. The program name from Step 1 is restored to its original case. 6. Step 3 is repeated. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 24 Procedure Division Verbs CALL 7. The program name from Step 4 is converted back to uppercase and compilation continues. When compilation ends (at the end of the source file), if a COBOL program with the desired name has been compiled, then it is the called program. 8. If no program is found using the above steps, then the calling program looks for a VALUE phrase. If the VALUE phrase is absent, the calling program assumes that the CALL statement is a COBOL CALL statement. It passes the uppercase name to the Binder (for a TNS program) or the nld or ld utility (for a native program) and passes all parameters by reference as extended addresses. 9. If the VALUE phrase is present, the calling program assumes that the CALL statement is an X/Open CALL statement. It passes the name as it was specified in program-name to the Binder (for a TNS program) or the nld or ld utility (for a native program) and passes all parameters as extended addresses—the VALUE parameters by value and all others by reference. 10. If you are calling a program written in a language other than COBOL, and it has no VALUE parameters, you must make the program stub of the called program available to the compiler using one of the files listed in Step 3. 11. If the program that program-name specifies is not available at execution time, an exception exists. 12. If you are building a PIC loadfile, and you want rld to run your program with unresolved externals, you must link your program with either of these ld options: • • • -set rld_unresolved IGNORE -set rld_unresolved WARN Two COBOL Programs With the Same Name Two or more COBOL programs in a run unit can have the same program name. If this happens, the compilation distinguishes between them according to these scope rules: ° If program A lacks the COMMON attribute and is directly contained in program B, then only CALL statements in B can call A. ° If program A has the COMMON attribute and is directly contained in program B, then only CALL statements in B and CALL statements in other programs contained in B (except for A and those contained in A) can call A. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 25 Procedure Division Verbs • CALL Binding or Linking a Program Called With a CALL identifier Statement Binding or linking a program called with a CALL identifier statement into a run unit is not automatic. Verify that all such programs are bound or linked into the run unit by doing one of: • ° ° Compile all the program units in a single source file. ° Have each required program bound or linked into the run unit by referring to the program explicitly in the source program with a dummy CALL statement and then calling the program by an identifier. ° ° For a TNS program, bind the program into the user library. For a TNS program, use the Binder object-file builder to bind the required program units into the run unit (see the Binder Manual). For a native program, use the nld or ld utility to link them into the run unit (see the nld Manual or the ld Manual). Use the SEARCH directive to add the program to the primary search list. How the BIND Process Finds the Object File (TNS Programs Only) If file-mnemonic is present but the BIND process does not find the called program in the associated object file, BIND reports an error. If file-mnemonic is absent but a search list was specified, the BIND process searches for the object file as explained in How the Compiler Validates and Resolves References. • Initial State of Called Programs A program that has the INITIAL attribute is in its initial state every time it is called. Programs directly or indirectly contained within a program that has the INITIAL attribute also have the INITIAL attribute. A program that does not have the INITIAL attribute is in its initial state the first time it is called, but each successive time it is called, it is usually in the state in which its previous execution left it. This state includes the final value of each internal data item (except those described in the Linkage Section), the final status of each internal file connector, and the final status of each GO TO statement whose destination procedure was specified by an ALTER statement. A program that does not have the INITIAL attribute is not in the state in which its previous execution left it if its calling program cancelled it with a CANCEL statement. In this case, the called program is in its initial state the next time it is called. All PERFORM statements in the program are restored to their initial states. All files are closed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 26 Procedure Division Verbs • CALL Storage Allocation For programs with the INITIAL attribute, HP COBOL uses dynamic storage allocation, allocating space for data items in the Working-Storage Section each time the program is called and releasing it each time the program is exited. This can cause stack overflow, which can cause the run unit to terminate abnormally. For programs without the INITIAL attribute, HP COBOL allocates space at the start of execution of the run unit for all program data except internal data, which it allocates when the program is called. It is unlikely that allocating space for internal data (usually a small amount) will cause stack overflow. • Passing Parameters Parameters passed by the USING phrase are data items from a calling program that the called program can reference. • Correspondence of Formal and Actual Parameters The formal parameters in the USING phrase of the Procedure Division header and the actual parameters in the USING phrase of the CALL statement correspond by position, not by name. • Declaration Locations and Access Modes of Formal and Actual Parameters You must declare formal parameters in the Linkage Section. For a TNS program, a parameter declared in the Linkage Section has EXTENDED-STORAGE access mode (a 32-bit address) unless you specify STANDARD access mode (a 16-bit address). For a native program, every parameter has a 32-bit address. If you specify STANDARD access mode, the NMCOBOL compiler ignores it and issues a warning. If a formal parameter has EXTENDED-STORAGE access mode, its corresponding actual parameter can have either STANDARD or EXTENDED-STORAGE access mode. If a formal parameter has STANDARD access mode, its corresponding actual parameter must also have STANDARD access mode. For an actual parameter to have STANDARD access mode, you must declare it in the File Section or Working-Storage Section. If you declare an actual parameter in the Linkage Section of the calling program and pass it to a formal parameter whose access mode is STANDARD, the COBOL85 compiler reports an error, but the program might work. • Parameter Validation The COBOL85 and NMCOBOL compilers report errors under these conditions: ° The number of actual parameters (in the CALL statement) differs from the number of formal parameters (in the Procedure Division heading). ° For a TNS program, the access mode of an actual parameter is incompatible with that of its corresponding formal parameter. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 27 Procedure Division Verbs CALL The COBOL85 compiler determines the access mode of the parameters in one of these ways: ° The called program is found in an existing object file (either the object file named by mnemonic-name or an object file named in the SEARCH directive). The required parameter types are defined by the program in the existing object file. ° The called program has been compiled earlier in the current compilation. The required parameter types are defined by the Linkage Section of the called program. ° The called program has not yet been found during the current compilation, or is specified by identifier rather than by an explicit program-name. The compiler assumes that all parameters are passed with extended addresses (the default for the Linkage Section of the called program). If the called program declares any matching parameters with ACCESS MODE STANDARD, the program executes incorrectly. If identifier is not specified, a subsequent attempt to bind the missing program to the run unit can cause a Binder error. The HP COBOL compilers do not report errors under these conditions: • ° The type (alphanumeric, numeric, and so on) of an actual parameter differs from that of its corresponding formal parameter. ° The size of an actual parameter differs from that of its corresponding formal parameter. Passing Index Values You cannot pass an index-name (defined by the INDEXED phrase of an OCCURS clause) as a parameter because it is not a level 01, level 77, or elementary data item. You can pass an index value in an index data item (defined by a USAGE INDEX clause) as a parameter, but there is no correspondence between the indexname used with the table in the calling program and the index-name used with the table in the called program. Index-names in the called and calling program always refer to separate data areas. • Recursion Although called programs can contain CALL statements, a called program cannot call itself explicitly or implicitly. • Calling and Called Program Using the Same File A called program does not inherit access to an internal file opened by its caller. A calling program and a called program can operate on records of the same file in these ways: ° One of the programs does all the reading and writing and passes the data items as parameters to the other. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 28 Procedure Division Verbs ° ° ° • CALL Each program opens the file as an internal file with a separate file connector. The file name has the GLOBAL attribute. The file is declared in any program and is given the EXTERNAL attribute. Then the file belongs to the run unit, and any program in the run unit that declares the same file with the EXTERNAL attribute can share in its manipulation. Difference Between X/Open CALL Statement and ENTER Statement The X/Open CALL statement reports an error if the types of the actual and formal parameters do not match; the ENTER statement attempts to convert the actual parameters into the types of the formal parameters. Example 9-8. Called Program That Calls Another Program (page 1 of 3) Main Program (source $DATA.MYSUBVOL.MAINSRC, object $DATA.MYSUBVOL.MAINOBJ) IDENTIFICATION DIVISION. PROGRAM-ID. COBOLMAIN. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP System. OBJECT-COMPUTER. HP System. SPECIAL-NAMES. FILE "$DATA.MYSUBVOL.SUB1OBJ" IS SUB1. DATA DIVISION. WORKING-STORAGE SECTION. 01 DATA-OUT PIC X(80) VALUE "I'M THE MAIN AND I'M ALIVE". 77 PARM1 PIC 99 VALUE 10. 77 PARM2 PIC XX VALUE "AB". 01 MAIN-TABLE. 05 TABLE-DATA PIC X OCCURS 10 TIMES INDEXED BY TABLE-INDEX. 01 SAVE-TABLE-INDEX PIC 999. PROCEDURE DIVISION. START-PROGRAM. DISPLAY DATA-OUT SET TABLE-INDEX TO 5 SET SAVE-TABLE-INDEX TO TABLE-INDEX DISPLAY "SAVE-TABLE-INDEX = " SAVE-TABLE-INDEX CALL COBSUB1 OF SUB1 USING PARM1 PARM2 MAIN-TABLE SAVE-TABLE-INDEX END-CALL DISPLAY "PROGRAM END" STOP RUN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 29 Procedure Division Verbs Example 9-8. Called Program That Calls Another Program (page 2 of 3) Level 1 Subprogram (source $DATA.MYSUBVOL.SUB1SRC, object $DATA.MYSUBVOL.SUB1OBJ) IDENTIFICATION DIVISION. PROGRAM-ID. COBSUB1. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP System. OBJECT-COMPUTER. HP System. SPECIAL-NAMES. FILE "$DATA.MYSUBVOL.SUB2OBJ" IS SUB2. DATA DIVISION. WORKING-STORAGE SECTION. 01 DATA-OUT PIC X(80) VALUE "I'M COBSUB1 ALIVE AND WELL". LINKAGE SECTION. 01 PARM1 PIC 99. 01 PARM2 PIC XX. 01 SUBPROGRAM-TABLE. 05 SUB-TABLE-ENTRY, PIC X OCCURS 10 TIMES INDEXED BY SUB-INDEX. 01 SAVE-SUB-INDEX PIC 999. PROCEDURE DIVISION USING PARM1, PARM2, SUBPROGRAM-TABLE, SAVE-SUB-INDEX. START-PROGRAM. SET SUB-INDEX TO SAVE-SUB-INDEX DISPLAY DATA-OUT DISPLAY "SAVE-SUB-INDEX = " SAVE-SUB-INDEX DISPLAY PARM1 DISPLAY PARM2 CALL "COBSUB2" OF SUB2 USING PARM1, PARM2 DISPLAY "I'M COBSUB1 AND I'M RETURNING TO MAIN NOW". Level 2 Subprogram (source $DATA.MYSUBVOL.SUB2SRC, object $DATA.MYSUBVOL.SUB2OBJ) IDENTIFICATION DIVISION. PROGRAM-ID. COBSUB2. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP System. OBJECT-COMPUTER. HP System. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 30 CALL Procedure Division Verbs CALL Example 9-8. Called Program That Calls Another Program (page 3 of 3) DATA DIVISION. WORKING-STORAGE SECTION. 77 DATA-MESSAGE PIC X(80) VALUE "I'M COBSUB2 ALIVE AND WELL". LINKAGE SECTION. 01 PARM1 PIC 99. 01 PARM2 PIC XX. PROCEDURE DIVISION USING PARM1, PARM2. START-PROGRAM. DISPLAY DATA-MESSAGE DISPLAY PARM1 DISPLAY PARM2 DISPLAY "I WILL NOW RETURN TO THE MAIN PGM VIA COBSUB1". For the programs in Example 9-8 to work properly, they must be compiled in this order: >COBOL85 /IN SUB2SRC, / SUB2OBJ >COBOL85 /IN SUB1SRC, / SUB1OBJ >COBOL85 /IN MAINSRC, / MAINOBJ If you want to eliminate the SPECIAL-NAMES paragraphs from the programs in Example 9-8, compile them, in the same order, with these additional directives: In COBSUB1: In COBOLMAIN: ?SEARCH SUBOBJ2 ?SEARCH SUBOBJ1 If COBSUB2 is a TNS program, and it must be recompiled for a reason that does not involve changes to the parameter list, you need not even recompile COBSUB1 or COBOLMAIN. You can simply rebind them, replacing the old version of MAINOBJ with the new one (see the Binder Manual). Output from running the programs in Example 9-8 as a single run unit looks like this: I'M THE MAIN AND I'M ALIVE SAVE-TABLE-INDEX = 005 I'M SUBCOB1 ALIVE AND WELL SAVE-SUB-INDEX = 005 10 AB I'M COBSUB2 ALIVE AND WELL 10 AB I WILL NOW RETURN TO THE MAIN PGM VIA COBSUB1 I'M COBSUB1 AND I'M RETURNING TO MAIN NOW PROGRAM END HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 31 Procedure Division Verbs CANCEL CANCEL CANCEL signals that you are done with a program that you called. On some computer systems, CANCEL releases memory used by a program that is no longer needed. On NonStop systems, CANCEL restores each specified program to its initial state (see Initial State). Nothing happens if a CANCEL statement specifies an initial program, a program that was not called, or a program that has already been cancelled. program-name CANCEL OF file-mnemonic IN identifier VST136.vsd program-name is a nonnumeric literal whose value is the program-name in the PROGRAM-ID paragraph of the COBOL program to be cancelled. file-mnemonic specifies the object file containing the program to be canceled. Associate filemnemonic with the operating system file name in the SPECIAL-NAMES paragraph of the Environment Division (see SPECIAL-NAMES Paragraph). identifier is an alphanumeric, nonnational data item whose value (which is not known until run time) is the program-name in the PROGRAM-ID paragraph of the COBOL program to be cancelled. Usage Considerations: • Internal Data Items Resume Their Initial Values Each internal data item (except those in the Linkage Section) is reset to the value that it had the first time the program was called. (CANCEL does not affect external data items.) • Internal File Connectors Are Implicitly Closed Each internal file connector whose open mode is neither closed nor locked is implicitly closed. The implicit close operation proceeds as if a CLOSE statement with no optional phrases were executed for each of the internal files. (CANCEL does not affect external file connectors.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 32 Procedure Division Verbs CANCEL If a called program that does not have the INITIAL attribute opens an internal file, the file remains open until either: • • ° ° ° The called program closes the file. The calling program cancels the called program. The process terminates. PERFORM Statements Resume Their Initial State (Inactive) GO TO Statements Modified by ALTER Statements Resume Their Initial Forms Each GO TO statement that was modified by an ALTER statement is restored to the form specified in the source program. • When Not to Use CANCEL ° On programs compiled with the NOCANCEL directive The NOCANCEL directive prevents the compiler from generating code that initializes the program the first time the program is called after being canceled by a CANCEL statement. ° On programs that are still executing, including the main program If you cancel the main program of the run unit or a called program that has not returned control to its calling program, the run unit terminates abnormally with a failure message. ° On routines written in languages other than COBOL and called with X/Open CALL statement Applying a CANCEL statement to a routine written in a language other than COBOL that was called with an X/Open CALL statement terminates the run unit. ° Within programs that are to run as process pairs If the primary process of a process pair executes a CANCEL statement, the backup process can become invalid. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 33 Procedure Division Verbs CHECKPOINT CHECKPOINT Note. • • Do not use this statement in the OSS environment. Before RVU D46.00 and G06.00, software product revision T8107AAT (run-time library T8108AAR), the NMCOBOL compiler ignores this directive and issues a warning. CHECKPOINT defines a restart point for the backup process of a process pair and transfers the information that the backup requires to restart. CHECKPOINT data-name-1 FILE data-name-2 file-name FILE QUEUE checkpoint-list-name VST137.vsd data-name-1 is the name of a data item to checkpoint, typically an item used for an I-O transfer of data that is relevant to the current state of the program and is needed if the backup process is to continue the operation in the event of a failure. FILE indicates that the next data item is the name or number of a file. data-name-2 is an integer, the operating system file number of the file whose sync block is to be checkpointed. Use data-name-2 only when files are managed entirely with ENTER statements that call TAL routines (rather than COBOL I-O statements). file-name is the name of a file (usually a disk file) whose sync block is to be checkpointed. QUEUE indicates that the next data item is the name of a checkpoint list. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 34 Procedure Division Verbs CHECKPOINT checkpoint-list-name is the name of a checkpoint list containing information that must be transferred to the backup process. The checkpoint list is a COBOL record with a specific structure in which the message changes are recorded. The information is returned by these Saved Message Utility (SMU) routines: ALTERPARAMTEXT DELETESTARTUP PUTPARAMTEXT DELETEASSIGN PUTASSIGNTEXT PUTSTARTUPTEXT DELETEPARAM PUTASSIGNVALUE For information on SMU routines and a description of the checkpoint list record, see Saved Message Utility (SMU) Overview. Usage Considerations: • Reason to Checkpoint If a backup process takes over, the contents of items that are not checkpointed are undefined. • Conditions Under Which Data Items Are Checkpointed ° COBOL85 compiler ° Working-Storage Section The COBOL85 compiler automatically checkpoints data items that are stored directly on the stack in 2 or fewer bytes (that is, if they are level 01 or 77, in the Working-Storage Section, and fewer than three characters long). ° Extended-Storage Section The COBOL85 compiler checkpoints data items in the Extended-Storage Section only if all of these conditions are true: ° ° ° The program runs in the CRE (see ENV). ° One or more CHECKPOINT statements explicitly specify the data items. The STARTBACKUP statement backs up the Extended-Storage Section (see STARTBACKUP). NMCOBOL compiler (RVU D46.00 and G06.00 or later, software product revision T8107AAT) The NMCOBOL compiler checkpoints only those data items that one or more CHECKPOINT statements specify explicitly. These data items can be in either the Working-Storage Section or the Extended-Storage Section. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 35 Procedure Division Verbs • CHECKPOINT Sending Values to a Backup Process When CHECKPOINT executes, the values of the data items and file sync blocks are sent to the fault-tolerant facility in the backup process. If the primary process fails before another checkpoint is made, the backup begins processing from the current checkpoint. The set of values specified in any checkpoint must be sufficient for the backup process to continue processing correctly with only that information. After the CHECKPOINT statement transfers the information in the checkpoint list to the backup process, it resets the checkpoint list to empty and its storage space is available to record further message changes. • Multiple Checkpoints for a Transaction Use multiple checkpoints for a transaction if the number of WRITE statements executed for a file exceeds the value of the sync depth with which the file was opened. If a file was opened with sync depth n, use at least one CHECKPOINT for every n WRITE statements executed for a file. • CHECKPOINT for Process Pairs When a requester that is running as a process pair sends a message, and the backup process takes over before the requester receives a reply, the server can resend the reply automatically—if a CHECKPOINT statement executes after the server reads the requester’s message but before the server writes a reply (or generates one automatically with another READ). When this happens, the server does not see the duplicate message. The CHECKPOINT statement can execute even if the server is not running as a process pair. • A Process Pair Cannot Update an SQL/MP or SQL/MX Database An HP COBOL program that runs as a process pair cannot update an SQL/MP or SQL/MX database. Note. A COBOL program must not modify the contents of a checkpoint list directly. The execution logic of the routines and the CHECKPOINT statement maintain checkpoint lists without the need for any other program action. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 36 Procedure Division Verbs CLOSE CLOSE CLOSE terminates processing of one or more open files or reels of tape. An optional LOCK phrase prevents the program from reopening the file (unless the file is dynamically assignable—see #DYNAMIC). If a file is closed but not locked, the only I-O operation the process can perform on that file is an open operation. If the file is closed and locked, the process cannot perform any I-O operation on the file. CLOSE has these formats: • • CLOSE for Sequential and Line Sequential Files CLOSE for Relative, Indexed, and Queue Files CLOSE for Sequential and Line Sequential Files Throughout this topic, “sequential file” means both sequential and line sequential files unless otherwise noted. CLOSE file-name file-info VST138.vsd file-name is the name of the sequential file to be closed. When more than one file-name appears, the files can have different organization and access modes and the optional phrases following one filename are independent of those following any other file-name. file-info UNIT REEL FOR NO WITH REMOVAL REWIND LOCK VST139.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 37 Procedure Division Verbs CLOSE for Sequential and Line Sequential Files UNIT REEL specify that the current reel is to be closed and rewound, and a new reel is to be mounted. REMOVAL specifies that the reel of a multiple-reel tape file be rewound and unloaded, and a new reel is to be mounted. NO REWIND specifies that the sequential file is to be left in its current position, not rewound. LOCK means the file associated with file-name cannot be opened again during the current run. If the file is dynamically assignable, the LOCK phrase has no effect (see #DYNAMIC). Usage Considerations: • Effects of CLOSE For each file-name in the CLOSE statement, the run-time routines perform an appropriate close operation. These close operations occur as if separate CLOSE statements were executed for each file-name in the order listed. Subsequent usage considerations describe actions taken during the close operation for one file. • File-Status Data Item If the file being closed has an associated file-status data item, the CLOSE statement assigns it an appropriate I-O status code. The possible I-O status codes and their meanings are: I-O Status Code Meaning “00” The close operation completed successfully. “07” The close operation completed successfully, but the CLOSE statement included a NO REWIND, REEL, UNIT, or REMOVAL phrase and the designated file does not reside on a reel or unit medium. “30” The close operation failed due to causes outside of COBOL. The file is not closed. If the operation was a reel close, the reel might not have been closed properly. “42” The program attempted to close a file that was not open. Failure of a close operation can terminate the run unit. When a run unit terminates for any reason (normal or abnormal), the run-time routines implicitly close any open files as if they were specified in a CLOSE statement without optional phrases. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 38 Procedure Division Verbs • CLOSE for Sequential and Line Sequential Files Closing Single-Tape and Multiple-Tape Files See Table 9-1. • Closing a File Open Under More Than One Name If a program has one operating system file open under more than one file name, closing one file name does not affect the availability of the operating system file through any other file name, except when the LOCK phrase is present. The LOCK phrase applies to all file names that the program has assigned to the operating system file except those assigned dynamically with the COBOLASSIGN, COBOL_ASSIGN_, or COBOL_ASSIGN_OSS_ routine. Table 9-1. CLOSE Statements for Sequential Tape File CLOSE Statement Single Reel Multiple Reel CLOSE See note 5 See notes 1 & 5 CLOSE NO REWIND See note 2 See notes 1 & 2 CLOSE LOCK See note 3 See notes 1 & 3 CLOSE REEL See note * See notes 4 & 5 CLOSE REEL FOR REMOVAL See note * See notes 3, 4, & 5 CLOSE REEL NO REWIND See note * See notes 2 & 4 1. OTHER REELS UNAFFECTED If more reels remain in the file, they are not processed. 2. NO REWIND The reel is left in its current position. 3. REEL REMOVAL The current reel is rewound and unloaded. 4. REEL SWAP When proceeding to the next reel in a multiple-reel set, a message is written to the home terminal and a read is done. If the reply is a carriage return, the new reel is assumed to be on the same device; otherwise, the reply must be a device name that has the next reel in the set. 5. REEL REWOUND The reel is rewound. * If the program issues a CLOSE REEL of any form for a file that is open for INPUT, and the operator limits the file to the current reel by responding “NO” to the reel swap prompt, the at-end condition occurs for that file. When an operator responds “NO” for a file that is open for other than INPUT, the run-time routine rejects the “NO” answer. • Closing Blocked Files The close operation RVUs an incomplete block to the file if all of these conditions are true: ° The file is declared with a BLOCK CONTAINS clause specifying more than one record for each block. ° ° The current block contains at least one record but is not yet filled. The file’s open mode is OUTPUT or EXTEND. If this RVU causes a boundary violation exception condition, the results are: HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 39 Procedure Division Verbs • CLOSE for Relative, Indexed, and Queue Files ° ° The block is not transmitted to the file. ° ° Any applicable USE procedure executes. The close operation terminates immediately, setting any file-status variable associated with the file to 34 (for a sequential file) or 24 (for a relative or indexed file). The file is not closed. COBOL and FUP Closing Procedures Are Incompatible (Multiple-Tape File) When the run-time routine closes a nonfinal reel of a multiple-tape file, it writes an end-of-file mark, a trash record, and an end-of-file mark. When the File Utility Program (FUP) closes a multiple-reel tape file, it writes only the two consecutive end-of-file marks. Because these closing procedures differ, you must not use FUP to copy tapes written by and for COBOL programs. Instead, write a simple COBOL program to copy such tapes. • Process Pairs When the run unit is executing as a process pair, the execution of a CLOSE filename also executes an implied statement of this form: CHECKPOINT FILE file-name • Repositioning a Sequential File to Its Beginning Although you can reposition a sequential file to its beginning by closing it and reopening it, you can do it faster with the routine COBOL85^REWIND^SEQUENTIAL or COBOL_REWIND_SEQUENTIAL_. For information on these routines, see COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_. CLOSE for Relative, Indexed, and Queue Files CLOSE file-name WITH LOCK VST140.vsd file-name is the name of the relative,indexed, or queue file to be closed. When more than one file-name appears, the files can have different organization and access modes and the optional phrases following one filename are independent of those following any other file-name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 40 Procedure Division Verbs COMPUTE LOCK means the file associated with file-name cannot be opened again during the current run. If the file is dynamically assignable, the LOCK phrase has no effect (see #DYNAMIC). See these usage considerations in CLOSE for Sequential and Line Sequential Files: • • • • • Effects of CLOSE File-Status Data Item Closing a File Open Under More Than One Name Closing Blocked Files Process Pairs COMPUTE COMPUTE evaluates an arithmetic expression and stores the result in the specified data item or items. COMPUTE result ROUNDED = expression SIZE ERROR imp-stmt-1 ON NOT SIZE ERROR imp-stmt-2 ON END-COMPUTE VST141.vsd result is the identifier of a numeric elementary item or numeric edited elementary item where the result of the computation is to be stored. ROUNDED specifies that the value is rounded before being stored. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 41 Procedure Division Verbs COMPUTE expression is an arithmetic expression. imp-stmt-1 is an imperative statement to be executed when a size error has been detected in the computation or in storing the result. imp-stmt-2 is an imperative statement to be executed when no size error is detected in the computation or in storing the result. END-COMPUTE ends the scope of the COMPUTE statement, causing the COMPUTE to be a delimited-scope statement. If the COMPUTE statement does not end with an ENDCOMPUTE phrase, the presence of the SIZE ERROR or the NOT SIZE ERROR phrase causes the COMPUTE statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • • • See Arithmetic Operations for information on data conversion and alignment, intermediate results, multiple results, and incompatible data. See Arithmetic Precision for information on precision of addition. See ROUNDED Phrase and SIZE ERROR Phrase for information on these phrases. For Example 9-9 and Example 9-10, these descriptions are in the Working-Storage Section of a program: Example 9-9. COMPUTE Statement (page 1 of 2) WORKING-STORAGE SECTION. 01 COMPUTE-RESULT PIC 01 DIAGNOSTIC-FIELD PIC 01 WS-RESULT PIC 01 WS-99 PIC 01 WS-FIVE-ONES PIC 01 EXPONENT PIC 01 A PIC 01 B PIC 01 C PIC 01 U PIC 01 X PIC 999 VALUE X(35). S9(9) VALUE S99 VALUE S9(5) VALUE 9(5) VALUE 9(4)V99. 9(4)V99 VALUE 9(4)V99 VALUE 9(4)V99 VALUE 9V99. ZEROS. ZEROS. 99. 11111. ZERO COMP. 8. 5. 7. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 42 Procedure Division Verbs COMPUTE Example 9-9. COMPUTE Statement (page 2 of 2) This statement specifies that the result be stored in COMPUTE-RESULT without being rounded: COMPUTE COMPUTE-RESULT = (((24.0 + 1) * (60 - 10)) / 125) ** 2 END-COMPUTE (The result is 100.) This COMPUTE statement specifies that the result be rounded and then stored in WSRESULT: MOVE 2 TO EXPONENT COMPUTE WS-RESULT ROUNDED = WS-99 / 10 * WS-99 ** EXPONENT + WS-FIVE-ONES END-COMPUTE (The result is 108,141.) Example 9-10. Combination of IF and COMPUTE Statements IF A > 0 COMPUTE X = B ** 2 - ( 4 * A * C ) / ( 2 * A) ON SIZE ERROR MOVE "DIVISION ERROR" TO DIAGNOSTIC-FIELD END-COMPUTE ELSE MOVE "DIVISION BY ZERO" TO DIAGNOSTIC-FIELD END-IF. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 43 Procedure Division Verbs CONTINUE CONTINUE CONTINUE is a no-operation statement. CONTINUE VST142.vsd Example 9-11. CONTINUE Statement IF SALARIED IF ANNUAL-SAL > 50000 IF BELOW-QUOTA CONTINUE ELSE PERFORM ADD-BONUS-TO-OVERPAID-SALESPERSON END-IF ELSE IF BELOW-QUOTA CONTINUE ELSE PERFORM ADD-BONUS-TO-FLUNKY END-IF ELSE IF OVERTIME ... Usage Considerations: • Effect of CONTINUE A CONTINUE statement has no effect on the execution of the program. • Where CONTINUE Can Appear The CONTINUE statement can appear anywhere a conditional statement or an imperative statement can appear. The normal use is as an unused branch of an IF statement. COPY COPY summons source text from a file set up as a COPY library. You can use COPY in any division. For more information, see COPY Statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 44 Procedure Division Verbs DELETE DELETE DELETE removes a record from a relative or indexed file that is open in I-O mode. DELETE file-name RECORD imperative-stmt-1 INVALID KEY NOT imperative-stmt-2 INVALID KEY END-DELETE VST143.vsd file-name is the name of a relative or indexed file that is open in I-O mode. imperative-stmt-1 is an imperative statement to be executed when the invalid-key condition arises during the delete operation. It is required for a file whose access mode is random or dynamic (but prohibited for a file whose access mode is sequential) when there is no USE procedure that applies to the file. imperative-stmt-2 is an imperative statement to be executed (after a declarative procedure) when no exception or an exception other than the invalid-key condition arises during the delete operation. END-DELETE ends the scope of the DELETE statement and makes it a delimited-scope statement. If you omit END-DELETE but include the INVALID KEY or NOT INVALID KEY phrase, the DELETE statement is a conditional statement and ends at the next period separator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 45 Procedure Division Verbs DELETE Usage Considerations: • I-O Status Codes If the file being closed has an associated file-status data item, the DELETE statement assigns it an appropriate I-O status code. The possible I-O status codes and their meanings are: I-O Status Code Meaning “00” The delete operation was successful. “23” The designated record does not exist. “30” The delete operation failed due to causes outside of COBOL. The specified record might or might not have been deleted. The file position indicator might be undefined. “43” The delete operation failed because the last input-output statement executed for the file (which is in the sequential access mode) was not a successfully executed READ statement. “49” The file was not open in the I-O mode or was not opened by an HP COBOL program. When the deletion is successful or the invalid-key condition occurs, these items are not affected: • ° ° Record area ° ° Key of reference Data item specified in the DEPENDING phrase of the RECORD clause, specifying the length of the record File position indicator Record Deleted When File Access Mode is Sequential If the file’s access mode is sequential and the last operation performed on the file was a successful READ statement, then DELETE logically removes from the file the record that the READ statement retrieved. If the last operation performed on the file was not a successful READ statement, DELETE terminates with I-O status code “43.” In a Pathway environment under the NonStop Transaction Management Facility (TMF), the last operation on the file must have been a successful execution of a READ LOCK statement (rather than a READ statement). For information on coding servers, see the Pathway/TS SCREEN COBOL Reference Manual for your system. The record retrieved by the READ statement is deleted. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 46 Procedure Division Verbs • DISPLAY Record Deleted When File Access Mode is Random or Dynamic If the file’s access mode is random or dynamic, the record to be deleted is defined by the record key, or, for relative files, the relative key (indexed or prime key). If the designated record does not exist, an invalid-key condition occurs with I-O status code “23.” Example 9-12. DELETE Statement INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT EMPLOYEE-MASTER ASSIGN TO "EMPMAST" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS EMPLOYEE-NUMBER FILE STATUS IS FILE-STAT. ... FD EMPLOYEE-MASTER LABEL RECORDS ARE OMITTED ... 05 EMPLOYEE-NUMBER PIC X(7). ... PROCEDURE DIVISION. ... DELETE-RECORD. MOVE KEY-TO-DELETE TO EMPLOYEE-NUMBER DELETE EMPLOYEE-MASTER RECORD INVALID KEY PERFORM KEY-ERROR END-DELETE DISPLAY DISPLAY delivers a small amount of data (such as an error message) to a terminal, a printer, or another process. DISPLAY identifier literal UPON mnemonic-name NO ADVANCING WITH VST144.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 47 Procedure Division Verbs DISPLAY identifier is the identifier of any data item except an index data item. literal is a literal or figurative constant name. mnemonic-name is the device on which the process displays the data. You must define mnemonicname in the SPECIAL-NAMES paragraph of the Environment Division. When you omit mnemonic-name, the process delivers the data to its output file, typically its home terminal. NO ADVANCING specifies that the device to which the display is directed is not reset to the next line after the data is displayed. The DISPLAY statement in Example 9-3 delivers an error message to the output file of a process. Example 9-13. DISPLAY Statement IF IO-STATUS = "23" DISPLAY "I-O ERROR " IO-STATUS " - NO RECORD FOR KEY = " INVOICE-NUMBER END-IF If INVOICE-NUMBER is 00246, the output from the code in Example 9-3 looks like this: I-O ERROR 23 - NO RECORD FOR KEY = 00246 Usage Considerations: • Differences in the OSS and Guardian Environments In the OSS environment (but not in the Guardian environment), if a DISPLAY statement includes mnemonic-name, it must be either the OSS pathname of a Guardian file or the name of an OSS text file. • Devices The devices to which the DISPLAY statement can transmit data are terminals (including the operator’s console), printers, processes (including spooler collectors), and entry-sequences files. Once the DISPLAY device is assigned, the program cannot change it. The WRITE statement is recommended for all but the smallest amounts of data. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 48 Procedure Division Verbs • DISPLAY Specifying the Wrong Device If you specify a device that cannot be used for DISPLAY output, the process displays a run-time error message and the output on its home terminal. The error message includes this line: Device assigned to ACCEPT or DISPLAY not a legal device • Opening and Closing Devices The display operation opens and closes the terminal or printer (but not a process) for each DISPLAY statement. This prevents a COBOL program from locking out other users between displays. Because a process is not prevented from accepting requests from other run units, COBOL does not close a process after each display operation; instead, it waits until execution of the run unit terminates. • How Different Types of Values Are Displayed ° Numeric values A numeric value is displayed as a numeric literal, preceded by a minus sign if the value is negative, and with a decimal point before any fractional digits. The number of digits displayed is the number of digits defined for the sending item. A function that returns a floating-point value (such as NUMVAL or NUMVAL-C) is displayed as if the value were described as PICTURE S9(18), with no decimal positions. For this reason, do not reference such functions in DISPLAY statements. Instead, move the values that such functions return to temporary variables that have decimal points in the appropriate positions and display the temporary variables. ° Nonnumeric values A nonnumeric value is displayed as a string of characters. ° Figurative constant values A figurative constant is displayed as a single occurrence of the constant value (even if the figurative constant includes the prefix ALL). ° Multiple values When you specify more than one value in a DISPLAY statement, DISPLAY combines the values (in the order you specify them) into a single characterstring and displays the character-string. The size of the displayed item is the sum of the sizes of all the values. If the character-string exceeds the line capacity of the device, DISPLAY displays the data as a sequence of lines. Every line except (perhaps) the last one contains its maximum number of characters. The last line contains whatever characters are left, up to the maximum. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 49 Procedure Division Verbs • DIVIDE Displaying Records and Large Amounts of Data Use the WRITE statement to display records and character-strings longer than several lines. The DISPLAY statement is not designed to deliver logical records or large amounts of data to a device. • NO ADVANCING Phrase If you include the NO ADVANCING phrase, the device is not changed after it displays the final operand (for example, the device is not repositioned to the next line). If the device is a printer or a spooler process, this causes the next line displayed to overprint the current line (useful for underlining). If the device is a terminal, the cursor appears after the last character displayed (useful for issuing a prompt and accepting the response on the same line). DIVIDE Form Topic DIVIDE a INTO b DIVIDE INTO DIVIDE a INTO b GIVING c DIVIDE b BY a GIVING c DIVIDE GIVING DIVIDE a INTO b GIVING c REMAINDER d DIVIDE b BY a GIVING c REMAINDER d DIVIDE GIVING REMAINDER HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 50 Procedure Division Verbs DIVIDE INTO DIVIDE INTO DIVIDE INTO divides one data item into one or more other data items and stores the quotient(s) in the respective dividend data item(s). DIVIDE divisor INTO dividend ROUNDED SIZE ERROR imperative-stmt-1 ON SIZE NOT ERROR ON imperative-stmt-2 END-DIVIDE VST145.vsd divisor is the identifier of the elementary numeric data item or numeric literal that is the divisor. dividend is the identifier of an elementary numeric data item that is both the dividend and the receiver of the quotient. ROUNDED specifies that quotient is to be rounded before being stored. imperative-stmt-1 is an imperative statement for the process to execute if it detects a size error in the division or in storing the result. imperative-stmt-2 is an imperative statement for the process to execute if it does not detect a size error in the division or in storing the result. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 51 Procedure Division Verbs DIVIDE INTO END-DIVIDE ends the scope of the DIVIDE statement and makes it a delimited-scope statement. If you omit END-DIVIDE but include the SIZE ERROR or NOT SIZE ERROR phrase, the DIVIDE statement is a conditional statement and ends at the next period separator. Usage Considerations: • Mathematics The statement DIVIDE A INTO B means store B /A in B. • Precision For information on the precision of HP COBOL division, see Arithmetic Precision. • Order of Evaluation The value of divisor is copied into a temporary data item for computation. The value of each dividend is divided by the value of the temporary data item and the value of the result is stored (after rounding, if specified) into dividend. If the same data name occurs more than once in the list of dividends, the final value of the item reflects multiple divisions by the value of divisor. Each time the result is stored in a dividend, the process of operand identification (including subscript evaluation and reference modification) occurs just before the storage operation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 52 Procedure Division Verbs DIVIDE GIVING DIVIDE GIVING DIVIDE GIVING divides one data item into another data item and stores the quotient in one or more data items. divisor DIVIDE INTO dividend BY dividend GIVING divisor quotient ROUNDED SIZE ERROR imperative-stmt-1 ON NOT SIZE ERROR ON imperative-stmt-2 END-DIVIDE VST146.vsd divisor is the identifier of the elementary numeric data item or numeric literal that is the divisor. dividend is the identifier of an elementary numeric data item that is the dividend. quotient is the identifier of the elementary numeric item or elementary numeric edited data item in which the quotient is to be stored. ROUNDED specifies that quotient is to be rounded before being stored. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 53 Procedure Division Verbs DIVIDE GIVING imperative-stmt-1 is an imperative statement for the process to execute if it detects a size error in the division or in storing the result. imperative-stmt-2 is an imperative statement for the process to execute if it does not detect a size error in the division or in storing the result. END-DIVIDE ends the scope of the DIVIDE statement and makes it a delimited-scope statement. If you omit END-DIVIDE but include the SIZE ERROR or NOT SIZE ERROR phrase, the DIVIDE statement is a conditional statement and ends at the next period separator. Usage Considerations: • Mathematics The statement DIVIDE A INTO B GIVING C means store B /A in C. The statement DIVIDE A BY B GIVING C means store A /B into C. • Precision For information on the precision of HP COBOL division, see Arithmetic Precision. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 54 Procedure Division Verbs DIVIDE GIVING REMAINDER DIVIDE GIVING REMAINDER DIVIDE GIVING REMAINDER divides one data item into another data item and stores the quotient and remainder in specified data items. DIVIDE divisor INTO dividend BY dividend GIVING divisor quotient ROUNDED remainder REMAINDER SIZE ERROR imperative-stmt-1 ON SIZE NOT ERROR ON imperative-stmt-2 END-DIVIDE VST147.vsd divisor is the identifier of the elementary numeric data item or numeric literal that is the divisor. dividend is the identifier of an elementary numeric data item that is the dividend. quotient is the identifier of the elementary numeric item or elementary numeric edited data item in which the quotient is to be stored. ROUNDED specifies that quotient is to be rounded before being stored. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 55 Procedure Division Verbs DIVIDE GIVING REMAINDER remainder is the identifier of an elementary numeric or elementary numeric edited data item where the remainder is stored. imperative-stmt-1 is an imperative statement for the process to execute if it detects a size error in the division or in storing the result. imperative-stmt-2 is an imperative statement for the process to execute if it does not detect a size error in the division or in storing the result. END-DIVIDE ends the scope of the DIVIDE statement and makes it a delimited-scope statement. If you omit END-DIVIDE but include the SIZE ERROR or NOT SIZE ERROR phrase, the DIVIDE statement is a conditional statement and ends at the next period separator. Usage Considerations: • Mathematics The statement DIVIDE A INTO B GIVING C REMAINDER D means store the quotient portion of the value of B /A in C and store the remainder in D. The statement DIVIDE A BY B GIVING C REMAINDER D means store the quotient portion of the value of A /B in C, and store the remainder in D. • Precision For a discussion of the precision of HP COBOL division, see Arithmetic Precision. • Remainder HP COBOL computes the remainder by performing the division with a signed quotient having the same number of decimal places as the quotient. For example, dividing 2 into -5 yields a remainder of -1. This differs from COBOL, in which the intermediate value has the same sign as the quotient. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 56 Procedure Division Verbs DIVIDE GIVING REMAINDER Example 9-14. DIVIDE INTO Statement With GIVING and REMAINDER Phrases WORKING-STORAGE SECTION. 01 ARITHMETIC-WORK-SPACE. 03 LEAP-YEAR PIC 9 VALUE ZERO. 03 DIVIDE-RESULT PIC 99 VALUE ZERO. ... 01 INVOICE-DATE. 05 INV-MONTH PIC 99. 05 INV-DAY PIC 99. 05 INV-YEAR PIC 9999. ... PROCEDURE DIVISION. ... DIVIDE 4 INTO INV-YEAR GIVING DIVIDE-RESULT REMAINDER LEAP-YEAR END-DIVIDE ... Example 9-15. DIVIDE BY Statement With GIVING and REMAINDER Phrases WORKING-STORAGE SECTION. 01 ARITHMETIC-WORK-SPACE. 03 LEAP-YEAR PIC 9 VALUE ZERO. 03 DIVIDE-RESULT PIC 99 VALUE ZERO. ... 01 INVOICE-DATE. 05 INV-MONTH PIC 99. 05 INV-DAY PIC 99. 05 INV-YEAR PIC 9999. ... PROCEDURE DIVISION. ... DIVIDE INV-YEAR BY 4 GIVING DIVIDE-RESULT REMAINDER LEAP-YEAR END-DIVIDE ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 57 Procedure Division Verbs ENTER ENTER ENTER calls a routine written in a language other than COBOL. (To call a COBOL routine, use CALL.) Note. If you use the ENTER statement in the OSS environment, see Mixed-Language Programs. In some implementations of COBOL, ENTER marks the beginning of an embedded routine in some other language. In HP COBOL, ENTER is analogous to CALL but is used to call a non-COBOL routine. An HP COBOL program’s mode and operating environment determine what types of non-COBOL routines it can call. A called routine can have an ordinary, VARIABLE, or EXTENSIBLE parameter list. ENTER routine-name language file-mnemonic OF IN parameter USING OMITTED GIVING return-value VST148.vsd language Compiler Environment language COBOL85 Guardian C, TAL, FORTRAN, or Pascal OSS C or TAL NMCOBOL Unnecessary, because the compiler can determine the language of the called program, but if specified, language must be HP C or TAL. If language is TAL, the compiler expects a pTAL program. The compiler does not accept TAL programs. The COBOL85 compiler reports an error if the called routine was not written in the specified language, except when the specified language is C and the routine was written in C++, which the COBOL85 compiler handles as if it were C. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 58 Procedure Division Verbs ENTER For the COBOL85 compiler, the absence or value of language determines these things: ° ° The protocol used to pass string parameters The language in which the called routine must have been written For the COBOL85 compiler: ° If language is absent, FORTRAN protocol is used to pass string parameters and the called routines must have been written in TAL. Omit language when calling TAL routines that can be called by either COBOL or FORTRAN, such as Saved Message Utility (SMU) routines. ° If language is present, the protocol of the language specified is used to pass string parameters and the called routine must have been written in the same language. routine-name is either the actual name of the called routine or it is a nonnumeric literal whose value is the name of the called routine. If routine-name is a nonnumeric literal or a COBOL reserved word, or if it contains a caret (^) or underscore (_), it must be enclosed in quotation marks. If routine-name is not enclosed in quotation marks, the compiler handles it as the actual name of the routine. Quotation marks are recommended. If routine-name specifies an C or C++ function whose name includes lowercase letters, the call fails, because the compiler automatically converts all names to uppercase. file-mnemonic specifies the object file containing the called routine’s code and data blocks, enabling the BIND process or nld or ld utility to find the routine during preparation of the run unit. For the NMCOBOL compiler, file-mnemonic must specify either: • • A linkfile An archive file Establish the association between file-mnemonic and the operating system file name in the SPECIAL-NAMES paragraph of the Environment Division. The file-mnemonic phrase is not part of the routine-name. You cannot use the phrase to make the routine-name unique. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 59 Procedure Division Verbs ENTER parameter data-name literal ( arithmetic-expression ) file-name VST149.vsd is a value to be passed to the called routine. data-name can be qualified, subscripted, and include a reference modifier. If data-name is a TAL or pTAL string:length parameter, you can set its length with a reference modifier (see Restrictions on Calling TAL or pTAL Routines). literal is a numeric literal whose value corresponds to a value parameter in the routine being called. arithmetic-expression is an arithmetic expression whose value corresponds to a value parameter in the routine being called. file-name is the file description name of a file. OMITTED must be specified in place of any omitted parameter surrounded by other parameters (because parameters are recognized by their order). OMITTED is only permitted when the called routine has the VARIABLE or the EXTENSIBLE attribute. return-value is a numeric or numeric edited elementary data item where the return value is stored when the called routine is a function. The return-value can be a 2-byte, 4-byte, or 8-byte integer or a 4-byte or 8-byte floating-point value (in TAL terms: INT, INT(32), FIXED, REAL, or REAL(64)). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 60 Procedure Division Verbs ENTER Usage Considerations: • language If you call a routine with a particular value of language (or with language omitted), you must use the same value of language each time you call that routine in the same compilation unit. • file-mnemonic If you specify file-mnemonic but the compiler does not find the called routine in the associated object file, the compiler reports an error. For information on resolving external references, see Finding the Entered Program. • USING Phrase The number and type of the parameters in the USING phrase must be compatible with the expectations of the called routine. The called routine might interpret the parameters slightly differently than the calling program does (see Appendix B, Data Type Correspondence). • GIVING Phrase When calling a function (a routine that returns a value), include a GIVING phrase in the ENTER statement. When control returns to the COBOL program, the value that the function returns is assigned to return-value. Scaling of the function’s value (if needed) is performed before the value is assigned to return-value. If the function’s value is larger than the maximum value allowed for a COBOL identifier, the COBOL program terminates with an arithmetic overflow condition during the conversion process. The assignment operation follows MOVE conventions (see MOVE TO). • Passing Parameters by Value When a formal parameter (in the called routine) is to be passed by value, the actual parameter (in the ENTER statement) must be a numeric literal, a numeric data item, a special register, an arithmetic expression, or the word OMITTED. If the parameter is not OMITTED, it is evaluated, scaled, and converted to the storage size and type of the formal parameter. The resulting value is passed to the called routine. This conversion might cause an arithmetic overflow. • Passing Parameters by Reference When a formal parameter (in the called routine) is to be passed by reference, the actual parameter (in the ENTER statement) must be a data item or, in some routines supplied by HP, a file name. If the actual parameter is a data item, the compiler generates code to pass the address of the data item’s storage space to the called routine. The calling program and the called routine must interpret the value of the data item the same way. If the actual parameter is a file name, the compiler generates code to pass the address of the COBOL file control block to the called routine. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 61 Procedure Division Verbs • ENTER Addressing Parameters All native instructions use 32-bit addressing. Some TNS instructions use 16-bit addressing and others use 32-bit addressing. Those that use 16-bit addressing execute faster, but cannot address data items in extended memory. The code in an called routine that handles parameters specified in the calling program is generated according to the addressing mode of the data descriptions in the called routine. Many COBOL data items are byte-addressed. Some data items in other languages are 2-byte-addressed. This means different things in a TNS program and in native program. In a TNS program, when you pass a byte-addressed parameter to a routine that expects a 2-byte-addressed parameter, the compiler shifts the byte address to the right to produce a 2-byte address. The data item must begin in the leftmost byte; otherwise, problems can arise. The compiler issues a warning if there is any possibility of this happening (because the offset within the record is odd, the data item is a table with odd element size, or the data item is within a table). In a native program, when you pass a byte-addressed parameter to a routine that expects a 2-byte-addressed parameter, the data item must be aligned on a 2-byte boundary; otherwise, problems can arise, because the called routine is expecting an aligned parameter. The compiler does not issue a warning in this case. ° TNS HP COBOL TNS HP COBOL programs use 16-bit addressing for all items in the File Section and the Working-Storage Section. They use 32-bit addressing for all data items in the Extended-Storage section and all data items in the Linkage Section that are not described as having STANDARD access mode. Any TNS HP COBOL data item except a special register or a data item declared in the Extended-Storage Section can correspond to a 16-bitaddressed reference parameter of the called routine. Any TNS HP COBOL data item except a special register can correspond to a 32-bit-addressed reference parameter of the called routine. ° FORTRAN (TNS only) Each FORTRAN routine uses the same addressing mode for all parameters it receives or passes—16-bit addressing by default, 32-bit addressing if the routine is compiled with the EXTENDEDREF or LARGECOMMON directive. (The LARGECOMMON directive also causes common blocks to be allocated in extended memory.) All FORTRAN routines bound into one object file must use the same addressing mode. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 62 Procedure Division Verbs ° ENTER Pascal (TNS only) Each Pascal module uses the same addressing mode for all parameters and pointers it receives or passes—16-bit addressing and 16-bit pointer allocation by default, 32-bit addressing and 32-bit pointer allocation if the routine is compiled with the XMEM directive. (16-bit addressing is called the “smallmemory model” and 32-bit addressing is called the “large-memory model.”) All Pascal modules bound into one object file must use the same addressing mode. ° pTAL In pTAL modules, each data item declaration (including parameter declarations) specifies either 1-byte or 2-byte addressing. All declarations use 32-bit addressing. ° TNS C and C++ Each HP C or HP C++ module uses the same addressing mode for all parameters and pointers it receives or passes—32-bit addressing and 32-bit pointer allocation by default, 16-bit addressing and 16-bit pointer allocation if the module is compiled with the NOXMEM pragma. All modules bound into one object file must use the same addressing mode. HP recommends using 32-bit addressing mode for HP C and HP C++ pointers. ° Native C and C++ In native HP C and HP C++ modules, all data item declarations (including parameter declarations) use 32-bit addressing. ° TAL In TAL programs, each data item declaration (including parameter declarations) specifies either 16-bit or 32-bit addressing. • Restrictions on Calling HP C and HP C++ Functions An HP COBOL program cannot call an HP C or HP C++ function for which any of these conditions are true: ° ° ° ° The function name includes lowercase letters. The function prototype specifies a variable number of parameters. The function returns a structured value. The function specifies a formal parameter whose type has no corresponding COBOL type (see Appendix B, Data Type Correspondence). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 63 Procedure Division Verbs ENTER In the non-CRE environment (but not the CRE), an HP COBOL program cannot call an HP C or HP C++ function for which any of these conditions are true: ° ° ° The function directly or indirectly allocates or deallocates controlled storage. The function performs HP C or HP C++ input-output operations. The function directly or indirectly accesses the HP C function getenv. Do not include the GIVING phrase in an ENTER statement that accesses an HP C or HP C++ function whose type is a pointer or whose type designation includes the modifier “unsigned.” The type “char” is included in this prohibition, because the HP C compiler and the HP C++ compiler interpret it as the type “unsigned char.” The type “signed char” is acceptable. When the formal parameter for an HP C or HP C++ function is a scalar variable, its type designation cannot include the modifier “unsigned.” The type “char” is include in this prohibition, because the HP C and HP C++ compilers interpret it as the type “unsigned char.” The type “signed char” is acceptable. Because the names of HP C++ routines are often modified to reflect their classes and argument types, it is recommended that HP COBOL programs call only regular HP C++ functions, not constructs that are peculiar to HP C++ (such as member functions and templates). • Restrictions on Calling FORTRAN Routines Do not pass literals or expressions to FORTRAN routines. The FORTRAN language has no way to specify that it expects to receive a parameter by value (all parameters are passed to FORTRAN routines by reference). If a program includes both HP COBOL and FORTRAN routines, these restrictions apply to input-output operations: • ° All input-output operations done on a particular file must be performed within one language or by routines provided by HP. ° In the non-CRE environment (but not the CRE), an HP COBOL routine must handle process termination. If execution terminates in FORTRAN code, the run-time routines do not have a chance to complete any possible pending input-output operations and lines of printer or terminal output are likely to be lost. ° In the CRE, the HP COBOL and FORTRAN routines can share IN, OUT, and $RECEIVE files. Restrictions on Calling Pascal Routines In the non-CRE environment (but not in the CRE), an HP COBOL program cannot call a Pascal routine that directly or indirectly allocates or deallocates controlled storage or performs Pascal input-output operations. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 64 Procedure Division Verbs • ENTER Restrictions on Calling TAL or pTAL Routines If your HP COBOL program calls a TAL or pTAL routine that has a string:length parameter, you only need to give the name of the corresponding actual parameter, because the compiler can determine its length. If a TAL or pTAL routine that has a string:length parameter does not ignore trailing spaces and you want to pass it an actual parameter that is shorter than the one defined for the corresponding formal parameter, use reference modification. The HP COBOL code in Example 9-16 calls the pTAL routine FILENAME_COMPARE_, which does not ignore trailing spaces and has two formal parameters, filename1:length1 and filename2:length2. Example 9-16. Calling a pTAL Routine That Does Not Ignore Trailing Spaces 01 file-name-1 PIC X(255). 01 file-name-2 PIC X(255). 01 len-1 PIC 999 COMP. 01 len-2 PIC 999 COMP. ... MOVE 0 TO len-1, len-2 INSPECT file-name-1 TALLYING len-1 FOR CHARACTERS BEFORE SPACE INSPECT file-name-2 TALLYING len-2 FOR CHARACTERS BEFORE SPACE ENTER "FILENAME_COMPARE_" USING file-name-1 (1: len-1) file-name-2 (1: len-2) GIVING ... If a TAL routine expects FORTRAN CHARACTER parameters (as the SMU routines do), omit language when calling the routine. If you specify the language TAL, differences in the TAL and FORTRAN parameter-passing protocols will cause trouble. The TAL parameter-passing protocol (which applies to all ordinary TAL routines including operating system externals) is to push parameter addresses onto the data stack and then call the routine. The FORTRAN parameter-passing protocol is to push the length of each CHARACTER parameter onto the data stack followed by its address. This allows the called routine to retrieve the parameter’s length. If the called routine expects lengths on the stack and they are not there, the called routine does not work as intended. In Example 9-17, a TNS HP COBOL program calls a TAL routine named SYS^PROCEDURE that expects one reference parameter and three value parameters. Because no qualifying mnemonic-name is present, one or more search lists must be present (produced from SEARCH, LIBRARY, or CONSULT directives) or the procedure must be in the object file COBOLEXT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 65 Procedure Division Verbs ENTER Example 9-17. HP COBOL Program Calling TAL Routine TAL procedure declarations: INT PROC SYS^PROCEDURE (T, I, FIX, N); STRING .T; ! REFERENCE ADDRESS INT I; ! VALUE FIXED(4) FIX; ! VALUE INT N; ! VALUE COBOL source code: WORKING-STORAGE SECTION. 77 T PIC X(40) 77 I PIC 9(4) 77 FIX PIC S9(13)V9999 77 RESULT PIC 9(4). ... PROCEDURE DIVISION. ... ENTER TAL "SYS^PROCEDURE" VALUE SPACES. VALUE ZERO COMP. VALUE -125641.3992 COMP. USING T (I+1) GIVING RESULT FIX 25 In Example 9-18, a TNS HP COBOL program calls the TAL procedure LOAD^BACKUP^CPU that is in this object file: $DATA.MYSUBVOL.TALL The procedure accepts no parameters and returns a 2-byte result. Example 9-18. HP COBOL Program Calling TAL Routine in Object File ENVIRONMENT DIVISION. CONFIGURATION SECTION. ... SPECIAL-NAMES. FILE "$DATA.MYSUBVOL.TALL" IS TAL-LIBRARY. ... WORKING-STORAGE SECTION. 77 BACK-UP-CPU PIC S99 COMPUTATIONAL. ... PROCEDURE DIVISION. ... ENTER TAL "LOAD^BACKUP^CPU" IN TAL-LIBRARY GIVING BACK-UP-CPU ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 66 Procedure Division Verbs ENTER COBOL ENTER COBOL HP COBOL compilers treat ENTER COBOL as a comment. In implementations that use ENTER to mark the beginning of an embedded routine in a language other than COBOL, the ENTER COBOL statement ends the embedded routine and the resumption of COBOL source code. ENTER . COBOL VST150.vsd EVALUATE EVALUATE defines a multiple-branch structure, a decision table. EVALUATE executes a different group of statements when one or more data items or expressions have certain sets of values. EVALUATE subject-list WHEN object-list WHEN OTHER match-imp-stmt no-match-imp-stmt END-EVALUATE VST151.vsd subject-list subject ALSO subject VST616.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 67 Procedure Division Verbs EVALUATE subject identifier literal expression TRUE FALSE VST152.vsd identifier is any identifier (it can be qualified, subscripted, or reference-modified). literal is any literal. expression is an arithmetic or conditional expression. TRUE FALSE are logical values. object-list object ALSO object VST153.vsd object ANY condition TRUE FALSE range NOT VST154.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 68 Procedure Division Verbs EVALUATE ANY matches any corresponding selection subject. condition is a relation condition, class condition, condition-name condition, switchstatus condition, sign condition, or complex condition. TRUE FALSE are truth values. NOT inverts the comparison. A match occurs when the value of a subject differs from the value of the corresponding object or lies outside the range specified for the object. range identifier-1 literal-1 THROUGH identifier-2 arith-exp-1 THRU literal-2 arith-exp-2 VST155.vsd identifier-1 identifier-2 are any identifiers (they can be qualified, subscripted, or referencemodified). They can be compared to any corresponding selection subjects being compared in a conditional expression. literal-1 literal-2 can be any literals. They can be compared to any corresponding selection subject being compared in a conditional expression. arith-exp-1 arith-exp-2 are arithmetic expressions. They can be compared to any selection subject being in a conditional expression. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 69 Procedure Division Verbs EVALUATE THROUGH THRU indicate that a range of values is to be compared. Two operands combined by THROUGH or THRU must be of the same class (alphabetic, alphanumeric, or numeric). The two operands thus connected constitute a single selection object. match-imp-stmt is an imperative statement to be executed when the values of the objects in the associated object-list match the values of the corresponding subjects in the subject-list. no-match-imp-stmt is an imperative statement to be executed when no match-imp-stmt applies. After no-match-imp-stmt executes, control passes to the end of the EVALUATE statement. END-EVALUATE ends the scope of the EVALUATE statement and makes it a delimited-scope statement. If you omit END-EVALUATE, the EVALUATE statement is a conditional statement and ends at the next period separator. Usage Considerations: • EVALUATE in Comparison to “Case” Statement The EVALUATE statement is a generalization of what some languages call the “case” statement, a statement that enables you to execute one of several groups of statements depending on the value of a single data item. Example 9-19. EVALUATE Statement as “Case” Statement EVALUATE TRAN-CODE WHEN 1 PERFORM TRAN-1 WHEN 2 PERFORM TRAN-2 WHEN 3 PERFORM TRAN-3 WHEN OTHER PERFORM TRAN-BAD END-EVALUATE Example 9-20. EVALUATE Statement With Both Ranges and Discrete Values EVALUATE SALARY OF PAYROLL-REC WHEN 15000 THRU 29999.99 PERFORM WHEN 30000 THRU 49999.99 PERFORM WHEN 50000 THRU 99999999 PERFORM WHEN OTHER PERFORM END-EVALUATE LOW-BRACKET MIDL-BRACKET HIGH-BRACKET NO-BRACKET HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 70 Procedure Division Verbs EVALUATE The EVALUATE statement extends the “case” statement concept by allowing several selection subjects and matching objects—the equivalent of a decision table. The EVALUATE statement in Example 9-21 uses the values of two distinct subjects to make its selection. Example 9-21. EVALUATE Statement With Two Distinct Subjects EVALUATE DEDUCTIONS ALSO SALARY WHEN 0 ALSO 0 THRU 14999.99 WHEN 0 ALSO 15000 THRU 29999.99 WHEN 0 ALSO 30000 THRU 49999.99 WHEN 1 THRU 2 ALSO 0 THRU 19999.99 WHEN 1 THRU 2 ALSO 20000 THRU 69999.99 WHEN 1 THRU 2 ALSO 70000 THRU 99999999 WHEN OTHER PERFORM FURTHER-ANALYSIS END-EVALUATE PERFORM PERFORM PERFORM PERFORM PERFORM PERFORM XXA YYA ZZA XXB YYB ZZB The selection objects (the “0” and “1 THRU 2” of Example 9-21) are not restricted to being literals or ranges of literals; they can also be (for example) condition names, identifiers, and arithmetic expressions. The WHEN OTHER phrase is commonly used as the mechanism for handling errors, enabling the program to detect invalid values for subjects and improper specification of objects. Example 9-22. EVALUATE Statement as a Decision Table EVALUATE XXX ALSO "GONE" ALSO ( A + B ) / C ALSO X = Y WHEN 5 ALSO ANY ALSO 25 ALSO TRUE PERFORM PROC-A WHEN 10 THRU 30 ALSO YYY ALSO 2 ALSO FALSE PERFORM PROC-B WHEN OTHER ADD 1 TO VACUOUS-COUNT END-EVALUATE • Subject-Object Correspondence Every object-list must have an object for every subject in the subject-list. Each object in an object-list must correspond to the subject that has the same ordinal position in the subject-list. The rules that determine whether a subject and object correspond are: ° ° The object value ANY corresponds to any subject value. ° An object composed of identifiers, literals, or arithmetic expressions corresponds to a subject if the value of the object is a valid operand for comparison to the subject. An object that is a condition or the value TRUE or FALSE corresponds to a subject that is a conditional expression or the value TRUE or FALSE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 71 Procedure Division Verbs • EVALUATE Subject-Object Comparisons EVALUATE operates as if each corresponding subject and object were evaluated and assigned one of: ° ° ° ° A numeric or nonnumeric value A range of numeric or nonnumeric values TRUE FALSE The subject is determined: subject EVALUATE uses … identifier The value and class of the data item referenced by identifier literal The value and class of literal arithmetic expression The numeric value determined by the rules for evaluating arithmetic expressions conditional expression The truth value determined by the rules for evaluating conditional expressions TRUE TRUE FALSE FALSE The object is determined: object EVALUATE uses … identifier (without NOT or THRU) The value and class of the data item referenced by identifier literal (without NOT or THRU) The value and class of literal ZERO or ZEROS or ZEROES (without NOT or THRU) The value 0 and the class of the corresponding selection subject arithmetic expression (without NOT or THRU) The numeric value determined by the rules for evaluating arithmetic expressions condition The truth value determined by the rules for evaluating conditional expressions ANY No value—ANY matches any selection subject A range of items specified with the keyword THRU but without the keyword NOT The range of all permissible subject values greater than or equal to the first operand and less than or equal to the second operand (if the value of the first operand is greater than the value of the second operand, there are no values in the range) The keyword NOT followed by an item or a range of items All permissible subject values not equal to the value, or not included in the range of values, that would have been used if the keyword NOT had been omitted TRUE TRUE FALSE FALSE HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 72 Procedure Division Verbs • EVALUATE Execution of the EVALUATE Statement Execution of the EVALUATE statement begins with the comparison phase illustrated in Figure 9-3. A comparison is satisfied if one of these conditions is true: ° ° ° The object is ANY (and the value of the subject is irrelevant). The corresponding subject and object were both assigned TRUE or both assigned FALSE. The corresponding subject and object were assigned the same type of values (numeric or nonnumeric) and the value assigned to the subject is equal to the value (or within the range of values) assigned to the object, according to the rules for comparison defined for a relation condition (see Relation Conditions in General). If each comparison in an object-list is satisfied, the object-list “qualifies.” After the comparison phase ends, execution of the EVALUATE statement proceeds as shown in Figure 9-4. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 73 Procedure Division Verbs EVALUATE Figure 9-3. Comparison Phase of EVALUATE Statement Enter Current object-list is first object-list Current subject is first subject Compare current subject with corresponding objectin current object-list Current subject is next subject TRUE Another subject ? TRUE FALSE Comparison satisfied? FALSE Another TRUE object-list ? Current object-list is next object-list FALSE Exit VST532.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 74 Procedure Division Verbs EVALUATE Figure 9-4. Execution Phase of the EVALUATE Statement Enter An object-list FALSE qualified? WHEN OTHER phrase? TRUE Execute match-imp-stmt associated with qualifying object-list Control returns to point immediately after imperative statement? FALSE TRUE Execute no-match-imp-stmt FALSE Control is wherever imperative statement transferred it TRUE Control passes to end of EVALUATE statement Exit VST533.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 75 Procedure Division Verbs EXIT EXIT EXIT provides: • • • • A common end point for a series of procedures A marker for the logical end of a called program A way to return to the test in an in-line PERFORM statement A way to go to the end of the last statement in a paragraph or section EXIT PROGRAM PARAGRAPH SECTION PERFORM CYCLE VST156.vsd PROGRAM PARAGRAPH SECTION PERFORM CYCLE are explained in Table 9-2. Table 9-2. EXIT Statement Restrictions and Effects (page 1 of 2) Statement Restrictions Effect EXIT Must appear in a sentence by itself, and that sentence must be the only sentence in the paragraph. Provides a common end point for a group of procedures or indicates the logical end of a called program. Does not affect program compilation or execution. EXIT PROGRAM If it appears in a consecutive sequence of imperative statements within a sentence, it must be the last statement in the sequence. Depends on the program that executes it—see Usage Considerations:. Not allowed while executing a GLOBAL declarative procedure, except within a program that was called while the declarative procedure was executing. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 76 Procedure Division Verbs EXIT Table 9-2. EXIT Statement Restrictions and Effects (page 2 of 2) Statement Restrictions Effect EXIT PARAGRAPH Must be contained in a paragraph. Transfers control to an implicit CONTINUE statement immediately preceding the next procedure declaration. If there is no next procedure declaration, it transfers control to an implicit CONTINUE statement at the end of the program. EXIT SECTION Must be contained in a section. Transfers control to an implicit CONTINUE statement immediately preceding the next section declaration. If there is no next section declaration, it transfers control to an implicit CONTINUE statement at the end of the program. EXIT PERFORM Must be contained in an inline PERFORM statement. Immediately transfers control to an implicit CONTINUE statement immediately following the END-PERFORM statement associated with the in-line PERFORM statement (see Example 9-23). EXIT PERFORM CYCLE Must be contained in an inline PERFORM statement. Immediately transfers control to an implicit CONTINUE statement immediately preceding the END-PERFORM statement associated with the in-line PERFORM statement (see Example 9-24). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 77 Procedure Division Verbs Example 9-23. EXIT PERFORM Statement 0001-TEST-EXIT-PERF. INITIALIZE WS-ANS. INITIALIZE WS-NUMBER. INITIALIZE WS-NUMBER-PERF. INITIALIZE WS-TEST-RESULTS. DISPLAY "TEST EXITS-1 FOR EXIT PERFORM BEGINS". PERFORM UNTIL WS-NUMBER-PERF = 99 ADD 3 TO WS-NUMBER-PERF IF WS-NUMBER-PERF = 96 MOVE 1 TO WS-NUMBER-PERF EXIT PERFORM END-IF IF WS-NUMBER-PERF = 1 DISPLAY "DID NOT EXIT PERFORM SUCCESSFULLY" MOVE 99 TO WS-NUMBER-PERF END-IF END-PERFORM. IF WS-NUMBER-PERF = 1 DISPLAY "TEST EXITS-1 FOR EXIT PERFORM SUCCESSFUL." ELSE DISPLAY "TEST EXITS-1 FOR EXIT PERFORM FAILED .". 0001-TEST-EXIT-PERF-EXIT. EXIT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 78 EXIT Procedure Division Verbs EXIT Example 9-24. EXIT PERFORM CYCLE Statement ?SYMBOLS IDENTIFICATION DIVISION. PROGRAM-ID. EXIT-PERFORM. DATA DIVISION. WORKING-STORAGE SECTION. 77 X PIC 999. 77 X PIC 999. 77 X PIC 999. PROCEDURE DIVISION. SUNRISE. DISPLAY "EXIT PERFORM TEST". MOVE 0 TO X MOVE 0 TO Y MOVE 0 TO Z * The loop appears to execute 200 times ... PERFORM UNTIL X=200 ADD 1 TO X * however, we exit after only 100 times. IF X = 100 EXIT PERFORM END-IF * Y counts to 4, so that every 4th time, exit the perform * cycle without incrementing Z ... ADD 1 TO Y IF Y = 4 MOVE 0 TO Y EXIT PERFORM CYCLE END-IF * so Z is incremented only 75 times, not 100. ADD 1 TO Z END-PERFORM . DISPLAY "X: " X. DISPLAY "Y: " Y. DISPLAY "Z: " Z. Usage Considerations: • EXIT PROGRAM Statement in a Program That Was Not Called If a program that was not called by another program executes an EXIT PROGRAM statement, program execution continues with the next executable statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 79 Procedure Division Verbs • EXIT EXIT PROGRAM Statement in a Called Initial Program If an initial program that was called by another program executes an EXIT PROGRAM statement, the called program is cancelled (see CANCEL). • EXIT PROGRAM Statement in a Called Program That is Not Initial If a program that was called by another program and is not initial executes an EXIT PROGRAM statement, program execution continues with the executable statement following the CALL statement in the calling program. The program state of the calling program is the same as it was when it executed the CALL statement, except for possible changes in the contents of data items and files that the calling and called programs shared. The only change in the program state of the called program is that the ends of the ranges of all PERFORM statements that it executed are considered to have been reached. • EXIT PERFORM in Nested In-Line PERFORM Statements An EXIT PERFORM statement in a nested in-line PERFORM statement causes the innermost PERFORM statement to be exited. Example 9-25. EXIT Statement in Nested In-Line PERFORM Statement ... PERFORM REPORT-EXPLOSION THROUGH REPORT-EXPLOSION-END. ... REPORT-EXPLOSION. READ MASTER-EXP RECORD AT END GO TO REPORT-EXPLOSION-END END-READ GO TO SUB-ASSY-1 SUB-ASSY-2 ... SUB-ASSY-23 DEPENDING ON SUB-ASSY OF MASTER-EXP PERFORM REPORT-BAD-SUB-ASSEMBLY GO TO REPORT-EXPLOSION-END. SUB-ASSY-1. ... SUB-ASSY-2. ... REPORT-EXPLOSION-END. EXIT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 80 Procedure Division Verbs GO TO GO TO Form Passes control to: Unconditional GO TO The beginning of a paragraph or section in the current program Conditional GO TO One of several procedures, depending on the value of a variable data item Unconditional GO TO Unconditional GO TO passes control to the beginning of a paragraph or section in the current program. GO TO procedure-name VST158.vsd procedure-name is the name of the procedure (paragraph or section) to which the process transfers control. If no procedure-name is present, the process must execute an ALTER statement naming the procedure before it executes the GO TO statement to set the destination procedure-name. Note. The 1985 COBOL standard classifies ALTER as obsolete, so you are advised not to use it, and therefore, not to use unconditional GO TO without procedure-name. Usage Considerations: • Declarative and Nondeclarative Procedures A GO TO statement in a declarative procedure (a procedure in the Declaratives Portion of the Procedure Division) cannot refer to a nondeclarative procedure (a procedure in the other portion of the Procedure Division). A GO TO statement in a nondeclarative procedure cannot refer to a declarative procedure. • Debugging and Nondebugging Declarative Procedures A GO TO statement in a debugging declarative procedure (a declarative procedure introduced by a USE DEBUGGING statement) cannot refer to a nondebugging declarative procedure. A GO TO statement in a nondebugging declarative procedure cannot refer to a debugging declarative procedure. • ALTER Statement Because the 1985 COBOL standard classifies ALTER as an obsolete element, and because the ALTER statement can cause maintenance problems, so you are advised not to use it. For more information, see ALTER. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 81 Procedure Division Verbs • Conditional GO TO Consecutive Imperative Statements in a Sentence When a GO TO statement includes procedure-name and the paragraph containing the GO TO statement is not referenced by an ALTER statement, the GO TO statement can be the last of a sequence of consecutive imperative statements within a sentence. Conditional GO TO Conditional GO TO passes control to one of several procedures, depending on the value of a variable data item. GO procedure-name TO DEPENDING ON depend VST159.vsd procedure-name is the name of the procedure (paragraph or section) to which the process transfers control, depending on the value of depend. The GO TO statement can have as many as 255 different procedure names. depend is the identifier of an elementary integer data item. Its value determines which procedure will receive control. If the value of depend is less than 1 or exceeds the number of procedures, control passes to the next statement. Usage Considerations: • Declarative and Nondeclarative Procedures A GO TO statement in a declarative procedure (a procedure in the Declaratives Portion of the Procedure Division) cannot refer to a nondeclarative procedure (a procedure in the other portion of the Procedure Division). A GO TO statement in a nondeclarative procedure cannot refer to a declarative procedure. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 82 Procedure Division Verbs • IF Debugging Declarative Procedures A GO TO statement in a debugging declarative procedure cannot refer to a nondebugging declarative procedure. A GO TO statement in a nondebugging declarative procedure cannot refer to a debugging declarative procedure. In Example 9-26, if BRANCH-FLAG equals 1, control passes to PROC-X. If BRANCH-FLAG equals 2, control passes to PROC-Y. If BRANCH-FLAG equals 3, control passes to PROC-Z. If BRANCH-FLAG is less than 1 or greater than 3, control passes to the MOVE statement immediately following the GO TO statement. Example 9-26. Three-Way Conditional GO TO Statement PROCEDURE-BRANCH. GO TO PROC-X PROC-Y PROC-Z DEPENDING ON BRANCH-FLAG MOVE 0 TO BRANCH-FLAG IF IF transfers control if the value of a condition is TRUE or FALSE. Form Comment Delimited-Scope Form Recommended for clarity and convenience Conditional Form Form that was available in COBOL 74 Delimited-Scope Form IF condition statement-1 THEN END-IF ELSE statement-2 VST160.vsd condition is any conditional expression (see Conditional Expressions). statement-1 is an imperative or conditional statement to be executed if the value of condition is TRUE. It can contain other IF statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 83 Procedure Division Verbs Delimited-Scope Form ELSE ends statement-1. statement-2 is an imperative or conditional statement to be executed if the value of condition is FALSE. It can contain other IF statements. END-IF ends the scope of the IF statement, making it a delimited-scope statement. Without END-IF, the IF statement is a conditional statement that ends at the next period separator. Usage Considerations: • Delimited-Scope Statements Are Recommended Over Conditional Statements For clarity and convenience, delimited-scope statements are recommended over conditional statements. • Period Separator in Delimited-Scope IF Statement A delimited-scope IF statement does not require a period separator. If a period separator occurs within a delimited-scope IF statement, it terminates the statement and the compiler diagnoses the END-IF as unmatched. • Nested Delimited-Scope IF Statements Delimited-scope IF statements can be “nested” (included) within other delimitedscope IF statements. Nested delimited-scope IF statements are interpreted by pairing each IF phrase with an ELSE phrase, ELSE … END-IF pair, or isolated END-IF phrase, proceeding from left to right within a sentence. Each ELSE, ELSE … END-IF, or isolated END-IF that the compiler encounters is considered to correspond to the nearest previous IF phrase that has not already been paired with an ELSE, ELSE … END-IF, or isolated END-IF. • How the Delimited-Scope IF Statement Works The condition is evaluated. If its value is TRUE, statement-1 is executed. If control reaches the point immediately following statement-1 (that is, statement-1 completes without executing a GO TO statement or the equivalent), control passes to the end of the IF statement. The ELSE phrase, if present, is ignored. If the value of condition is FALSE and an ELSE phrase is present, statement-2 is executed. If control reaches the point immediately following statement-2 (that is, statement-2 completes without executing a GO TO statement or the equivalent), control passes to the end of the IF statement. If the value of condition is FALSE and there is no ELSE phrase, control passes to the end of the IF statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 84 Procedure Division Verbs Delimited-Scope Form Figure 9-5. How the Delimited-Scope IF Statement Works Enter condition ? FALSE ELSE phrase? TRUE TRUE Execute statement-1 Execute statement-2 Control returns to point immediately after last statement-1 ? Control returns to point immediately after last statement-2 ? TRUE TRUE FALSE FALSE Control is wherever last statement-1 transferred it FALSE Control passes to end of IF statement Control is wherever last statement-2 transferred it Exit VST530.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 85 Procedure Division Verbs Conditional Form Conditional Form IF condition THEN statement-1 NEXT SENTENCE ELSE statement-2 NEXT SENTENCE VST161.vsd condition is any conditional expression (see Conditional Expressions). statement-1 is an imperative or conditional statement to be executed if the value of condition is TRUE. It can contain other IF statements. NEXT SENTENCE specifies that control be passed directly to the end of the sentence containing the IF statement. It is not recommended (see Usage Considerations:). ELSE ends statement-1. statement-2 is an imperative or conditional statement to be executed if the value of condition is FALSE. It can contain other IF statements. Usage Considerations: • CONTINUE and END-IF Are Recommended Over NEXT SENTENCE NEXT SENTENCE transfers control to the next period (.) while CONTINUE transfers control to END-IF. Either or both statement-1 and statement-2 can be CONTINUE statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 86 Procedure Division Verbs • Conditional Form IF Sentences A conditional IF statement followed by a period separator is called an “IF sentence.” An IF sentence can contain IF statements (of either form) only if such IF statements do not end with period separators. • Nested Conditional IF Statements Conditional IF statements can be “nested” (included) within other conditional IF statements. When conditional IF statements are nested, each optional ELSE phrase is considered to be the next phrase of the nearest preceding unterminated conditional IF statement with which that phrase is permitted to be associated according to the syntax of the conditional IF statement, but with which no such phrase has already been associated. An unterminated statement is one that has not been previously terminated either explicitly or implicitly. The separator period that terminates the sentence also terminates all nested statements. • How the Conditional IF Statement Works The condition is evaluated. If its value is TRUE and NEXT SENTENCE is specified (as opposed to statement-1 ), control passes to the next executable sentence. The ELSE phrase, if present, is ignored. If the value of condition is TRUE and statement-1 is specified (as opposed to NEXT SENTENCE), statement-1 is executed. If control reaches the point immediately following statement-1 (that is, statement-1 completes without executing a GO TO statement or the equivalent), control passes to the end of the IF statement. The ELSE phrase, if present, is ignored. If the value of condition is FALSE and an ELSE phrase specifies NEXT SENTENCE, control passes to the next executable sentence. If the value of condition is FALSE and an ELSE phrase specifies statement-2, statement-2 is executed. If control reaches the point immediately following statement-2 (that is, statement-2 completes without executing a GO TO statement or the equivalent), control passes to the end of the IF statement. If the value of condition is FALSE and there is no ELSE phrase, control passes to the end of the IF statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 87 Procedure Division Verbs Conditional Form Figure 9-6. How the Conditional IF Statement Works Enter condition ? ELSE phrase ? FALSE TRUE THEN NEXT SENTENCE ? TRUE TRUE TRUE ELSE NEXT SENTENCE ? FALSE FALSE Execute statement-1 Execute statement-2 Control returns to point immediately after last statement-1 ? Control returns to point immediately after last statement-2 ? TRUE TRUE FALSE Control is wherever last statement-1 transferred it FALSE FALSE Control passes to next sentence Control is wherever last statement-2 transferred it Exit VST531.vsd Example 9-27 and Example 9-28 are equivalent. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 88 Procedure Division Verbs Conditional Form Example 9-27. Simple Conditional IF Statement IF JULIAN-DAYS IS GREATER THAN 59, ADD LEAP-YEAR TO JULIAN-DAYS. Example 9-28. Delimited-Scope IF Statement IF JULIAN-DAYS IS GREATER THAN 59 ADD LEAP-YEAR TO JULIAN-DAYS END-IF Example 9-29 and Example 9-30 are equivalent. Example 9-29. Simple Conditional IF ELSE Statement IF TALLY GREATER THAN 0 MOVE 0 TO TALLY MOVE 3 TO MSG-INDEX PERFORM PRINT-ERROR-ROUTINE ELSE MOVE 1 TO FLAG. Example 9-30. Delimited-Scope IF ELSE Statement IF TALLY GREATER THAN 0 MOVE 0 TO TALLY MOVE 3 TO MSG-INDEX PERFORM PRINT-ERROR-ROUTINE ELSE MOVE 1 TO FLAG END-IF Example 9-31 and Example 9-32 are equivalent. Example 9-31. IF ELSE Statement Nested Within PERFORM Statement PERFORM DIV-IT VARYING I FROM 1 BY 1 UNTIL I > N ... DIV-IT. MOVE INF TO Q (I) IF D (I) > 0 DIVIDE X (I) BY D (I) GIVING Q (I). Example 9-32. Delimited-Scope IF ELSE Statement Nested Within PERFORM Statement PERFORM VARYING I FROM 1 BY 1 UNTIL I > N IF D (I) > 0 THEN DIVIDE X (I) BY D (I) GIVING Q(I) ELSE MOVE INF TO Q (I) END-IF END-PERFORM HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 89 Procedure Division Verbs Conditional Form Example 9-33. Nested Conditional IF Statements IF EMPLOYEE-NUMBER NOT EQUAL TO SPACES PERFORM READ-ROUTINE * Must perform out of line * to do INVALID KEY test IF NO-ERROR PERFORM LIST-RECORD-OUT DISPLAY "DELETE ? Y or N" ACCEPT ANSWER IF YES-ANSWER PERFORM DELETE-MASTER * Must perform out of line * to do INVALID KEY test IF NO-DELETE-ERROR ADD 1 TO DELETE-COUNT ELSE NEXT SENTENCE ELSE DISPLAY "0 RECORDS DELETED" MOVE 0 TO FLAG ELSE NEXT SENTENCE ELSE MOVE 1 TO FLAG. Example 9-34 shows the equivalent delimited-scope IF statement with delimited-scope statements marked. Example 9-34. Delimited-Scope IF Statement IF EMPLOYEE-NUMBER NOT EQUAL TO SPACES READ EMP-FILE RECORD NOT INVALID KEY PERFORM LIST-RECORD-OUT DISPLAY "DELETE ? Y or N" ACCEPT ANSWER IF YES-ANSWER DELETE EMP-FILE RECORD NOT INVALID KEY ADD 1 TO DELETE-COUNT END-DELETE ELSE DISPLAY "0 RECORDS DELETED" MOVE 0 TO FLAG END-IF END-READ ELSE MOVE 1 TO FLAG END-IF VST529.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 90 Procedure Division Verbs INITIALIZE INITIALIZE INITIALIZE sets selected types of data items to predetermined values; for example, numeric data to zeros or alphanumeric data to spaces. INITIALIZE receiver REPLACING replacement VST162.vsd receiver is the identifier of an elementary item or data structure. These restrictions apply to the data item: ° ° ° ° It cannot be an index data item or a pointer data item. It cannot be a special register. Its description cannot include a RENAMES clause. Its description (and the descriptions of its subordinate data items, if any) cannot include an OCCURS clause with a DEPENDING phrase. The maximum number of receivers in an INITIALIZE statement is 127. replacement ALPHABETIC ALPHANUMERIC NUMERIC ALPHANUMERIC-EDITED NUMERIC-EDITED BY DATA sender literal VST163.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 91 Procedure Division Verbs INITIALIZE specifies the category of elementary item in receiver to which the INITIALIZE operation is to assign a value. The default replacement is ZEROS for each NUMERIC or NUMERIC-EDITED receiver and SPACES for each ALPHABETIC, ALPHANUMERIC, or ALPHANUMERIC-EDITED receiver. The receiver is in one of these categories whether you specify replacement or not (see PICTURE Clause). ALPHABETIC ALPHANUMERIC NUMERIC ALPHANUMERIC-EDITED NUMERIC-EDITED are categories defined in PICTURE Clause. The category you specify must be permitted for a receiving operand in a MOVE statement where the corresponding sending operand is sender or literal. You cannot specify a category more than once in a single INITIALIZE statement. sender is the identifier of a data item from which the INITIALIZE statement obtains a value to store into the elementary items specified by receiver. The sender cannot be a national or index data item. literal is the representation of a value that the INITIALIZE statement stores into the elementary item specified by receiver. literal cannot be a national literal. The INITIALIZE statements in Example 9-35 assign initial values to data structures composed of counters and pointers that a program uses for UNSTRING and INSPECT statements. In the first statement, the REPLACING phrase can be omitted if UNSTRING-COUNTERS and INSPECT-COUNTERS are numeric. Example 9-35. INITIALIZE Statements INITIALIZE UNSTRING-COUNTERS INSPECT-COUNTERS REPLACING NUMERIC DATA BY ZERO INITIALIZE UNSTRING-POINTERS INSPECT-POINTERS REPLACING NUMERIC DATA BY 1 The INITIALIZE statement in Example 9-36 assigns a value of zero to only the numeric-edited items in a table composed of a variety of categories. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 92 Procedure Division Verbs INITIALIZE Example 9-36. INITIALIZE Statement 01 STOCK. 03 STOCK-ITEM OCCURS 500 TIMES. 05 S-NAME PIC X(30). 05 S-WHOLESALE-PRICE PIC $$$,$$$.99. 05 S-MARKUP-PCT PIC P999. ... INITIALIZE STOCK REPLACING NUMERIC-EDITED DATA BY ZERO Usage Considerations: • Execution of the INITIALIZE Statement The INITIALIZE statement is equivalent to a series of MOVE statements, each of which has an elementary item as its receiving operand. • Determining the Receiving Operands If receiver includes reference modification, the data item to which it refers is handled as an elementary item. If receiver references an elementary data item, that data item is a receiving operand unless the INITIALIZE statement includes a REPLACING phrase and the category of the elementary data item is not specified in any of the phrases following the REPLACING phrase. If receiver references an elementary data item that is not a receiving operand, that data item is not initialized. If receiver references a data structure, each elementary item subordinate to the data structure (including each element in a subordinate table) is a receiving operand; however, the initialize operation ignores: ° ° ° ° Index or pointer data items ° Data items that are not in the same categories as the initial values specified for them; for example, an ALPHABETIC receiver is not initialized to a NUMERIC replacement value even if the INITIALIZE statement specifies this Elementary FILLER data items Data items whose descriptions contain REDEFINES clauses Data items subordinate to data items whose descriptions contain REDEFINES clauses HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 93 Procedure Division Verbs • INITIALIZE Determining the Sending Operands The initialize operation determines the sending operand in each implicit MOVE statement: ° If you include replacement, the sending operand is the literal or sender associated with the category of the receiving operand. ° If you omit replacement, the sending operand is the implied figurative constant SPACES or ZEROS, as this table shows: Category of Receiving Operand Sending Operand ALPHABETIC SPACES ALPHANUMERIC SPACES ALPHANUMERIC-EDITED SPACES NUMERIC ZEROS NUMERIC-EDITED ZEROS The value of sender is established before the implicit MOVE statement executes. • Execution of the Implicit MOVE Statements For each receiving operand, the initialization operation executes an implicit MOVE statement of the form: MOVE SENDING-OPERAND TO RECEIVING-OPERAND The implicit MOVE statements are executed in the order that the receiver s associated with their receiving operands appear in the INITIALIZE statement (reading from left to right). When a receiver references a data structure, the affected elementary items are initialized in the order that they are defined within the data structure. Tables within data structures are initialized element by element. • Operand Overlap The storage area referenced by a sender cannot be the same as or overlap the storage area referenced by a receiver. If this rule is violated, the operation is undefined. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 94 Procedure Division Verbs INSPECT INSPECT INSPECT scans a data item and counts and/or replaces occurrences of a single character or groups of characters. Form Description INSPECT TALLYING Counts occurrences of a character sequence in a source string INSPECT REPLACING Replaces occurrences of a character sequence in a data item with a specified value INSPECT TALLYING REPLACING Counts occurrences of a character sequence in a data item and replaces each occurrence with a specified value INSPECT CONVERTING Performs a character-for-character replacement INSPECT TALLYING INSPECT TALLYING counts occurrences of a sequence of one or more characters in a source string. INSPECT source-string tallying-phrase VST164.vsd source-string is the identifier of an elementary item or data structure with USAGE DISPLAY. Inspection proceeds from left to right within source-string. tallying-phrase TALLYING tally FOR for-clause VST165.vsd tally is the identifier of an elementary numeric item where the number of occurrences is to be stored. The INSPECT statement does not initialize tally but adds to its current value. If you want tally to begin at a given number, set it before the INSPECT statement executes. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 95 Procedure Division Verbs INSPECT TALLYING for-clause CHARACTERS position ALL compare-string LEADING position VST166.vsd CHARACTERS specifies that any character in source-string that has not satisfied a previous compare-string relation is counted, regardless of its value. position BEFORE AFTER delim-string INITIAL VST167.vsd marks a beginning or ending point for an INSPECT scan cycle. Each CHARACTERS phrase, ALL phrase, or LEADING phrase can have a single BEFORE phrase, a single AFTER phrase, or one BEFORE phrase and one AFTER phrase in either order. BEFORE specifies that scanning is up to but not including the character or characters matching delim-string. If INSPECT does not find delim-string in source-string, it scans all of sourcestring. AFTER specifies that scanning starts at the position immediately following the character or characters matching delim-string. If INSPECT does not find delim-string in source-string, it does not scan source-string. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 96 Procedure Division Verbs INSPECT TALLYING delim-string is the identifier of an elementary item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. ALL specifies that all occurrences of compare-string are tallied. LEADING specifies scanning for consecutive occurrences of compare-string beginning at the current position within source-string. compare-string is the identifier of an elementary data item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. The comparestring is the character-string being sought. Usage Considerations: • Definition of “Leading” Characters are “leading” when they begin in the leftmost position of sourcestring and have not satisfied another compare-string condition. For example, two leading As are found in “AARDVARK” when INSPECT ... FOR LEADING "A" is coded, but no leading As are found in “AARDVARK” when INSPECT ... FOR ALL "A" ... FOR LEADING "A". is coded. The ALL phrase finds all three As, so none are left for the LEADING phrase to find. (For a complete explanation of the logic of the comparison, see Comparison Operation.) An example of LEADING ZERO is 00012. • National Data Items and National Literals National data items and national literals cannot be used in an INSPECT statement. • How Parameter Categories Affect INSPECT 1. If source-string, compare-string, or delim-string is alphanumeric, the INSPECT statement handles the contents of each of them as a characterstring. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 97 Procedure Division Verbs INSPECT TALLYING 2. If source-string, compare-string, or delim-string is alphanumeric edited, numeric edited, or unsigned numeric, the source-string is inspected as though it had been redefined as alphanumeric and the INSPECT statement had been written to refer to the redefined item. 3. If source-string, compare-string, or delim-string is described as a signed numeric, source-string is inspected as though it had been moved to an unsigned numeric data item of the same length (excluding any separate sign), and then Item 2 applies. • Comparison Operation The comparison operation to determine the occurrences of compare-string works like this: 1. Each tally is considered in the order specified in the INSPECT statement (reading from left to right). The first compare-string is compared to an equal number of consecutive characters of source-string, starting with source-string ’s leftmost character. If the compare-string and the substring of source-string are equal, character for character, then they match. 2. If no match occurs in the comparison of the first compare-string, the comparison is repeated with each successive compare-string until either a match is made or there is no next compare-string. When there is no next compare-string, the character position in source-string immediately to the right of the leftmost character position considered in the last comparison cycle is considered to be the leftmost character position, and the comparison cycle begins again with the first compare-string. 3. Whenever a match occurs, tallying occurs as described in Tallying. The character position in source-string immediately to the right of the rightmost character position that participated in the match is now considered to be the leftmost character position of source-string, and the comparison cycle resumes with the first compare-string. 4. The comparison operation continues until the rightmost character position of source-string has participated in a match or has been considered to be the leftmost character position. When this occurs, inspection terminates. 5. If the CHARACTERS phrase appears, an implied 1-character operand participates in the comparison cycle, except that no comparison to the contents of source-string occurs. This implied character is considered to match the leftmost character of source-string participating in the current comparison cycle. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 98 Procedure Division Verbs • INSPECT TALLYING BEFORE and AFTER Phrases The BEFORE and AFTER phrases affect the comparison operation like this: 1. If no BEFORE or AFTER phrase is present, compare-string or the operand implied by CHARACTERS participates in the comparison operation. 2. If the BEFORE phrase appears, the associated compare-string or the operand implied by CHARACTERS participates only in comparison cycles that involve the portion of source-string from its leftmost character position up to, but not including, the first occurrence of delim-string. The position of this first occurrence is determined before the first cycle of the comparison operation begins. If, on any comparison cycle, compare-string or the operand implied by CHARACTERS is not eligible to participate, it is not considered to match the contents of source-string. If delim-string does not occur within source-string, its associated compare-string or the operand implied by CHARACTERS participates in the comparison operation as though the BEFORE phrase was not specified. 3. If the AFTER phrase appears, the associated compare-string or the operand implied by CHARACTERS can participates only in comparison cycles that involve the portion of source-string following the first occurrence of delim-string. The position of the first occurrence of delim-string. is determined before the first cycle of the comparison operation begins. The portion of source-string following the first occurrence of delim-string begins with the character position immediately to the right of the rightmost character of the first occurrence of delim-string and ends with the rightmost character of source-string. If, on any comparison cycle, compare-string or the operand implied by CHARACTERS is not eligible to participate, it is not considered to match the contents of source-string. If delim-string does not occur within source-string, its associated compare-string or the operand implied by CHARACTERS is not eligible to participate in the comparison operation. • Tallying The INSPECT statement does not initialize tally. During the inspection of source-string, each properly matched occurrence of compare-string is tallied, using these rules: ° If the ALL phrase appears, tally is incremented by one for each occurrence of compare-string matched within source-string. ° If the LEADING phrase appears, tally is incremented by one for each contiguous occurrence of compare-string matched within sourcestring, provided that the leftmost such occurrence is at the point where comparison began in the first comparison cycle in which compare-string was eligible to participate. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9- 99 Procedure Division Verbs ° INSPECT TALLYING If CHARACTERS appears, tally is incremented by one for each character matched within source-string. In the Example 9-37, INSPECT TALLYING checks for spaces in a data item. If spaces are present (J-TALLY is greater than 0), the code reports an error. Example 9-37. INSPECT TALLYING With One Compare-String MOVE ZERO TO J-TALLY INSPECT JOB-CLASS TALLYING J-TALLY FOR ALL SPACES IF J-TALLY GREATER THAN 0 MOVE 0 TO J-TALLY MOVE 3 TO MESSAGE-INDEX PERFORM PRINT-ERROR ELSE MOVE 1 TO FLAG END-IF In Example 9-38, an INSPECT TALLYING statement uses multiple compare-string s. Some characters look as if they qualify as matches, yet are not counted, because a character can be counted only once, no matter how many comparisons it can satisfy. Example 9-38. INSPECT TALLYING With Multiple Compare-Strings WORKING-STORAGE SECTION. 01 77 INSPECT-COUNTERS. 03 COUNTER-1 03 COUNTER-2 03 COUNTER-3 03 COUNTER-4 03 COUNTER-5 ITEM-A PIC PIC 99 PIC 99 PIC 99 PIC 99 PIC 99 X(15) PROCEDURE DIVISION. ... INSPECT ITEM-A TALLYING COUNTER-1 COUNTER-2 COUNTER-3 COUNTER-4 COUNTER-5 FOR FOR FOR FOR FOR VALUE 0. VALUE 0. VALUE 0. VALUE 0. VALUE 0. VALUE " 00001,003,200". ALL "0", CHARACTERS BEFORE INITIAL "," LEADING " ", ALL "0" BEFORE INITIAL ",", ALL "0" AFTER INITIAL "," HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -100 Procedure Division Verbs INSPECT TALLYING After execution of the INSPECT statement in Example 9-38, the counters have these values: Counter Value COUNTER-1 8 COUNTER-2 3 COUNTER-3 0 COUNTER-4 0 COUNTER-5 0 HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -101 Procedure Division Verbs HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -102 INSPECT TALLYING Procedure Division Verbs INSPECT REPLACING 9 Procedure Division Verbs INSPECT REPLACING INSPECT REPLACING replaces occurrences of a sequence of one or more characters in a data item with a specified value. INSPECT source-string replacing-phrase VST168.vsd source-string is the identifier of an elementary item or data structure with USAGE DISPLAY. Inspection proceeds from left to right within source-string. replacing-phrase REPLACING absolute-replacement matching-replacement VST169.vsd absolute-replacement CHARACTERS BY replace-string position VST170.vsd CHARACTERS specifies that any character in source-string can be replaced, regardless of its value. If you use CHARACTERS, replace-string and delim-string must each be one character in length. replace-string is the identifier of an elementary item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -103 Procedure Division Verbs INSPECT REPLACING position BEFORE AFTER delim-string INITIAL VST167.vsd marks a starting and ending place for a replacement cycle. It follows the same item rules as replace-string. A CHARACTERS phrase, ALL phrase, LEADING phrase, or FIRST phrase can have a single BEFORE phrase, a single AFTER phrase, or one BEFORE phrase and one AFTER phrase in either order. BEFORE specifies that scanning is up to but not including the character or characters matching delim-string. If INSPECT does not find delim-string in source-string, it scans all of source-string. AFTER specifies that scanning starts at the position immediately following the character or characters matching delim-string. If INSPECT does not find delim-string in source-string, it does not scan source-string. INITIAL is for documentation only and has no effect. delim-string is the identifier of an elementary item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -104 Procedure Division Verbs INSPECT REPLACING matching-replacement ALL LEADING FIRST compare-string BY replace-string position VST172.vsd defines the character-string being scanned for. ALL specifies that all occurrences of compare-string are replaced. LEADING specifies scanning for consecutive occurrences of compare-string beginning at the current position within source-string. For example, REPLACING LEADING “0” replaces only the first three zeros in “000120020.” FIRST specifies that only the first occurrence of compare-string is replaced. compare-string is the identifier of an elementary data item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. The comparestring is the character-string being sought. replace-string is an identifier of an elementary data item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. When replacestring and compare-string are used together, they must be the same size. position is as described earlier for absolute-replacement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -105 Procedure Division Verbs INSPECT REPLACING Usage Considerations: • Rules for Replacement ° CHARACTERS causes each character in source-string to be replaced by replace-string. ° ALL causes each occurrence of compare-string in source-string to be replaced by replace-string. ° LEADING causes each contiguous occurrence of compare-string in source-string to be replaced by replace-string, provided that the leftmost occurrence is at the point where comparison began in the first comparison cycle in which compare-string was eligible to participate. ° FIRST causes the leftmost occurrence of compare-string in sourcestring to be replaced by replace-string. ALL, LEADING, and FIRST apply to each succeeding BY phrase until the next ALL, LEADING, or FIRST appears. • • See these usage considerations in INSPECT TALLYING: ° ° ° How Parameter Categories Affect INSPECT Comparison Operation BEFORE and AFTER Phrases Leading Zeros HP COBOL does not treat leading spaces in a numeric data item as if they were leading zeros, as some implementations of COBOL do. To convert leading spaces to zeros, use the INSPECT statement as Example 9-39 does. Example 9-39. INSPECT Statement Converting Leading Spaces to Zeros WORKING-STORAGE SECTION. 03 A-VALUE PICTURE X(10) VALUE " 23". 03 N-VALUE PICTURE 9(10) REDEFINES A-VALUE. ... INSPECT A-VALUE REPLACING LEADING " " BY "0". In Example 9-40, several replacements occur during the execution of one INSPECT statement. When the INSPECT statement finishes executing, ITEM-C equals “$$9,XXX.00.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -106 Procedure Division Verbs INSPECT TALLYING REPLACING Example 9-40. One INSPECT Statement, Several Replacements WORKING-STORAGE SECTION. 77 ITEM-C PIC X(10) VALUE "009,999. ". PROCEDURE DIVISION. INSPECT ITEM-C REPLACING ALL " " BY "0", LEADING "0" BY "$", ALL "9" BY "X" AFTER INITIAL "," INSPECT TALLYING REPLACING INSPECT TALLYING REPLACING counts occurrences of a sequence of one or more characters in a data item and replaces each occurrence with a specified value. INSPECT source-string tallying-phrase replacing-phrase VST174.vsd source-string is the identifier of an elementary item or data structure with USAGE DISPLAY. Inspection proceeds from left to right within source-string. tallying-phrase TALLYING tally FOR for-clause VST165.vsd tally is the identifier of an elementary numeric item where the number of occurrences is to be stored. The INSPECT statement does not initialize tally but adds to its current value. If you want tally to begin at a given number, set it before the INSPECT statement executes. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -107 Procedure Division Verbs INSPECT TALLYING REPLACING for-clause CHARACTERS position ALL compare-string LEADING position VST166.vsd CHARACTERS specifies that any character in source-string that has not satisfied a previous compare-string relation is counted, regardless of its value. position BEFORE AFTER delim-string INITIAL VST167.vsd marks a beginning or ending point for an INSPECT scan cycle. A CHARACTERS phrase, ALL phrase, or LEADING phrase can have a single BEFORE phrase, a single AFTER phrase, or one BEFORE phrase and one AFTER phrase in either order. BEFORE specifies that scanning is up to but not including the character or characters matching delim-string. If INSPECT does not find delim-string in source-string, it scans all of source-string. AFTER specifies that scanning starts at the position immediately following the character or characters matching delim-string. If INSPECT does not find delim-string in source-string, it does not scan source-string . INITIAL is for documentation only and has no effect. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -108 Procedure Division Verbs INSPECT TALLYING REPLACING delim-string is the identifier of any type of elementary item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. ALL specifies that all occurrences of compare-string are tallied. LEADING specifies scanning for consecutive occurrences of compare-string beginning at the current position within source-string. compare-string is the identifier of an elementary data item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant (except one beginning with ALL), in which case it represents one character. The comparestring is the character-string being sought. replacing-phrase REPLACING absolute-replacement matching-replacement VST169.vsd absolute-replacement CHARACTERS BY replace-string position VST170.vsd CHARACTERS specifies that any character in source-string can be replaced, regardless of its value. If you use CHARACTERS, replace-string and delim-string must each be one character in length. replace-string is the identifier of an elementary item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -109 Procedure Division Verbs INSPECT TALLYING REPLACING position BEFORE AFTER delim-string INITIAL VST167.vsd marks a starting and ending place for a replacement cycle. It follows the same item rules as replace-string. A CHARACTERS phrase, ALL phrase, LEADING phrase, or FIRST phrase can have a single BEFORE phrase, a single AFTER phrase, or one BEFORE phrase and one AFTER phrase in either order. BEFORE specifies that scanning is up to but not including the character or characters matching delim-string. If INSPECT does not find delim-string in source-string, it scans all of source-string. AFTER specifies that scanning starts at the position immediately following the character or characters matching delim-string. If INSPECT does not find delim-string in source-string, it does not scan source-string . INITIAL is for documentation only and has no effect. delim-string is the identifier of an elementary item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -110 Procedure Division Verbs INSPECT TALLYING REPLACING matching-replacement ALL LEADING FIRST compare-string BY replace-string position VST172.vsd defines the character-string being scanned for. ALL specifies that all occurrences of compare-string are replaced. LEADING specifies scanning for consecutive occurrences of compare-string beginning at the current position within source-string. For example, REPLACING LEADING “0” replaces only the first three zeros in “000120020.” FIRST specifies that only the first occurrence of compare-string is replaced. compare-string is the identifier of any type of elementary item with USAGE DISPLAY or nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. replace-string is an identifier of any type of elementary item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. When replacestring and compare-string are used together, they must be the same size. position is as described earlier for absolute-replacement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -111 Procedure Division Verbs INSPECT TALLYING REPLACING Usage Considerations: • Action of the INSPECT TALLYING REPLACING Statement The INSPECT TALLYING REPLACING statement is a combination of the INSPECT TALLYING and the INSPECT REPLACING statements. See Usage Considerations: and Usage Considerations:. • Difference Between INSPECT TALLYING REPLACING and INSPECT TALLYING Followed by INSPECT REPLACING The only difference between an INSPECT TALLYING REPLACING statement and an INSPECT TALLYING statement followed immediately by an INSPECT REPLACING statement with the same source-string s, compare-string s, and delim-string is the side effects. Each form of the INSPECT statement performs all operand identification at the beginning of execution. The INSPECT TALLYING REPLACING statement performs only one operand identification operation, but the INSPECT TALLYING statement followed by the INSPECT REPLACING statement performs operand identification before the INSPECT TALLYING statement and again before the INSPECT REPLACING statement. If subscripts or reference modifiers in any operands of the REPLACING clause use values that the TALLYING phrase changes, the INSPECT TALLYING REPLACING statement works differently than the INSPECT TALLYING statement followed immediately by an INSPECT REPLACING statement. For example, suppose X has the value “AAABBBABAB” and C is an array containing the values 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9. Executing the three statements MOVE 1 TO Y INSPECT X TALLYING Y FOR LEADING "A" INSPECT X REPLACING LEADING "A" BY C (Y) changes the value of X to “333BBBABAB,” because the subscript Y in the REPLACING clause has the value 4 when the INSPECT REPLACING statement begins execution; however, executing the two statements MOVE 1 TO Y INSPECT X TALLYING Y FOR LEADING "A" X REPLACING LEADING "A" BY C (Y) changes the value of X to “000BBBABAB,” because the subscript Y in the REPLACING clause has the value 1 when the INSPECT TALLYING REPLACING statement begins executing. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -112 Procedure Division Verbs INSPECT CONVERTING INSPECT CONVERTING INSPECT CONVERTING performs a character-for-character replacement. It is easier to express such a replacement with the CONVERTING phrase than it is with a series of REPLACING ALL … BY … phrases. INSPECT source-string CONVERTING match VST175.vsd source-string is the identifier of an elementary item or data structure with USAGE DISPLAY. Inspection proceeds from left to right within source-string. match compare-string TO replace-string position VST173.vsd compare-string is the identifier of any type of elementary item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. A character must not appear more than once in compare-string. replace-string is the identifier of any type of elementary item with USAGE DISPLAY or a nonnumeric literal, that defines what to replace the source-string characters with. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. The size of replacestring and compare-string must be the same. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -113 Procedure Division Verbs INSPECT CONVERTING position BEFORE AFTER delim-string INITIAL VST167.vsd marks a starting and ending place for a replacement cycle. It follows the same item rules as replace-string. A CONVERTING phrase can have a single BEFORE phrase, a single AFTER phrase, or one BEFORE phrase and one AFTER phrase in either order. BEFORE specifies that scanning is up to but not including the character or characters matching delim-string. If INSPECT does not find delimstring in source-string, it scans all of source-string. AFTER specifies that scanning starts at the position immediately following the character or characters matching delim-string. If INSPECT does not find delim-string in source-string, it does not scan sourcestring. INITIAL is for documentation only and has no effect. delim-string is the identifier of any type of elementary item with USAGE DISPLAY or a nonnumeric literal. It can be a figurative constant that does not include the keyword ALL, in which case it represents one character. Example 9-41 shifts any lowercase letters found in IN-BUFFER to uppercase letters. Example 9-41. INSPECT CONVERTING Statement INSPECT IN-BUFFER CONVERTING "abcdefghijklmnopqrstuvwxyz" TO "ABCDEFGHIJKLMNOPQRSTUVWXYZ". HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -114 Procedure Division Verbs LOCKFILE Usage Considerations: • Action of the INSPECT CONVERTING Statement The compiler treats a statement of the form INSPECT source-string CONVERTING compare-string TO replace-string as if it were a statement of the form INSPECT source-string REPLACING ALL comp-char-1 BY repl-char-1 ALL comp-char-2 BY repl-char-2 ... In the INSPECT CONVERTING statement, the n th character of comparestring corresponds to the n th character of replace-string. • Restrictions on Overlapping Operands The storage area referenced by compare-string, replace-string, or delim-string cannot be the same as the storage area referred to by sourcestring, and must not overlap the storage area referred to by source-string. Violation of this rule produces unpredictable results. • See these usage considerations in INSPECT TALLYING: ° ° ° How Parameter Categories Affect INSPECT Comparison Operation BEFORE and AFTER Phrases LOCKFILE LOCKFILE prevents other processes from accessing the records in a file. All records remain locked until either: • • • • You use an UNLOCKFILE statement. You close the file. The run unit terminates. You are executing a transaction with TMF and the transaction ends. LOCKFILE file-name TIME LIMIT wait-time VST176.vsd file-name is the file description name of the file to lock. For LOCKFILE to work, file-name must specify a disk file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -115 Procedure Division Verbs LOCKFILE wait-time is a numeric literal or the name of a numeric data item. Its value must have no more than seven digits preceding any decimal point. Any fractional portion is rounded to two decimal places. For example: 03 WAIT-TIME PIC 9(7)V9(2) COMPUTATIONAL. A nonnegative wait-time is the number of seconds within which the LOCKFILE operation must finish. If the LOCKFILE operation does not finish within that time, it terminates with no error message. The I-O status code has the value “30” and the GUARDIAN-ERR register has the value 40. If wait-time is negative or no wait-time is specified, the LOCKFILE operation has no time limit. The program can wait indefinitely. If file-name was not opened with a TIME LIMITS phrase, including wait-time in the LOCKFILE statement causes a run-time error. Usage Considerations: • Action of the LOCKFILE Statement The LOCKFILE statement has no effect if the process has already locked the file or if the file is not a disk file. Whether effective or not, the LOCKFILE statement does not affect the key of reference, the file position indicator, or the contents of the record area associated with the file. • I-O Status Code If the file has an associated file-status data item, the LOCKFILE statement assigns it an appropriate I-O status code. The possible I-O status codes that result from LOCKFILE operations are: • I-O Status Code Meaning “00” LOCKFILE executed successfully. “30” Either the specified (nonnegative) time limit elapsed before the LOCKFILE completed (in which case, GUARDIAN-ERR is also set to 40), or the LOCKFILE operation failed due to non-COBOL causes. The file might or might not have been locked. “42” The file was not open. “90” The wait-time is nonnegative but the file was not opened with time limits enabled. An error message is delivered to the process’s home terminal. One File Open Under Multiple Names If a file-system file is opened twice or more times, using two or more distinct file descriptions, only one of the file descriptions can have the file locked at a time. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -116 Procedure Division Verbs • LOCKFILE Declarative Procedures If a declarative procedure applies to the file and the time interval expires, the declarative procedure is performed, and program execution continues with the statement following the one terminated (see Expired Time Limit). If error message 42 or 90 is returned after the declarative procedure executes, the run unit terminates abnormally. • Interaction of LOCKFILE and READ LOCK Statements If your process executes a READ LOCK statement on a file that it or any other process has locked with a LOCKFILE statement, or your process executes a LOCKFILE statement against a file that has an outstanding READ LOCK, the TIME LIMIT phrase determines what happens. If the second statement attempting to lock the file has a TIME LIMIT phrase, it keeps trying to lock the file until the time limit expires. Either it fails and then times out or it succeeds in locking the file. If the second statement attempting to lock the file has no TIME LIMIT phrase, it suspends execution until the statement succeeds because the contending lock is removed or until the program is terminated by an external agency (such as the TACL command STOP). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -117 Procedure Division Verbs Example 9-42. LOCKFILE Statement With TIME LIMIT Phrase SELECT IN-MASTER-FILE ASSIGN ... ... FILE STATUS IS IN-MASTER-STATUS. ... FD IN-MASTER-FILE. ... PROCEDURE DIVISION. DECLARATIVES. DECL SECTION. USE AFTER ERROR PROCEDURE ON IN-MASTER-FILE. DECL-ROUTINE. IF GUARDIAN-ERR NOT = 40 STOP RUN END-IF END DECLARATIVES. ... OPEN INPUT IN-MASTER-FILE WITH TIME LIMITS SHARED LOCKFILE IN-MASTER-FILE TIME LIMIT WAIT-TIME IF IN-MASTER-STATUS NOT = "00" IF GUARDIAN-ERR = 40 PERFORM RECOVER-MASTER-LOCK END-IF END-IF PERFORM UP-DATE-MASTER UNTIL DONE MOVE 0 TO M-FLAG UNLOCKFILE IN-MASTER-FILE ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -118 LOCKFILE Procedure Division Verbs MERGE MERGE MERGE combines two or more files into another file, ordered by the same key. MERGE is performed by the FastSort utility, using files that are not open to the COBOL program. MERGE opens, reads, writes, and closes these files. MERGE can return records to an output procedure that can then write them to some file that is open to the COBOL program. MERGE merge-file key-specifier COLLATING SEQUENCE phrase USING phrase output-specifier VST177.vsd merge-file is a sort-merge file description (SD) name. merge-file can have variable-length or fixed-length records. Its record description entry defines the data item or items used as the key or keys. key-specifier ASCENDING ON DESCENDING key KEY VST178.vsd ASCENDING specifies ascending merge order. DESCENDING specifies descending merge order. key is a data item to be used as a merge key. If merge-file has variable-length records, key must refer to data within the first x character positions of the record, where x is the minimum record size for merge-file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -119 Procedure Division Verbs MERGE COLLATING SEQUENCE phrase SEQUENCE COLLATING alphabet-name IS VST179.vsd specifies a collating sequence for sorting. alphabet-name must be associated with a collating sequence in the SPECIAL-NAMES paragraph of the Environment Division (see SPECIAL-NAMES Paragraph). USING phrase USING merge-in-1 merge-in-2 merge-in-n VST180.vsd merge-in-1 merge-in-2 merge-in-n are file description (FD) names. Multiple-reel tape files are permitted. The files can have variable-length or fixed-length records. If merge-file has variable-length records, then the records of merge-in-1, merge-in-2, and merge-in-n must not be shorter than the shortest record that merge-file can have or longer than the longest record that mergefile can have. If merge-file has fixed-length records, then the records of merge-in-1, merge-in-2, and merge-in-n must not be greater than that fixed length. If a record of merge-in-1, merge-in-2, or merge-in-n is shorter than the fixed length of each merge-file record, then the shorter record is spacepadded on the right when it is released to merge-file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -120 Procedure Division Verbs MERGE output-specifier OUTPUT PROCEDURE outproc-1 IS THROUGH outproc-2 THRU GIVING merge-out VST181.vsd specifies the procedure to which the merge operation is to deliver the records of the merged files, in order. outproc-1 is the paragraph-name or section-name of the first (and maybe only) paragraph or section of the procedure to which the merge operation delivers the records of the merged files. outproc-2 is the paragraph-name or section-name of the last paragraph or section of the procedure in the group of procedures to which the merge operation delivers the records of the merged files. merge-out is a file description (FD) name, the name of a file that results from the merge operation. The merge-out file can have variable-length or fixed-length records. If merge-out has fixed-length records, any record in merge-file that is shorter than that fixed length is space-padded on the right when that record is returned to merge-out. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -121 Procedure Division Verbs MERGE Usage Considerations: • Placement of MERGE Statements A MERGE statement cannot appear in the Declaratives Portion of the Procedure Division. • Files Specified in the MERGE Statement You can merge to and from these types of files: ° ° ° ° Disk files Blocked tape files Multiple-reel tape files Tape files on a multiple-file reel The files specified in the MERGE statement are subject to these restrictions: • ° ° ° Every file record must contain all of the key fields. ° Files that appear in the same MERGE statement cannot appear in a SAME AREA or SAME SORT-MERGE AREA clause. ° Except for merge-out files, files that appear in the same MERGE statement cannot appear in the SAME RECORD AREA clause. ° A merge-in-1, merge-in-2, or merge-in-n file whose SELECT clause includes the OPTIONAL phrase must be present at execution time. A file name cannot appear more than once in the same MERGE statement. Two files of a multiple-file tape reel cannot appear in the same MERGE statement. Merge Keys Each merge key is subject to these restrictions: ° The data item specified by key must be described within a record associated with merge-file. When merge-file has more than one record description entry, a merge key data item can be defined within any one of those entries. ° No key can have an OCCURS clause or be subordinate to an item that has an OCCURS clause. ° No key can have a variable size (that is, have an OCCURS DEPENDING clause in the description of a subordinate item). Keys are listed from left to right within the MERGE statement in order of decreasing significance (that is, the first key is the most significant and the last key is the least significant). ASCENDING and DESCENDING phrases do not affect keys’ significance. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -122 Procedure Division Verbs MERGE When a key is in an ASCENDING phrase, the merged sequence is from the record with the lowest value in the key to the record with the highest value. When a key is in a DESCENDING phrase, the merged sequence is from the record with the highest value in the key to the record with the lowest value. In both cases, the rules for comparison of operands in a relation condition determine which value is higher. The results of the merge operation are predictable only when the records in each of the input files are ordered as described in the key-specifier phrases. The PROGRAM COLLATING SEQUENCE clause affects merge operations. • Output Procedure The output procedure is outproc-1 or outproc-1 through outproc-2. The output procedure must have a RETURN statement. An output procedure can be any procedure needed to select, modify, or copy the records that the RETURN statement makes available to merge-file one at a time in merged order. The range of an output procedure includes statements that execute due to transfer of control by CALL, EXIT, GO TO, and PERFORM statements in the range of the output procedure and statements in declarative procedures that execute as a result of execution of statements in the range of the output procedure. The range of an output procedure must not cause the execution of any of these statements: ° ° ° A MERGE, RELEASE, or SORT statement A RETURN statement that specifies a sort-merge file other than merge-file A statement that manipulates merge-in-1, merge-in-2, merge-in-n, or merge-out or uses the record area associated with one of these files If the MERGE statement is in a section that is not in an independent segment (a segment whose segment-number is from 00 through 49), then any output procedures must either be totally within dependent segments or they must be wholly contained in a single independent segment. If the MERGE statement is in an independent segment (a segment whose segment-number is from 50 through 99), then any output procedures must either be totally within dependent segments or they must be wholly contained in the same independent segment that contains the MERGE statement. • Execution Phases The execution of a MERGE statement consists of an input-and-merge phase and an output phase. • Input-and-Merge Phase The input-and-merge phase transfers records from the input files merge-in-1, merge-in-2, and merge-in-n to merge-file in the order specified by the merge keys and the collating sequence alphabet-name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -123 Procedure Division Verbs MERGE When the MERGE statement begins execution, merge-file and the input files must be closed but not locked. The input-and-merge phase performs an implicit OPEN statement on merge-file and each of the input files. The input-andmerge phase opens each input file in INPUT mode, performs implicit READ NEXT statements to retrieve their records, and performs implicit RELEASE statements to release the records to the merge-file. The MERGE statement determines the merging logic by retrieving the first record from each input file to form a set of candidate records. After selecting the proper candidate to transfer to merge-file, the merging logic retrieves the next record from that input file, if any, to replace it. This process continues until all input files are exhausted. The candidate records are first ranked in accordance with their values for the most significant key. When two or more records have equal values for the current key, that subset is then ranked in accordance with the record values for the next most significant key, and so on. When all records have been merged, the input-and-merge phase performs an implicit CLOSE statement on each input file. If the MERGE statement has an OUTPUT PROCEDURE phrase, the close operations occur after the specified procedure completes execution and returns control to the MERGE statement. • Output Phase If the MERGE statement has an OUTPUT PROCEDURE phrase, the output phase transfers the merged records to the output procedure using an implicit PERFORM statement. The implicit PERFORM retrieves the merge-file records by executing implicit RETURN statements. When the implicit PERFORM statement finishes executing, control returns to the merge operation. If the MERGE statement has a GIVING phrase, the output phase transfers the merged records to one or more merge-out files. When the MERGE statement begins execution, each merge-out file must be closed but not locked. The output phase uses implicit OPEN statements to open each merge-out file in OUTPUT mode. Then the output phase executes implicit RETURN statements to retrieve records from the merge file and implicit WRITE statements to release them to the merge-out files. Finally, the output phase uses implicit CLOSE statements to close the merge-out files. Regardless of whether the MERGE statement has an OUTPUT PROCEDURE phrase or a GIVING phrase, the merge operation uses an implicit CLOSE statement to close merge-file after the output phase ends. Then the MERGE statement terminates execution. The implicit OPEN and CLOSE statements are equivalent to OPEN and CLOSE statements without optional phrases. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -124 Procedure Division Verbs • MERGE How the Scratch File Is Determined Note. If a scratch file is specified but its value is all spaces, assume that no scratch file was specified. • ° If COBOL_SET_SORT_PARAM_TEXT_ specifies a SCRATCH-FILE, then that file is the scratch file. ° If the SELECT statement associated with merge-file specifies the =_SORT_DEFAULTS DEFINE as the define-name-literal, then: ° If the =_SORT_DEFAULTS DEFINE exists and specifies a scratch file, then that file is the scratch file. ° If the =_SORT_DEFAULTS DEFINE exists but does not specify a scratch file, then a temporary file on the volume $SYSTEM is the scratch file. ° If no =_SORT_DEFAULTS DEFINE exists, then a temporary file on the volume $SYSTEM is the scratch file. ° For more information on the =_SORT_DEFAULTS DEFINE, see Establishing Parameters With =_SORT_DEFAULTS DEFINE. ° If the SELECT statement associated with merge-file does not specify the =_SORT_DEFAULTS DEFINE as the define-name-literal, then the file that the SELECT statement specifies is the scratch file. How the Volume of the Swap File Is Determined Note. If a swap file is specified but its value is all spaces, assume that no swap file was specified. The operating system assigns a swap file to swap pages in and out of memory while the compiler is running. The swap file mirrors all of the data areas that the compiler uses. The ideal swap file is a fast device that is neither busy nor mirrored. To redirect the swap file, give define-name-literal the value =_SORT_DEFAULTS. The swap file is a temporary file with a volume but no subvolume. If you specify a swap file, including a volume, the volume is used but the file-id is not. If you specify only a file-id, the default volume is used. ° If COBOL_SET_SORT_PARAM_TEXT_ specifies a SWAP-FILE, then the swap file is created on that file’s volume. ° If the SELECT statement associated with merge-file specifies the =_SORT_DEFAULTS DEFINE as the define-name-literal, then: ° If the =_SORT_DEFAULTS DEFINE exists and specifies a swap file, then the swap file is created on that file’s volume. ° If the =_SORT_DEFAULTS DEFINE exists but does not specify a swap file, then the swap file is created on the volume used for the scratch file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -125 Procedure Division Verbs ° MERGE If no =_SORT_DEFAULTS DEFINE exists, then the swap file is created on the volume used for the scratch file. For more information on the =_SORT_DEFAULTS DEFINE, see Establishing Parameters With =_SORT_DEFAULTS DEFINE. ° If the SELECT statement associated with merge-file does not specify the =_SORT_DEFAULTS DEFINE as the define-name-literal, then the swap file is created on the volume of the file that the SELECT statement specifies. In Example 9-43, a MERGE statement merges two files to produce a third. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -126 Procedure Division Verbs Example 9-43. MERGE Statement INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT PARTS-ON-HAND ASSIGN TO "H215432.ONHAND" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. SELECT PARTS-RECEIVED ASSIGN TO "H215432.RECD" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. SELECT PARTS-TOGETHER ASSIGN TO "H215432.TGTHR" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. SELECT MERGER ASSIGN TO "$HISPD.#TEMP". ... DATA DIVISION. FILE SECTION. FD PARTS-ON-HAND RECORD CONTAINS 120 CHARACTERS LABEL RECORDS ARE OMITTED. 01 P-O-H. 05 PARTNO PIC 9(8). ... FD PARTS-RECEIVED RECORD CONTAINS 120 CHARACTERS LABEL RECORDS ARE OMITTED. 01 P-R. 05 PARTNO PIC 9(8). ... FD PARTS-TOGETHER RECORD CONTAINS 120 CHARACTERS LABEL RECORDS ARE OMITTED. 01 P-T. 05 PARTNO PIC 9(8). ... SD MERGER RECORD CONTAINS 120 CHARACTERS. 01 PARTNO PIC 9(8). ... PROCEDURE DIVISION. ... MERGE MERGER ON ASCENDING KEY PARTNO OF MERGER USING PARTS-ON-HAND PARTS-RECEIVED GIVING PARTS-TOGETHER ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -127 MERGE Procedure Division Verbs MOVE MOVE Form Description MOVE TO Copies data from a data item and stores it in one or more other data items MOVE CORRESPONDING Copies elements of one group to corresponding elements of another group MOVE TO MOVE TO copies data from a data item and stores it in one or more other data items. MOVE sender TO receiver VST182.vsd sender is the literal or the identifier of the data item from which data is copied. receiver is the identifier of a data item to which the data is to be copied. Usage Considerations: • Evaluation of Subscripts and Indexes Subscripts or indexes in sender are evaluated only once, immediately before data is moved to the first receiver. Subscripts or indexes in receivers are evaluated in the order in which the receivers are specified. For example, MOVE A(B) TO B C(B) is equivalent to MOVE A(B) TO temp MOVE temp TO B MOVE temp TO C(B) • MOVE Statements That Are Not Recommended Do not attempt these moves: ° SPACE, alphanumeric edited, or alphabetic data item to numeric or numeric edited data item ° ZERO, numeric literal, numeric, or numeric edited data item to alphabetic data item HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -128 Procedure Division Verbs • MOVE TO MOVE Conventions Table 9-3 summarizes the legal MOVE TO statements by category of sending and receiving data items. Data is converted and stored according to the category of the receiving data item. Table 9-3. Summary of Legal Moves Category of Receiving Data Item Category of Sending Data Item Alphabetic Alphanumeric Numeric National Alphabetic Yes Yes No No Edited Yes Yes* No No Non-Edited Yes Yes Yes No Integer No Yes Yes No Noninteger No Yes Yes No Edited No Yes Yes No No No No Yes Alphanumeric Numeric National * Although it is possible to move an alphanumeric item to a numeric item, the presence of a nonnumeric character in the data moved makes any operation on the numeric item unpredictable. • Alphabetic, Alphanumeric, Alphanumeric Edited, or National Receiving Data Items Data is stored beginning at the leftmost position of receiver. If sender is shorter than receiver, spaces are filled according to standard alignment rules. If sender is longer than receiver, the value of sender is truncated on the right to the length of receiver. Any editing required by receiver is performed unless sender is a group data item. If sender is a signed numeric data item, the operational sign is not moved to receiver. If sender is described with the SEPARATE phrase in the SIGN clause, the size of sender is considered to be one character less than the actual size of sender. If sender is a numeric item with the scaling factor (P ) in its rightmost digits, positions containing P are considered to contain zeros. If sender is a numeric item with decimal digits (that is, sender has V in its PICTURE clause), the decimal point is ignored and sender is treated as if it were an alphanumeric item whose size is equal to the number of 9 s in the PICTURE clause. If its USAGE is not DISPLAY, it is converted to DISPLAY for the move operation. For example: PIC 999V99 VALUE 123.45 is treated as if it were PIC X(5); that is, as the value 12345. If the number of digits in sender is greater than 18 (for example, when a NUMVAL function is used), the leftmost 18 digits are moved and any to the right of this are discarded. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -129 Procedure Division Verbs MOVE TO The COBOL standard requires that the numeric item have no decimal positions. HP allows this as an extension. If an elementary receiver is described as JUSTIFIED, see JUSTIFIED Clause. • Numeric or Numeric Edited Receiving Data Items Data is aligned by decimal point and filled with zeros as necessary. If receiver is signed, the sign of sender is moved to receiver. If sender has no sign, the new sign of receiver is positive. If receiver is not signed, the absolute value of sender becomes the new value of receiver. If sender is alphanumeric, its value is treated as an unsigned numeric integer. If sender is numeric-edited, the operand’s unedited numeric value is determined (it can be signed). The unedited numeric value of sender is moved to receiver. • Group MOVE Statements Group MOVE statements (MOVE statements in which sender, receiver, or both are data structures) are treated as alphanumeric-to-alphanumeric moves, with no data conversion. Receiving items are filled without regard to individual or subordinate items in either sender or receiver s. If a receiver is an elementary item defined with a JUSTIFIED clause, justification does occur. If sender is a national data item, its size is assumed to be twice the number of national characters. Verify the receiving data structure can hold all of the national characters. In Example 9-44, several MOVE TO statements set the values of two records in working storage. Example 9-44. MOVE TO Statements (page 1 of 2) WORKING-STORAGE SECTION. 01 RECORD-IN. 03 ITEM-A PIC X(5) VALUE "AAAAA". 03 ITEM-B PIC 99V99 VALUE "2.38". 03 ITEM-C PIC ZZ,ZZ9.99. ... 01 TEMPS. 03 TEMP1 PIC X(4). 03 TEMP2 PIC X(8). 03 TEMP3 PIC 9(5)V999. 03 TEMP4 PIC 9V9. 03 TEMP5. 05 T PIC 99 OCCURS 12 TIMES. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -130 Procedure Division Verbs MOVE TO Example 9-44. MOVE TO Statements (page 2 of 2) PROCEDURE DIVISION. BEGIN-PROCESSING. MOVE ITEM-A TO TEMP1 * TEMP1 is set to "AAAA" MOVE ITEM-A TO TEMP2 * TEMP2 is set to "AAAAA " MOVE ITEM-B TO TEMP3 * * TEMP3 is set to 00002v380 where "v" marks the decimal location MOVE ITEM-B TO TEMP4 * * * TEMP4 is set to 2v3 where "v" marks the decimal location MOVE SPACES TO RECORD-IN RECORD-IN is set to " " (9 spaces) MOVE ZEROS TO ITEM-B ITEM-B is set to 00v00 where "v" marks the decimal location MOVE 5280 TO ITEM-C. ITEM-C is set to " 5,280.00" * * MOVE ITEM-C TO TEMP-3. TEMP-3 is set to 05280v000 where "v" marks the decimal location * * * * MOVE ZEROS TO TEMP-5. * * * * * * * * * Each 2-digit T in TEMP-5 is set to the 2-character value "00". Do not move ZEROS to any group containing COMP or NATIVE-n items, because the operation delivers characters. Do not move LOW-VALUES to a group of numeric items -- instead use INITIALIZE ... REPLACING NUMERIC DATA BY ZERO HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -131 Procedure Division Verbs MOVE CORRESPONDING MOVE CORRESPONDING MOVE CORRESPONDING copies elements of one group to corresponding elements of another group. Groups of data correspond if they have the same names and qualifier names, beyond the group-names in the MOVE statement, and if they meet restraints explained under CORRESPONDING Phrase. Caution. MOVE CORRESPONDING is not recommended, because minor changes to one group can change the correspondence between its elements and those of the other group, and this is difficult to detect. If someone adds a new name to a group, the new name might be included in unintended move operations. MOVE CORRESPONDING group-1 TO group-2 CORR VST183.vsd group-1 is the group-name of the data to be copied. group-2 is the group-name to which the data is to be copied. MULTIPLY Form Description MULTIPLY BY Multiplies one data item by one or more other data items and stores the result(s) in the other data item(s); for example, the statement MULTIPLY A BY B C D means store A x B in B, A x C in C, and A x D in D MULTIPLY GIVING Multiplies two data items and stores the product in one or more other data item(s); for example, the statement MULTIPLY A BY B GIVING C D E means store A x B in C, D, and E HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -132 Procedure Division Verbs MULTIPLY BY MULTIPLY BY MULTIPLY BY multiplies one data item by one or more other data items and stores the result(s) in the other data item(s); for example, the statement MULTIPLY A BY B C D means store A x B in B, A x C in C, and A x D in D. MULTIPLY BY multiplicand multiplier ROUNDED SIZE ERROR imperative-stmt-1 ON NOT SIZE ERROR ON imperative-stmt-2 END-MULTIPLY VST184.vsd multiplicand is a numeric literal or the identifier of an elementary numeric data item. multiplier is the identifier of an elementary numeric data item. ROUNDED specifies that the product is to be rounded before being stored as the new value of multiplier. imperative-stmt-1 is an imperative statement to be executed when a size error is detected in the multiplication or in storing the product in multiplier. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -133 Procedure Division Verbs MULTIPLY BY imperative-stmt-2 is an imperative statement to be executed when no size error is detected in the multiplication or in storing the product in multiplier. END-MULTIPLY ends the scope of the MULTIPLY statement and makes it a delimited-scope statement. If you omit END-MULTIPLY but include the SIZE ERROR or NOT SIZE ERROR phrase, the MULTIPLY statement is a conditional statement and ends at the next period separator. Usage Considerations: • Mathematics The statement MULTIPLY A BY B C D means store A x B into B, A x C into C, and A x D into D. • Repeating a Multiplier If more than one multiplier specifies the same data item, the final value of that data item reflects more than one multiplication by multiplicand. For example, MULTIPLY 4 BY A B B results in A being replaced by 4 x A and B being replaced by 16 x B. • Operand Identification For each multiplier, operand identification occurs just prior to the multiply-and store operation. For example, in the statement MULTIPLY 4 BY A B C(B) the subscript is not evaluated until B has been multiplied by 4. See Operand Identification. • Arithmetic Operations See Arithmetic Operations for information on data conversion and alignment, intermediate results, multiple results (and subscript evaluation), and incompatible data. • Precision If you omit the SIZE ERROR phrase, arithmetic overflow can cause the run unit to terminate abnormally. For information on precision of multiplication, see Arithmetic Precision. • ROUNDED and SIZE ERROR Phrases See ROUNDED Phrase and SIZE ERROR Phrase for information on these. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -134 Procedure Division Verbs MULTIPLY BY Example 9-45 converts a length in feet to a length in inches. Example 9-45. MULTIPLY BY Statement 05 LENGTH PICTURE S9(6)V9(6). ... MULTIPLY 12 BY LENGTH Example 9-46 converts several dimensions from centimeters to inches, with rounding. Example 9-46. MULTIPLY BY Statement With ROUNDED Phrase 03 CM-TO-INCHES PICTURE S9V99 VALUE 0.39. ... 03 LENGTH 03 WIDTH 03 DEPTH ... MULTIPLY CM-TO-INCHES PICTURE S9(3)V9(2). PICTURE S9(3)V9(2). PICTURE S9(3)V9(2). BY LENGTH ROUNDED WIDTH ROUNDED DEPTH ROUNDED HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -135 Procedure Division Verbs MULTIPLY GIVING MULTIPLY GIVING MULTIPLY GIVING multiplies two data items and stores the product in one or more other data item(s); for example, the statement MULTIPLY A BY B GIVING C D E means store A x B in C, D, and E. MULTIPLY BY multiplicand multiplier GIVING result ROUNDED SIZE ERROR imperative-stmt-1 ON NOT SIZE ERROR ON imperative-stmt-2 END-MULTIPLY VST185.vsd multiplicand is a numeric literal or the identifier of an elementary numeric data item. multiplier is a numeric literal or the identifier of an elementary numeric data item. result is the identifier of an elementary numeric or numeric edited data item that is to receive the product. ROUNDED specifies that the product is to be rounded before being stored in result. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -136 Procedure Division Verbs MULTIPLY GIVING imperative-stmt-1 is an imperative statement to be executed when a size error is detected in the multiplication or in storing the product in result. imperative-stmt-2 is an imperative statement to be executed when no size error is detected in the multiplication or in storing the product in result. END-MULTIPLY ends the scope of the MULTIPLY statement and makes it a delimited-scope statement. If you omit END-MULTIPLY but include the SIZE ERROR or NOT SIZE ERROR phrase, the MULTIPLY statement is a conditional statement and ends at the next period separator. Usage Considerations: • Mathematics The statement MULTIPLY A BY B GIVING C D E means store A x B into C, D, and E. The values of A and B do not change. • Operand Identification For each result, operand identification occurs just prior to the storage operation. For example, in the statement MULTIPLY A BY B GIVING C D(C) the subscript is not evaluated until C has been set to A x B. See Operand Identification. • Arithmetic Operations See Arithmetic Operations for information on data conversion and alignment, intermediate results, multiple results (and subscript evaluation), and incompatible data. • Precision If you omit the SIZE ERROR phrase, arithmetic overflow can cause the run unit to terminate abnormally. For information on precision of multiplication, see Arithmetic Precision. • ROUNDED and SIZE ERROR Phrases See ROUNDED Phrase and SIZE ERROR Phrase for information on these. • Edited Result The MULTIPLY GIVING statement can produce an edited result, as Example 9-47 shows. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -137 Procedure Division Verbs OPEN Example 9-47. MULTIPLY GIVING Statement 03 03 03 03 UNIT-PRICE PICTURE S9(5)V999 COMPUTATIONAL. ORDERED PICTURE S9(5) COMPUTATIONAL. NET-PRICE PICTURE S9(10)V999 COMPUTATIONAL. NET-PRICE-DSP PICTURE $$,$$$,$$$,$$$.99. ... MULTIPLY UNIT-PRICE BY ORDERED GIVING NET-PRICE-DSP ROUNDED NET-PRICE OPEN OPEN makes a file accessible for input, output, or both. OPEN associates a COBOL file name within the program with a file name known to the file system. The NonStop operating system treats processes as files, so an HP COBOL program can open a terminal or another process as a file. The mode in which such files are opened determines how they are treated (see Table 4-4). OPEN file-specification VST186.vsd file-specification INPUT OUTPUT I-O EXTEND input-file-description output-file-description i-o-file-description extend-file-description VST187.vsd INPUT specifies that the file or files in input-file-description are being opened for reading only. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -138 Procedure Division Verbs OPEN input-file-description for a sequential, relative, indexed, or queue file: infile TIME LIMITS WITH SHARED SYNCDEPTH PROTECTED «REVERSED» EXCLUSIVE sync NO REWIND WITH VST188.vsd for a line sequential file: infile SHARED PROTECTED EXCLUSIVE VST627.vsd infile is the file description file name of a file to open in INPUT mode, for read operations only. TIME LIMITS allows you to use the TIME LIMIT phrase in LOCKFILE, READ, and START statements that apply to infile. SHARED allows other processes to read or write the file while this process is open. SHARED is the default for terminals. PROTECTED allows other processes to read but not write the file while this process is open. PROTECTED is the default for input files that are not terminals. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -139 Procedure Division Verbs OPEN EXCLUSIVE prevents other processes from reading or writing the file while this process is open. EXCLUSIVE is the default for all other files. sync is a numeric literal that: • • • Specifies the number of write requests that cannot be tried again whose I-O status code is to be recorded by the file system. Determines the number of write operations that the primary process of a process pair can perform on the file without doing a checkpoint to its backup process. If sync is 0, no checkpointing or automatic disk recovery is performed. To allow recovery from the failure of a processor that is controlling the disk during a write operation, the value of sync must be 1 or greater. The default value of sync is 1. REVERSED Note. The 1985 COBOL standard classifies REVERSED as obsolete, so you are advised not to use it. is ignored with a warning. NO REWIND specifies that a tape is not to be rewound. This phrase applies to singlereel, single-file tapes; single-reel, multiple-file tapes; and multiple-reel, single-file tapes. If NO REWIND is specified for other types of files, it is ignored. If NO REWIND is not specified for a tape file, the tape is rewound. The tape must be positioned at the beginning of the file prior to the execution of the OPEN statement. No file repositioning is done. OUTPUT specifies that the file or files in output-file-description are being opened for writing only. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -140 Procedure Division Verbs OPEN output-file-description for a sequential, relative, indexed, or queue file: outfile TIME LIMITS WITH SHARED SYNCDEPTH PROTECTED sync NO EXCLUSIVE REWIND WITH VST189.vsd for a line sequential file: outfile SHARED PROTECTED EXCLUSIVE VST628.vsd outfile is the file description file name of a file to open in OUTPUT mode, for write operations only. TIME LIMITS SHARED PROTECTED EXCLUSIVE sync NO REWIND are the same as described earlier for infile. I-O specifies that the file or files in i-o-file-description are being opened for reading or writing. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -141 Procedure Division Verbs OPEN i-o-file-description for a sequential, relative, indexed, or queue file: iofile TIME LIMITS WITH SYNCDEPTH SHARED sync PROTECTED EXCLUSIVE VST190.vsd for a line sequential file: iofile SHARED PROTECTED EXCLUSIVE VST626.vsd iofile is the file description file name of a file to open in I-O mode, for both read and write operations. TIME LIMITS SHARED PROTECTED EXCLUSIVE sync are the same as described earlier for infile. EXTEND specifies that the file or files in extend-file-description are being opened for writing additional data following any existing data. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -142 Procedure Division Verbs OPEN extend-file-description for a sequential, relative, indexed, or queue file: extfile TIME LIMITS WITH SHARED SYNCDEPTH sync PROTECTED EXCLUSIVE VST191.vsd for a line sequential file: extfile SHARED PROTECTED EXCLUSIVE VST629.vsd extfile is the file description file name of a sequential file to open in EXTEND mode, for write operations that append records to the file. The file is positioned after the last logical record when opened. All operations on the file must be write operations, as if the file had been opened in OUTPUT mode. If the file is an Enscribe unstructured file, its size must be a multiple of the record size. TIME LIMITS SHARED PROTECTED EXCLUSIVE sync are the same as described earlier for infile. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -143 Procedure Division Verbs OPEN Usage Considerations: • Associating COBOL File Names With System File Names Before you can open a file, you must associate its COBOL file name with the name of a system file name, using one of: • ° The ASSIGN clause of the file-control entry for the COBOL file (see FILE-CONTROL Paragraph) ° The TACL command ASSIGN (see ASSIGN Command) ° A DEFINE of the class MAP, SPOOL, or TAPE (see DEFINEs) ° The COBOLASSIGN or COBOL_ASSIGN_ routine (see COBOLASSIGN and COBOL_ASSIGN_) Devices That You Can Open The OPEN statement can open devices that accept normal read and write operations (as opposed to read and write operations that require special control information). This table shows which file organizations are compatible with which devices: • File Organization Devices Allowed Device Type Numbers Relative, indexed, or queue Disk file 3 Sequential without LINAGE Process $RECEIVE Disk file Tape Printer Page mode terminal Envoy line Card reader X25 treated as a process COMM system manager 0 2 3 4 5 6 7 8 9 50 Sequential with LINAGE Process Printer 0 5 Successful and Unsuccessful Open Operation Execution of an OPEN statement sets an I-O status code for each file specified in the statement. Successful opening of a file sets the I-O status code of that file to “00,” “05,” “07,” or “97.” Unsuccessful opening of a file sets the I-O status code to one of the values in Table 9-4 and causes execution of any applicable USE AFTER EXCEPTION CONDITION procedure. If you declared a file-status data item for a file (see FILE-CONTROL Paragraph), the process stores the I-O status code in that data item. For an extensive discussion of I-O status codes, see I-O Status Code. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -144 Procedure Division Verbs OPEN Table 9-4. I-O Status Codes for Unsuccessful Open Operations I-O Status Code Unsuccessful Open Operation “30” One of: • • • • The file was to be opened for OUTPUT and an existing disk file with unsuitable attributes cannot be purged. The file was to be opened for OUTPUT and the data in an existing disk file cannot be purged. The file was to be opened for EXTEND and the file cannot be positioned at its end. The open operation failed due to some cause outside COBOL. “35” The file was to be opened for INPUT, I-O, or EXTEND; the file is not optional; and the file does not exist. “37” One of: • • • The file was to be opened for INPUT, but the device is not suitable for INPUT. The file was to be opened for OUTPUT, but the device is not suitable for OUTPUT. The file was to be opened for I-O, but the device is not suitable for I-O (both input and output). Only disks and terminals can be opened for I-O. “38” The file is locked. “39” The attributes of the file under the file system do not correspond to the attributes specified for the file in the program, for example: • • • • • • The file was to be opened for INPUT but it is assigned to a printer device. The file description includes a LINAGE clause, but the file is assigned to a tape drive. The file description includes a MULTIPLE FILE TAPE clause, but the file is not assigned to a tape drive. The file is described as having keys, but the file is assigned to a nondisk file. The prime record key attributes of a disk file are inconsistent with the description for the COBOL file. The alternate record key attributes of a disk file are inconsistent with the description for the COBOL file. “41” The program already has that file open, or the file is one of several on a tape reel and another of the files on the reel is open. “91” The file is an EDIT format, unstructured disk file and the call to the operating system routine that reads EDIT files failed. The open operation cannot allocate a resource required to process the file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -145 Procedure Division Verbs • OPEN Labeled Files When the LABEL RECORDS clause in the file description entry indicates that label records are present, the beginning file or reel labels are processed in accordance with the conventions for the specified open mode. If the file is opened for INPUT or EXTEND, the label records are verified. If the file is opened for OUTPUT, the label records are created. If the device assigned is not a tape, the LABEL RECORDS clause is ignored. • File Position Indicator The file position indicator specifies the next record to be accessed within the opened file during certain sequences of input-output operations. For files opened for INPUT or I-O, it is defined to be just before the first record in the file. For files opened for OUTPUT or EXTEND, it is undefined. When a file is opened for OUTPUT, run-time routines position the file at its beginning point. The first WRITE statement executed for the file creates the first logical record in the file. When a file is opened for EXTEND, run-time routines position the file to point immediately following the last existing logical record, which is defined: File Organization Last Existing Record Sequential Last record written to the file Relative Existing record with highest relative record number Indexed or queue Existing record with highest prime record key value If a file opened for EXTEND is empty, the first WRITE statement executed for the file creates the first logical record. If the file is not empty, the first WRITE statement executed for the file creates the successor record to the current last record. If a file opened for EXTEND is an Enscribe unstructured file, its size must be a multiple of the record size. • Key of Reference For a relative file, the key of reference is the relative key. For an indexed or queue file, the key of reference is the prime record key. • Locked System Files An HP COBOL program cannot open a system file that it closed and locked earlier in its current execution. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -146 Procedure Division Verbs • OPEN Opening a File Multiple Times, Simultaneously An HP COBOL program can open one system file under more than one COBOL file name. This is particularly helpful when you are developing a server. You can open $RECEIVE twice—once for INPUT and once for OUTPUT—and use TACL ASSIGN commands to make one terminal (or obey file) your input simulator and another terminal your output monitor. If an HP COBOL program opens a file with a certain COBOL file name, it must close that COBOL file (using that COBOL file name) before it can open it again with that COBOL file name. • Operations by Other Input-Output Statements Before any other input-output statement can operate upon a file, an OPEN statement must make the file accessible. Whether you can use a verb to operate on a file depends on the mode in which you open the file (INPUT, OUTPUT, I-O, or EXTEND), the file’s organization and access mode, and the device with which the file is associated. The READ, WRITE, REWRITE, START, and DELETE statements can operate only on files opened with certain options. Table 9-5 summarizes the open modes that make files having different organizations and access modes accessible to these statements. The START and DELETE statements can operate only on files associated with disk devices. The REWRITE statement can operate only on files associated with disk devices. The CLOSE, LOCKFILE, UNLOCKFILE, and UNLOCKRECORD statements can operate on any open file. • Direct Calls to NonStop Operating System I-O Procedures If you open a file with the OPEN statement, do not perform I-O operations on that file by making direct calls to NonStop operating system I-O procedures. If you do, the results are undefined. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -147 Procedure Division Verbs OPEN Table 9-5. I-O Statements You Can Use in Different Open Modes Open Mode I-O Statement INPUT READ ALL WRITE OUTPUT EXTEND ALL ALL REWRITE START I-O Org: R, I Acc: R, D Org: S, R, I Acc: S ALL Org: S*, R, I Acc: S, D Org: S*, R, I Acc: S, D DELETE Org: R, I Org is the file’s organization: I = Indexed or queue R = Relative S = Sequential S* = Sequential (but only for START specifying an alternate key) Acc is the file’s access mode: S = Sequential R = Random D = Dynamic ALL means all organizations and access modes • Nonexistent Files When the INPUT, I-O, or EXTEND phrase applies and the SELECT clause includes the OPTIONAL phrase, the run-time routines determine whether or not the file is present. If the file is not present, one of these occurs: ° If the I-O or EXTEND phrase applies, the open operation creates a file. This creation occurs as if these statements were executed in the order shown: OPEN OUTPUT file-name. CLOSE file-name. The OPEN statement as specified in the source program is then executed. If the file is defined to have alternate keys, the creation attempt fails because you cannot create such files with COBOL verbs. They must be created by an application outside the HP COBOL language (for example, by FUP, the File Utility Program, or by using ENTER to call Enscribe routines). If the creation attempt succeeds, then the file exists. Files Assigned to Disk Devices explains the rules for existing disk files. After a successful open operation that creates a file in the manner described, the I-O status code is “05,” rather than “00” (as it would have been if the operation had opened an existing file). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -148 Procedure Division Verbs OPEN Although no Guardian file is open, if the file might be created later by the current or another program, you must close the file before opening it in COBOL. ° If the INPUT phrase applies, the file position indicator is set to indicate that an optional file is not present. In this case, the I-O status code is “05” and the other steps described later are omitted from the open operation. When the INPUT, I-O, or EXTEND phrase applies, the file is not described as OPTIONAL, and the file is not present at run-time, the open operation terminates immediately with I-O status code “35.” • Files Assigned to Processes Any file assigned to a process must be described with sequential organization without alternate keys in its file-control entry. The mode in which you open the file determines its use. Table 9-6. Open Modes for Files Assigned to Processes Open Mode Action INPUT The file is treated as if it were a terminal. No carriage-control messages are sent to the file, and it cannot have a LINAGE clause in its file description entry. READ, with or without the PROMPT phrase, is the only I-O statement that can be executed on the file; however, prompts are ignored in this open mode. OUTPUT or EXTEND If the process has a device subtype of 31, it is a spooler process, treated like a printer. If the file description entry for the file includes a LINAGE clause, or the file was opened by the routine COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_, it is assumed to be a printer or a spooler process. Carriage-control messages are sent to the file, and it can have a LINAGE clause in its file description entry. WRITE, with or without the ADVANCING phrase, is the only I-O statement that can be executed on the file. Lines of output are held until a subsequent write or close operation, and consecutive spacing operations due to ADVANCING clauses are consolidated to minimized output operations. If the process does not meet the criteria stated earlier, it is assumed to be an ordinary process. No consolidation of operations occurs, and each line is written to the process immediately. No control information or extra blank lines are written to the process. I-O • The file is treated as if it were a terminal. No carriage-control messages are sent to the file, and it cannot have a LINAGE clause in its file description entry. READ and WRITE statements can be executed on the file, but DELETE, REWRITE, and START statements cannot. Files Assigned to Terminals Any file assigned to a terminal must be described with sequential organization without alternate keys in its file-control entry. The mode in which you open the file determines its use. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -149 Procedure Division Verbs OPEN Table 9-7. Open Modes for Files Assigned to Terminals Open Mode Action INPUT No carriage-control messages are sent to the file, and it cannot have a LINAGE clause in its file description entry. READ, with or without the PROMPT phrase, is the only I-O statement that can be executed on the file; however, prompts are ignored in this open mode. OUTPUT or EXTEND No carriage-control messages are sent to the file, and it cannot have a LINAGE clause in its file description entry. WRITE, with or without the ADVANCING phrase, is the only I-O statement that can be executed on the file; however, “ADVANCING mnemonic-name,” if used, is ignored. I-O No carriage-control messages are sent to the file, and it cannot have a LINAGE clause in its file description entry. READ and WRITE statements can be executed on the file, but DELETE, REWRITE, and START statements cannot. • Files Assigned to Disk Devices When the object of an OPEN statement is a disk file, the presence or absence of such a file on disk, as well as both the open mode and the file’s description, determines what happens. In all cases, a disk file cannot be described with a LINAGE clause in its file description entry, nor can a WRITE statement that operates on a disk file include an ADVANCING phrase. • Unstructured Disk Files Unstructured files can be used by a COBOL program in only certain instances: ° ° The program must specify sequential organization with no alternate keys. The file contains zero or more complete records. For this to be true, one of these must be true: ° The COBOL program describes the records of the file as having an even number of characters, and the file size is some integer multiple of the record size. ° The COBOL program describes the records of the file as having an odd number of characters, the file system description of the file includes the “odd-unstructured” attribute, and the file size is some integer multiple of the record size. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -150 Procedure Division Verbs • OPEN ° The COBOL program describes the records of the file as having an odd number of characters, the file system description of the file does not include the “odd-unstructured” attribute, and the file size is some integer multiple of (COBOL record size plus 1). ° If the file code is 101 (EDIT format) because either the file already exists with that code or an ASSIGN command with a CODE phrase has been processed for the file, the file can be opened in INPUT, OUTPUT, or EXTEND modes. Opening the file for OUTPUT deletes any existing records in the file and starts the line numbers at 1, and increments by 1. Opening the file for EXTEND retains existing records and starts the line numbers at 1 greater than the number of the last line in the file, and increments by 1. An EDIT-format file cannot be opened for OUTPUT or EXTEND if the NONSTOP directive has been specified. ° If the file code is 180 (line sequential, available only in the OSS environment). ° The file must be described as having fixed-length records (absence of the rec-1 TO phrase and the VARYING phrase in the RECORD clause). ° If the file is opened in EXTEND mode, the file position indicator is advanced to the end of the file. Structured Disk Files Not Present at Run Time The open mode determines what happens when a structured disk file is not present at run time. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -151 Procedure Division Verbs OPEN Table 9-8. Open Modes for Structured Disk Files Not Present at Run Time Open Mode Action INPUT When the SELECT clause for the file contains the word OPTIONAL, the OPEN statement completes successfully, and COBOL simulates the existence of an empty disk file. If the file is not described as OPTIONAL, the open operation fails. OUTPUT or EXTEND or I-O If a file is described with alternate-record keys, the open operation fails. A COBOL program cannot create files with alternate keys. When the disk file is otherwise described, COBOL creates the file (see Structured Disk Files Present at Run Time). If the device name is associated with a proper file name (such as $volumename.subvolname.filename), then the created file is permanent and continues to exist after the program has closed it. If the device name is not associated with a proper file name (that is, if its name has the form of just a volume name or is a special name like #TEMP), the created file is temporary and disappears when it is closed. The device name can be associated with a proper file name in any of these ways: • • • • By the ASSIGN clause at compile time By an ASSIGN command at run time By a DEFINE of class MAP at run time Structured Disk Files Present at Run Time Certain requirements pertain to all files in this category: ° The organization declared for the file must be consistent with the actual organization of the file (that is, if the file is declared ORGANIZATION SEQUENTIAL, the file must be entry-sequenced; if it is declared ORGANIZATION RELATIVE, the file must be relative; and if it is declared ORGANIZATION INDEXED, the file must be key-sequenced). ° If the file is key sequenced or has alternate keys, the declaration of the keys in the COBOL program must agree with the declaration of the keys in the file system. ° The file security must be appropriate for the open mode. You cannot open a file for INPUT or I-O if it is secured against your reading it. You cannot open a file for OUTPUT, I-O, or EXTEND if it is secured against your writing to it. Caution. If you open a disk file for shared access, do not use sequential block buffering, because one process can read data from the file that is not up-to-date while another process is altering the file. See the explanation of the RESERVE clause in file-control entries under FILECONTROL Paragraph. When the preceding requirements are met for a disk file present at run time, the open mode determines what happens during execution. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -152 Procedure Division Verbs OPEN Table 9-9. Open Modes for Structured Disk Files Present at Run Time Open Mode Action INPUT If the record length of the physical file is shorter than the record length declared in the File Section, and the record length is not declared as variable (rec-1 TO rec-2 CHARACTERS or VARYING SIZE), the OPEN statement fails. If the open operation succeeds and the file organization is relative, the relative key is established as the key of reference. If the open operation succeeds and the file organization is indexed, the prime record key is established as the key of reference. The file position indicator is set so that the first execution of a READ statement retrieves either of these, depending on the file’s organization: • • OUTPUT The first record in a sequential file The first record in the sequence defined by the key of reference in an indexed, queue, or relative file If the record length of the physical file is shorter than the record length declared in the File Section, the file is not suitable for use: • • If no alternate record keys exist, the file is purged and a new one is created. The new file has file code 0 unless the COBOL_ASSIGN_ routine or the TACL command ASSIGN provides another file code value. The new file has the standard HP COBOL defaults for file size and number of extents, rather than the size and extents of the original file. If alternate record keys exist, the file cannot be purged, and the open operation fails with I-O status code “30.” If the record length of the physical file is not shorter than the record length declared in the File Section, and the file contains some data, the file is not purged, but its data is purged. In either case, no warning alerts you that a purge is taking place. After the file is purged, the file position indicator is set to either of these, depending on the file’s organization: • • EXTEND The first record in a sequential file An undefined value for an indexed, queue, or relative file, because the file contains no records at that point If the record length of the physical file is shorter than the record length declared in the File Section, the file is not suitable for use. The open operation fails with I-O status code “30.” The file position indicator is set to the end of the file. I-O If the record length of the physical file is shorter than the record length declared in the File Section, the file is not suitable for use. The open operation fails with I-O status code “30.” The file position indicator is set to the first record in the file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -153 Procedure Division Verbs • OPEN HP COBOL Queues Printer File Records HP COBOL queues write operations to files that are associated with printers and to processes that behave like printers. The LINAGE clause of the file description entry and the ADVANCING phrase of the WRITE statement are valid only for such files. Records that HP COBOL writes to a process are queued only when the OPEN statement specifies an attribute of OUTPUT, EXTEND, or I-O, and at least one of these is true: ° ° The file description entry includes a LINAGE clause The OPEN statement discovers that the process with which it is associating the file has the device subtype attribute value of 31 When the OPEN routine opens a printer-type file, it turns off automatic page ejection, computes any dynamic logical page attributes, and when appropriate, performs a page eject. In the non-CRE environment (as opposed to the CRE), when a write operation for a printer-type file releases a record to the run-time routines, the routines hold the record until either another record is released or the file is closed. This enables the run-time routines to consolidate any control operations (like page eject or spacing) that follow one record with any that precede the next record, thereby reducing the number of calls to the operating environment. • Files Assigned to Tape Devices When the file device is a tape unit, the run-time routines request mounting of the first, last, or only reel of the file: ° ° The first or only reel if the open mode is INPUT or OUTPUT The last or only reel if the open mode is EXTEND See CLOSE in this section for more information about the messages that the runtime routines issue about tape mounting. If the NO REWIND phrase appears, the tape is presumed to be already properly positioned; otherwise, the tape is rewound and, if it is a multiple-file tape, positioned to the file being opened. The NO REWIND phrase is ignored if the file device is not a tape unit. If the rest of the open operation actions complete successfully, the I-O status code is set to “07.” • Process Pairs When the process is executing as a process pair, each open operation for a file also executes an implied statement of this form: CHECKPOINT FILE file-name HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -154 Procedure Division Verbs • OPEN Exclusion Modes The EXCLUSIVE, SHARED, or PROTECTED phrase specifies the appropriate file system exclusion mode for the file. If the OPEN statement does not have one of these phrases, the process determines the default exclusion mode: when a command interpreter ASSIGN command that applies to the file specifies an exclusion mode, the process uses that exclusion mode; otherwise, the process determines the exclusion mode from the type of file device: Device Exclusion Mode Terminal (including the operator console) SHARED Disk file being opened for input PROTECTED Other file EXCLUSIVE A file that no process has open can be opened by any single process with any exclusion mode. If some process already has a file open EXCLUSIVE, no other process can open the file. A file intended for multi-user access must specify SHARED. If some process already has a file open SHARED for any access mode except OUTPUT, another process can open the same file SHARED for any access mode. If some process already has a file open SHARED for OUTPUT, no other process can open the file (because the OPEN would delete all the records in the file). If some process already has a file open SHARED for INPUT access mode, another process can open the same file PROTECTED for any access mode. If some process already has a file open PROTECTED for INPUT access mode, another process can also open the same file PROTECTED for INPUT access mode. All other combinations of access mode and exclusion mode cause the open operation to fail. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -155 Procedure Division Verbs • OPEN Record Prereading To save execution time by overlapping reading and processing, the run-time routines perform record prereading (starting the read for record n +1 when returning record n to the program) when all of these conditions are true: ° ° ° The file access mode is SEQUENTIAL. ° ° The process is not running as a process pair. The file is open for INPUT. The file is either a disk file opened for PROTECTED use or a disk, tape, terminal, or card reader opened for EXCLUSIVE use. The file is not opened for timed I-O. Caution. Verify the OPEN statement does not meet prereading requirements when the COBOL process does any of these, or the operation might begin with the wrong record: • • • Enters a TAL routine to do input or output Executes the read operation as part of a TMF transaction (enters BEGINTRANSACTION, executes a READ statement, then enters ENDTRANSACTION) Executes a CLOSE NO REWIND statement on a tape file and subsequently executes an OPEN NO REWIND statement on the same file to continue from the previous position Example 9-48 shows an OPEN statement with a TIME LIMITS and a SYNCDEPTH phrase and an OPEN statement without optional phrases. Example 9-48. OPEN Statements ?NONSTOP IDENTIFICATION DIVISION. ... INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT EMPLOYEE-MASTER ASSIGN TO "EMPMAST" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC. ... SELECT LISTING-FILE ASSIGN TO "LISTOUT" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. ... PROCEDURE DIVISION. ... OPEN I-O EMPLOYEE-MASTER WITH TIME LIMITS SYNCDEPTH 1 OPEN OUTPUT LISTING-FILE HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -156 Procedure Division Verbs PERFORM PERFORM PERFORM executes one or more procedures in a program, simply or with looping. When a procedure-name is a section-name, PERFORM executes all the paragraphs in that section. Form Description Unconditional PERFORM Executes a procedure, group of procedures, or imperative statement one time PERFORM TIMES Executes a procedure, group of procedures, or imperative statement a specified number of times PERFORM UNTIL Executes a procedure, group of procedures, or imperative statement repeatedly until a specified condition is true PERFORM VARYING Executes a loop of procedures Unconditional PERFORM Unconditional PERFORM executes a procedure, group of procedures, or imperative statement one time. When execution reaches the end of the procedure, group of procedures, or imperative statement, control returns to the statement following the PERFORM statement. PERFORM procedure-group imperative-statement END-PERFORM VST192.vsd procedure-group proc-1 THROUGH proc-2 THRU VST193.vsd proc-1 is a paragraph-name or section-name. Without THROUGH or THRU, proc-1 identifies the only procedure that is to be executed. With THROUGH or THRU, proc-1 identifies the first procedure of a group. THROUGH THRU indicate that a group of procedures is to be executed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -157 Procedure Division Verbs Unconditional PERFORM proc-2 identifies the last procedure in the group. imperative-statement is defined under Imperative Statement. END-PERFORM ends the scope of the PERFORM statement, causing the PERFORM to be a delimited-scope statement. If the PERFORM statement does not end with an ENDPERFORM phrase, it is an out-of-line PERFORM. If the PERFORM statement ends with an END-PERFORM phrase, it is an in-line PERFORM. Usage Considerations: • Execution Cycle of a PERFORM Statement (PERFORM Cycle) Each execution of the range of a PERFORM statement is called a “PERFORM cycle.” It begins with the implicit transfer of control to the first statement of the range of the PERFORM and ends with an implicit transfer of control back to the internal decision logic of the PERFORM statement. The point at which the return occurs depends upon the proc-1 THROUGH proc-2 phrase: ° When proc-2 does not appear and proc-1 is a paragraph-name, the return occurs after the execution of the last statement in the specified paragraph. ° When proc-2 does not appear and proc-1 is a section-name, the return occurs after the execution of the last statement of the last paragraph of that section. ° When proc-2 does appear and is a paragraph-name, the return occurs after the execution of the last statement in that paragraph. ° When proc-2 does appear and is a section-name, the return occurs after the execution of the last statement of the last paragraph of that section. The preceding conditions for the return of control might be unsatisfied when the range includes a GO TO statement. If the flow of control does not pass through the last statement indicated above, the condition for return cannot be satisfied. Such a PERFORM cycle ends only when the program terminates, which it can do by executing one of these statements: ° ° ° A STOP RUN statement An EXIT PROGRAM statement (from within in a called program) The last statement in the program Avoid including a GOTO statement in the range of a PERFORM statement. For a program compiled by the COBOL85 compiler, a GOTO statement can cause a stack overflow. For a program compiled by the NMCOBOL compiler, a GOTO statement can cause a run-time diagnostic indicating that the PERFORM stack is full. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -158 Procedure Division Verbs • Unconditional PERFORM Procedure Relationships and the Ends of PERFORM Cycles There is no necessary relationship between proc-1 and proc-2, except that a PERFORM cycle begun at the procedure named by proc-1 ends when control reaches the return point following the last statement of the procedure named by proc-2. GO TO statements, PERFORM statements, CALL or ENTER statements, and so forth, can occur in the logical sequence of statements executed during a PERFORM cycle. If there are two or more logical points at which a cycle could end, then proc-2 can name a paragraph consisting solely of the EXIT statement, and all execution paths can terminate cleanly by transferring control to that paragraph. The existence of a return point following the end of an execution range is a dynamic characteristic of an executing program. If control reaches the return point defined for a PERFORM statement that is not in the process of execution (that is, is not currently performing a cycle), then control passes through to the next paragraph in accordance with the normal rules for implicit transfer of control from one statement to the next. • In-line and Out-of-Line PERFORM Statements The PERFORM imperative-statement END-PERFORM form of the statement is an “in-line PERFORM statement.” The PERFORM proceduregroup form of the statement is an “out-of-line PERFORM statement.” The descriptions of the action of the PERFORM statement in this section are expressed in terms of the out-of-line PERFORM statement. The execution of an inline PERFORM statement is exactly equivalent to that of an out-of-line PERFORM statement, with the exception that the statements contained in imperativestatement in the in-line PERFORM statement are executed in place of the statements within the range of procedure-group. Unless specially qualified by the term in-line or out-of-line, all the considerations that apply to the out-of-line PERFORM statement also apply to the in-line PERFORM statement. • Execution and Transfers of Control Section 8, Procedure Division, explains the execution of sections and paragraphs as well as explicit and implicit transfers of control. • Range of the PERFORM Statement The range of an out-of-line PERFORM statement is the statements contained within the range of procedure-group. The range of an in-line PERFORM statement is the statements contained within the PERFORM statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -159 Procedure Division Verbs • Unconditional PERFORM Logical Range of the PERFORM Statement The logical range of any PERFORM statement is all statements that are executed as a result of the PERFORM statement, including the transfer of control to the statement following the PERFORM statement (or to the statement following the END-PERFORM). The logical range includes all statements executed as a result of a GO TO, PERFORM, or CALL statement in the range of the original PERFORM statement, as well as all statements in the Declaratives Portion that might be executed. There is no requirement for statements in the range of a PERFORM statement to appear consecutively. • Nested PERFORM Statements The logical range of a PERFORM cycle can include another PERFORM statement (called a nested PERFORM statement), but these restrictions apply: ° The logical range of the nested PERFORM statement must be either totally included in or totally excluded from the logical range of the outer PERFORM statement; therefore, an active PERFORM statement whose execution point begins within the range of another active PERFORM statement must not allow control to pass to the exit of the other active PERFORM statement. ° The final paragraph in the range of one active PERFORM statement cannot be the same as the final paragraph in the range of any other active PERFORM statement, because the program terminates only one PERFORM cycle for each such final paragraph. The final paragraph would have to be executed twice to terminate both cycles. ° The sequence of statements executed in any cycle of one PERFORM statement must not allow control to reach the return point for any other active PERFORM statement in which it is nested. If this does happen, neither PERFORM cycle terminates, and control falls through to succeeding statements. ° The sequence of statements executed in any cycle of one PERFORM statement must not allow control to reach any active PERFORM statement, including itself. ° As a consequence of the preceding rules, a cycle of an active PERFORM statement cannot end until after any PERFORM statements nested within it complete their execution. For the COBOL85 compiler, the maximum number of PERFORM statements that can be nested varies from 0 to approximately 15,000, depending on the space available on the stack. For the NMCOBOL compiler, the maximum number of PERFORM statements that can be nested is 50. Violation of the preceding rules often causes run-time diagnostic 148. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -160 Procedure Division Verbs • Unconditional PERFORM Placement of Procedures As a general rule, both proc-1 and proc-2 must be in the same logically discrete area of the Procedure Division (in a specific declarative procedure, including any associated sections, or in the portion of the Procedure Division that does not include declaratives). Most violations of this rule cause the compiler to issue a warning but to accept the PERFORM statement; however, if either proc-1 or proc-2 is in the Declaratives Portion, then both must be in the Declaratives Portion. • Placement of PERFORM Statements As a general rule, a PERFORM statement must be in the same logically discrete area of the Procedure Division as proc-1 and proc-2. Most violations of this rule cause the compiler to issue a warning; however, certain combinations are explicitly permitted, and others are totally prohibited: ° For any PERFORM statement, proc-1 and proc-2 can be in any nondebugging declarative procedure; however, the compiler issues a warning if proc-1 and proc-2 are in two different declarative procedures. ° When the PERFORM statement is in a debugging declarative procedure, its proc-1 and proc-2 can be in any declarative procedure; however, the compiler issues a warning if proc-1 and proc-2 are in two different declarative procedures. ° When the PERFORM statement is not in a debugging declarative procedure, neither proc-1 nor proc-2 can be in any debugging declarative procedure. ° When the PERFORM statement is in the Declaratives Portion, neither proc-1 nor proc-2 can be in the other portion of the Procedure Division. Example 9-49. Unconditional PERFORM Statement With One Paragraph IF REPORT-A PERFORM DO-REPORT-A END-IF Example 9-50. Unconditional PERFORM Statement With Several Paragraphs IF REPORTS-TO-DO PERFORM DO-REPORTS THRU DO-REPORTS-EXIT. IF MUST-EXIT ... DO-REPORTS. ... (several paragraphs to create the reports) ... DO-REPORTS-EXIT. EXIT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -161 Procedure Division Verbs PERFORM TIMES An in-line PERFORM statement can contain delimited-scope statements (such as a delimited-scope READ or IF statements) because they count as imperative statements. Example 9-51. In-Line PERFORM Statement With Delimited-Scope Statements PERFORM UNTIL END-IX READ IX-FILE RECORD AT END SET END-IX TO TRUE NOT AT END IF IX-NUMBER > 0 READ MASTR-FILE RECORD KEY IS IX INVALID KEY DISPLAY "Bad IX value: " IX STOP RUN END-READ END-IF MOVE MASTER-NAME TO CUST-NAME ... END-READ END-PERFORM PERFORM TIMES PERFORM TIMES executes a procedure, a group of procedures, or an imperative statement a specified number of times. PERFORM procedure-group count count TIMES TIMES imperative-statement END-PERFORM VST194.vsd procedure-group proc-1 THROUGH proc-2 THRU VST193.vsd proc-1 is a paragraph-name or section-name. Without THROUGH or THRU, proc-1 identifies the only procedure that is to be executed. With THROUGH or THRU, proc-1 identifies the first procedure of a group. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -162 Procedure Division Verbs PERFORM TIMES THROUGH THRU indicate that a group of procedures is to be executed. proc-2 is the last procedure in the group. count is an integer numeric literal or the identifier of an integer data item that tells the process how many times to execute the statements in the range of the PERFORM statement. imperative-statement is defined in Imperative Statement. END-PERFORM ends the scope of the PERFORM statement, causing the PERFORM to be a delimited-scope statement. If the PERFORM statement does not end with an ENDPERFORM phrase, it is an out-of-line PERFORM. If the PERFORM statement ends with an END-PERFORM phrase, it is an in-line PERFORM. Example 9-52 specifies that the value of the identifier TRAN-COUNT controls the number of PERFORM cycles: Example 9-52. PERFORM TIMES Statement PERFORM LIST-TRANSACTIONS TRAN-COUNT TIMES. In Example 9-53, an in-line PERFORM uses a TIMES phrase to initialize a table of squares. Example 9-53. PERFORM TIMES Statement MOVE 1 TO R PERFORM 100 TIMES MULTIPLY R BY R GIVING R-SQ (R) ON SIZE ERROR MOVE "OVERFLOW" TO REASON PERFORM REPORT-DEMISE END-MULTIPLY ADD 1 TO R END-PERFORM HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -163 Procedure Division Verbs PERFORM UNTIL Usage Considerations: • Negative or Zero Value in the TIMES Phrase The value of count can be a negative integer or 0, in which case the process does not perform the procedure or group. • See the usage considerations in Unconditional PERFORM. PERFORM UNTIL PERFORM UNTIL executes a procedure, group of procedures, or imperative statement repeatedly until a condition is true. The condition is checked before or after each PERFORM cycle, and when the condition is met, the PERFORM ends. PERFORM procedure-group test-site UNTIL condition UNTIL condition test-site imperative-statement END-PERFORM VST196.vsd procedure-group proc-1 THROUGH proc-2 THRU VST193.vsd proc-1 is a paragraph-name or section-name. Without THROUGH or THRU, proc-1 identifies the only procedure that is to be executed. With THROUGH or THRU, proc-1 identifies the first procedure of a group. THROUGH THRU indicate that a group of procedures is to be executed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -164 Procedure Division Verbs PERFORM UNTIL proc-2 identifies the last procedure in the group. test-site TEST WITH BEFORE AFTER VST197.vsd specifies whether the condition is to be tested before or after the PERFORM range is executed. The default is TEST BEFORE. condition is any conditional expression. imperative-statement is defined in Imperative Statement. END-PERFORM ends the scope of the PERFORM statement, causing the PERFORM to be a delimited-scope statement. If the PERFORM statement does not end with an END-PERFORM phrase, it is an out-of-line PERFORM. If the PERFORM statement ends with an END-PERFORM phrase, it is an in-line PERFORM. Usage Considerations: • No Execution With TEST BEFORE if the Condition Value is TRUE If the TEST AFTER phrase is not present and the value of the condition is TRUE when control first arrives at the PERFORM statement, the PERFORM range is not executed. • See Usage Considerations: in Unconditional PERFORM. The PERFORM UNTIL statement in Example 9-54 uses a condition-name condition. Once the add routine is successful, a SET ANY-ADDS-CV TO TRUE statement is executing (moving the value 1 to ANY-ADDS-CV); otherwise, ANY-ADDS-CV remains 0 when control returns to the PERFORM statement. As long as ANY-ADDS-CV is 0, the PERFORM cycle is re-executed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -165 Procedure Division Verbs PERFORM VARYING Example 9-54. PERFORM UNTIL Statement WORKING-STORAGE SECTION. 01 ANY-ADDS-CV PICTURE 9. 88 SOME-MORE-ADDS VALUE 0. 88 NO-MORE-ADDS VALUE 1. ... PROCEDURE DIVISION. ... MOVE 0 TO ANY-ADDS-CV PERFORM ADD-ROUTINE UNTIL NO-MORE-ADDS ... ADD-ROUTINE. ... PERFORM VARYING PERFORM VARYING executes a loop of procedures. PERFORM VARYING with TEST BEFORE is a “while loop;” with TEST AFTER, it is a “repeat loop.” A single PERFORM VARYING statement containing one or more AFTER phrases enables you to perform nested loops of procedures. The last AFTER phrase defines the innermost loop. The first set of parameters in the VARYING phrase defines the outermost loop. PERFORM procedure-group test-site varying-phrase after-phrase varying-phrase test-site after-phrase imperative-statement END-PERFORM VST198.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -166 Procedure Division Verbs PERFORM VARYING procedure-group proc-1 THROUGH proc-2 THRU VST193.vsd proc-1 is a paragraph-name or section-name. Without THROUGH or THRU, proc-1 is the only procedure that is to be executed. With THROUGH or THRU, proc-1 is the first procedure of a group. THROUGH THRU indicate that a group of procedures is to be executed. proc-2 is the last procedure in the group. test-site TEST BEFORE WITH AFTER VST197.vsd BEFORE specifies that the condition is to be tested before the perform range is executed. This is the default. AFTER specifies that the condition is to be tested after the perform range is executed. varying-phrase VARYING UNTIL vary-1 FROM base-1 BY step-1 condition-1 VST199.vsd specifies the outermost loop of the PERFORM statement control logic. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -167 Procedure Division Verbs PERFORM VARYING vary-1 is a numeric data item or an index. It is the iteration variable—the variable whose value is changed each time the code in the outermost loop is executed. base-1 is a numeric literal, an index-name, or the identifier of a numeric data item. It is the initial value for vary-1. step-1 is a numeric literal or the identifier of a numeric data item. It is the increment that is to be added to vary-1 each time control returns from the end of the range of the PERFORM. The value of step-1 must not be 0. condition-1 is any conditional expression. after-phrase AFTER UNTIL vary-2 FROM base-2 BY step-2 condition-2 VST200.vsd specifies additional inner loops of the PERFORM statement control logic. Up to six AFTER phrases can be used in an out-of-line PERFORM statement. In COBOL, the AFTER phrase is not permitted in the in-line PERFORM statement. vary-2 is a numeric data item or an index. It is an iteration variable—a variable whose value changes each time the process executes the code in an inner loop. base-2 is a numeric literal, an index-name, or the identifier of a numeric data item. It is the initial value for vary-2. step-2 is a numeric literal or the identifier of a numeric data item. It is the increment that is to be added to vary-2 each time control returns from the end of the range of the PERFORM. The value of step-2 must not be 0. condition-2 is any conditional expression. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -168 Procedure Division Verbs PERFORM VARYING imperative-statement is defined in Imperative Statement. END-PERFORM ends the scope of the PERFORM statement, causing the PERFORM to be a delimited-scope statement. If the PERFORM statement does not end with an ENDPERFORM phrase, it is an out-of-line PERFORM. If the PERFORM statement ends with an END-PERFORM phrase, it is an in-line PERFORM. Usage Considerations: • No Execution With TEST BEFORE if the Condition Value is TRUE If the TEST AFTER phrase is not present and the value of the condition in the VARYING phrase is TRUE when control first arrives at the PERFORM statement, the PERFORM range is not executed. • Values of Data Items The PERFORM VARYING statement initializes and augments the values of one or more data items in an orderly manner. When vary-1 or vary-2 is an index-name, it is initialized and subsequently augmented according to the rules of the SET statement. When vary-1 or vary-2 is the name of a numeric data item, it is initialized either according to the rules of the SET statement (if the associated base-1 or base-2 is an index-name) or according to the rules of the MOVE statement (if base-1 or base-2 is not an index-name). In either case, subsequent augmentation (with the BY phrase) occurs in the manner described later. • Execution of PERFORM VARYING with TEST BEFORE Specified or Implied When no AFTER phrase list appears, vary-1 is initialized with the value of base-1 at the beginning of execution of the PERFORM statement. If condition-1 evaluates to FALSE, the first cycle is performed; if TRUE, no cycles are performed. After the completion of each cycle, the value of vary-1 is augmented by step-1, and condition-1 is evaluated again to determine whether or not to perform another cycle. Whenever the evaluation of condition-1 results in TRUE, execution of the statement terminates. Figure 9-7 illustrates the execution of a PERFORM VARYING statement with a TEST BEFORE phrase and without an AFTER phrase list. After execution of the PERFORM statement terminates, vary-1 has the value assigned, either by initialization or augmentation, at the point where the evaluation of condition-1 gave a result of TRUE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -169 Procedure Division Verbs PERFORM VARYING When one AFTER phrase appears, vary-1 and vary-2 are initialized with the values of base-1 and base-2, respectively, at the beginning of execution of the PERFORM statement. Then either: ° If condition-1 is TRUE, execution of the statement terminates without ever proceeding to the inner loop (without performing any cycles). ° If the initial value of condition-1 is FALSE, execution proceeds to the inner loop of the PERFORM statement logic. Figure 9-7. Execution of a PERFORM VARYING Statement With a TEST BEFORE Phrase and Without an AFTER Phrase List Enter Set vary-1 to current base-1 value. condition-1 ? TRUE Exit FALSE Execute the range of the PERFORM. Augment vary-1 with step-1 . VST510.vsd Each iteration of the inner loop begins with an evaluation of condition-2: ° If its value is FALSE, a cycle is performed, vary-2 is augmented by the specified increment or decrement (the value of step-2 ), and control returns to the top of the loop. ° If the value of condition-2 is TRUE, no cycle is performed, vary-1 is augmented by the specified increment or decrement (the value of step-1 ), vary-2 is initialized to base-2, and the inner loop terminates. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -170 Procedure Division Verbs PERFORM VARYING After each termination of the inner loop, the process evaluates condition-1 again: ° If the value of condition-1 is FALSE, execution proceeds to the inner loop, as described in the preceding text. ° If the value of condition-1 is TRUE, execution of the statement terminates. Figure 9-8. Execution of a PERFORM VARYING Statement With a TEST BEFORE Phrase and One AFTER Phrase Enter Set vary-1 to current base-1 value. Set vary-2 to current base-2 value. TRUE condition-1 ? Exit FALSE TRUE condition-2 ? FALSE Execute the range of the PERFORM. Augment vary-2 with step-2 . Augment vary-1 with step-1 . Set vary-2 to base-2 . VST511.vsd After termination of the PERFORM statement, vary-1 has the value assigned, either by initialization or augmentation, at the point where the evaluation of condition-1 gave a result of TRUE. vary-2 has the value assigned by its last initialization from the base-2. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -171 Procedure Division Verbs PERFORM VARYING When multiple AFTER phrases appear, the mechanism is the same as for one AFTER phrase except: ° In secondary AFTER phrases, vary-2 is also initialized with the value of base-2 in its associated FROM phrase at the beginning of execution of the PERFORM statement. ° In the inner loop (as described earlier), the step “a cycle is performed” is replaced by “execution proceeds to the next inner loop.” ° The logic of the next inner loop parallels that of the first inner loop except for: ° ° Its condition plays the role of condition-2. ° The next vary-2 is initialized with the current value of the base-2 in its associated FROM phrase when the value of its condition is TRUE. The next vary-2 is augmented by the current value of its step-2 after each cycle is performed. After termination of a PERFORM statement with multiple AFTER phrases, vary-1 has the value assigned, either by initialization or augmentation, at the point where the evaluation of condition-1 gave a result of TRUE, and each vary-2 has the value assigned by its last initialization from its associated base-2. • Execution of PERFORM VARYING with TEST AFTER Specified When no AFTER phrase list appears, vary-1 is initialized with the value of base-1 at the beginning of execution of the PERFORM statement. The first cycle is then performed. After the completion of each cycle, condition-1 is evaluated to determine whether or not to perform another cycle. Whenever the evaluation of condition-1 results in TRUE, execution of the statement terminates. If the evaluation of condition-1 results in FALSE, the value of vary-1 is augmented by the specified increment or decrement (the value of step-2 ), and another cycle is performed. After termination of the PERFORM statement, vary-1 has the value it contained at the end of the last execution of the range of the PERFORM statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -172 Procedure Division Verbs PERFORM VARYING Figure 9-9. Execution of a PERFORM VARYING Statement With a TEST AFTER Phrase and Without an AFTER Phrase List Enter Set vary-1 to current base-1 value. Execute the range of the PERFORM. condition-1 ? TRUE Exit FALSE Augment vary-1 with step-1 . VST512.vsd When one AFTER phrase appears, vary-1 and vary-2 are initialized with the values of base-1 and base-2, respectively, at the beginning of execution of the PERFORM statement. Then the specified set of statements is executed. This is considered the inner loop. Each iteration of the inner loop ends by evaluating condition-2. ° If its value is FALSE, vary-2 is augmented by the specified increment or decrement (the value of step-2 ), and a cycle is performed. ° If its value is TRUE, condition-1 is evaluated. ° If the value of condition-1 is FALSE, vary-1 is augmented by the specified increment or decrement (the value of step-1 ), vary-2 is initialized with the current value of base-2, and the inner loop is entered again. ° Whenever the evaluation of condition-1 results in TRUE, execution of the statement terminates. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -173 Procedure Division Verbs PERFORM VARYING Figure 9-10. Execution of a PERFORM VARYING Statement With a TEST AFTER Phrase and One AFTER Phrase Enter Set vary-1 to current base-1 value. Set vary-2 to current base-2 value. Execute the range of the PERFORM. TRUE condition-2 ? FALSE Augment vary-2 with step-2 . condition-1 ? TRUE Exit FALSE Augment vary-1 with step-1 . VST513.vsd After termination of the PERFORM statement, vary-1 and vary-2 have the values they contained at the end of the last execution of the specified set of statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -174 Procedure Division Verbs PERFORM VARYING When two or more AFTER phrases appear, the mechanism is the same as for one AFTER phrase except: ° In the second AFTER phrase, vary-2 is also initialized with the value of base-2 in its associated FROM phrase at the beginning of execution of the PERFORM statement. ° In the inner loop (as described earlier), the step “a cycle is performed” is replaced by “execution proceeds to the second inner loop.” ° The logic of the second inner loop parallels that of the first inner loop except for: ° ° Its condition plays the role of condition-2. ° The second vary-2 is initialized with the current value of the base-2 in its associated FROM phrase when the value of its condition is TRUE. The second vary-2 is increased by the current value of its step-2 after each cycle is performed. After termination of a PERFORM statement with two AFTER phrases, vary-1 has the value assigned, either by initialization or increase, at the point where the evaluation of condition-1 gave a result of TRUE, and each vary-2 has the value assigned by its last initialization from its associated base-2. • Restrictions for Index-Names When the vary-1 or vary-2 is an index-name, these restrictions apply: ° The base-1 or base-2 operand must be a positive integer numeric literal, an index-name, or an identifier that designates an integer numeric data item. ° The step-1 or step-2 operand must be an integer numeric literal or an identifier that designates an integer numeric data item. When the base-1 or base-2 operand is an index-name, these restrictions apply: ° The associated vary-1 or vary-2 operand must be an index-name or an identifier that designates an integer numeric data item. It cannot designate a special register. ° The associated step-1 or step-2 operand must be an integer numeric literal or an identifier that designates an integer numeric data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -175 Procedure Division Verbs • PERFORM VARYING Restrictions for Identifiers When the vary-1 or vary-2 operand is an identifier, and the associated base-1 or base-2 is not an index-name, these restrictions apply: • ° The vary-1 or vary-2 identifier must designate a numeric data item. It cannot designate a special register. ° The associated base-1 or base-2 operand must be a numeric literal or an identifier that designates a numeric data item. ° The associated step-1 or step-2 must be a numeric literal or an identifier that designates a numeric data item. Execution Cycles of PERFORM Statements (PERFORM Cycles) Execution of a PERFORM statement causes none, one, or more executions of its range. These executions are called PERFORM cycles. The number of PERFORM cycles depends upon the values of the operands of the PERFORM statement. The decision of whether to perform the first cycle or not occurs after any initialization specified in the VARYING and FROM phrases. • See Usage Considerations: in Unconditional PERFORM. Example 9-55. PERFORM VARYING Statement Used to Display a List WORKING-STORAGE SECTION. 01 COMMAND-DATA. 05 FILLER PIC X(36) VALUE "ADD - ADD A NEW RECORD". 05 FILLER PIC X(36) VALUE "DELETE - DELETE A RECORD". ... 01 COMMAND-TABLE REDEFINES COMMAND-DATA. 05 COMMAND-ENTRY PIC X(36) OCCURS 10 TIMES. 01 COMMAND-NUMBERS. 05 NO-OF-COMMANDS PIC 99 VALUE 9. 05 COMMAND-SUB PIC 99 COMP VALUE 1. PROCEDURE DIVISION. ... PERFORM LIST-COMMANDS VARYING COMMAND-SUB FROM 1 BY 1 UNTIL COMMAND-SUB GREATER THAN NO-OF-COMMANDS ... LIST-COMMANDS. DISPLAY COMMAND-ENTRY(COMMAND-SUB) ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -176 Procedure Division Verbs READ In Example 9-56, each of the two paragraphs builds a table of numbers (rows) raised to powers (columns). Each paragraph fills the 5 columns of row 1, then of row 2, and so on. Example 9-56. PERFORM VARYING Statement Used to Build a Table WORKING-STORAGE SECTION. 01 TWO-D-TABLE. 03 OCCURS 10 TIMES. 05 PWR PICTURE 9(6) OCCURS 5 TIMES. PROCEDURE DIVISION. TWO-NESTED-PERFORMS. PERFORM VARYING R FROM 1 BY 1 UNTIL R > 10 PERFORM VARYING C FROM 1 BY 1 UNTIL C > 5 COMPUTE PWR (R, C) = R ** C END-PERFORM END-PERFORM. SINGLE-PERFORM-WITH-AFTER. PERFORM VARYING R FROM 1 BY 1 UNTIL R > 10 AFTER C FROM 1 BY 1 UNTIL C > 5 COMPUTE PWR (R, C) = R ** C END-PERFORM. READ READ copies one logical record from a file and stores it in a record area defined by your program. Form Reads the record that is ... READ for Sequential or Dynamic Access Next in the file READ for Line Sequential Files Next in the file READ for Random or Dynamic Access Identified by the value of a key HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -177 Procedure Division Verbs READ for Sequential or Dynamic Access READ for Sequential or Dynamic Access READ for sequential or dynamic access reads the next record in the file. (For sequential access of line sequential files, see READ for Line Sequential Files.) READ file-name NEXT REVERSED RECORD INTO data-name LOCK WITH TIME PROMPT LIMIT END prompt-item wait-time imperative-stmt-1 AT NOT END imperative-stmt-2 AT END-READ VST201.vsd file-name is the file description name of the file to retrieve a record from. NEXT indicates that the next record is to be read (that is, the record after the current record, according to the key of reference). NEXT is required for sequential reading of a relative, indexed, or queue file whose access is DYNAMIC. REVERSED indicates that the prior record is to be read (that is, the record before the current record, according to the key of reference). For restrictions, see Restrictions on REVERSED. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -178 Procedure Division Verbs READ for Sequential or Dynamic Access data-name is the identifier of the data area defined by your program to which the contents of the record area are transferred after the read operation is complete. data-name cannot be an index-name or the identifier of an index data item. The transfer is conducted as if it were a move from an alphanumeric item to an alphanumeric item. The INTO phrase is allowed only when one of: ° ° Only one record is associated with file-name. The record associated with file-name is defined as a data structure or as an elementary alphanumeric item and data-name is either a data structure or an elementary alphanumeric item. LOCK keeps other programs from accessing the record retrieved until an UNLOCKFILE statement, UNLOCKRECORD statement, or REWRITE UNLOCK statement executes. The file that file-name specifies must be associated with a disk device. PROMPT displays prompt-item to the file before a READ operation (as in a COBOL requester communicating with a server). The PROMPT phrase is permitted only for files whose organization is SEQUENTIAL and works only for terminals, processes, operator consoles, and communication system submanagers. If the PROMPT phrase is specified for other devices, such as disk files, it is ignored. prompt-item is a DISPLAY data item that starts at the beginning of a record of the file associated with file-name. prompt-item is ignored if the file against which the READ is executed is open in INPUT, OUTPUT, or EXTEND mode, or if the file is assigned to a device not capable of supporting such operations (such as a disk file). For further information on the use of prompt-item, see PROMPT phrase. wait-time is the time interval, in seconds, in which the operation must complete. wait-time can be a literal or the name of a data item. In either case, it must have a value described with at most seven digits preceding any decimal point position. Any fractional portion is truncated to two decimal places. If file-name was not opened with a TIME LIMITS phrase, including wait-time in the READ statement causes a run-time error. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -179 Procedure Division Verbs READ for Sequential or Dynamic Access imperative-stmt-1 is an imperative statement to be performed when the end of the file is encountered at the beginning of the read operation. This phrase is required if no USE statement is applicable for the file. If both a USE statement and an AT END phrase are present, only the AT END phrase is used. imperative-stmt-2 is an imperative statement to be performed when the end of the file is not encountered at the beginning of the read operation. END-READ ends the scope of the READ statement, causing the READ to be a delimited-scope statement. If the READ statement does not end with an END-READ phrase, the presence of the AT END or the NOT AT END phrase causes the READ statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • Restrictions on REVERSED REVERSED can be specified for a file only if all of these conditions are true: ° ° The file is a structured disk file. ° ° The file’s access is not RANDOM. The file’s file-control entry does not have a RESERVE clause with number greater than one in the non-CRE environment or greater than two in the CRE. Prereading is not active for the file. If REVERSED is specified, then: ° ° Neither LOCK nor PROMPT prompt-item can be specified. REVERSED cancels the effect of GENERIC (a positioning mode that the START statement can specify). REVERSED is not recommended if these conditions are true, because it is very inefficient: • ° ° ° File organization is RELATIVE. The relative key is the key of reference. Records are not contiguous. Action of the READ Statement (Sequential Read) Any READ statement that has a NEXT or REVERSED phrase, or is associated with a file for which the ACCESS MODE SEQUENTIAL clause is specified or implied, is a sequential READ statement. Any other READ statement is a random READ statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -180 Procedure Division Verbs READ for Sequential or Dynamic Access The file identified by file-name must be open in the INPUT or I-O mode; if it is not, the read operation is unsuccessful with I-O status code “47.” If the file is described with fixed-length records and a smaller record is read, the read operation is successful with I-O status code “04.” In addition to the specific I-O status codes described later, the general codes “00,” “30,” and “90” can occur. For more information, see I-O Status Code. ° Retrieval of a logical record The read operation retrieves a logical record from the file identified by filename and places it into the record area associated with that file. ° Alignment within record area If the size of the retrieved record is greater than the maximum record size defined for the file (as specified in the explicit or implicit RECORD clause in the file description entry for file name), the run-time routines truncate the retrieved record on the right before placing it in the record area. If the size of the retrieved record is less than the maximum record size defined for the file, the run-time routines left justify the record content within the record area. All character positions in the record area that are to the right of the last character in the retrieved record have undefined values—that is, they can contain any characters. If you want to verify that they are spaces, use the INTO phrase. When the read operation is attempted on a file with fixed-length records and the size of the retrieved record is greater than the maximum record size defined for the file or less than the minimum record size defined for the file (as specified in the explicit or implicit RECORD clause in the file description entry for the file), the read operation is unsuccessful with I-O status code “30” and the GUARDIAN-ERR register has the value 21. ° Unsuccessful read operation Whenever the read operation terminates with an I-O status code greater than or equal to “30” (except “97”), execution of the READ statement is not successful. In this case the applicable USE procedure, if one exists, is executed. If the execution of a READ statement is unsuccessful for any reason, the key of reference and the contents of the record area associated with the file are undefined and the value of the depending item, if one is defined for the file, is not altered. ° PROMPT phrase When the PROMPT phrase appears, and the device with which the file is associated is either a terminal or a process (typically, a server), and the file’s open mode is I-O, the value of prompt-item is sent to the file as part of the read operation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -181 Procedure Division Verbs READ for Sequential or Dynamic Access The PROMPT phrase (often used for the WRITE/READ action common in requesters) is effective only when the device with which the file is associated is either a terminal or a process and the open mode of the file is I-O. When these conditions are met, the PROMPT phrase causes the value of prompt-item to be sent to the file before the actual read operation begins (as if a write operation preceded the read operation). The record area is then cleared to spaces for the length of the prompt-item. Characters being read from the terminal or process are then copied into the record area. When the specified conditions are not met, the PROMPT phrase is ignored. If the file has variable-length records, then the DEPENDING ON data item does not affect the length of the string written from the prompt-item. To write a variable-length prompt-item, use reference modification. You can also write a variable-length prompt-item by using an OCCURS DEPENDING phrase in the prompt-item, but then you cannot use reference modification on the prompt-item elsewhere in the program. ° Inability to establish a position for the read operation The run-time routines examine the file position indicator at the start of the read operation. Certain settings of the file position indicator reflect that the read operation is unable to retrieve any record: • ° If the file position indicator indicates that no valid next record has been established, the read operation terminates immediately with I-O status code “46.” ° If the file position indicator indicates that an optional file is not present, the run-time routines change the setting of the file position indicator to indicate that the at-end condition already exists. The read operation then terminates with I-O status code “10.” Execution then proceeds as described in the rule for the at-end condition (see the usage condition Retrieval). File-Status Data Item You can declare a file-status data item for a file in its file-control entry. During each execution of a READ statement, this file-status data item is assigned a new value that reflects the outcome of the read operation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -182 Procedure Division Verbs READ for Sequential or Dynamic Access The possible I-O status codes that result from successful read operations are: I-O Status Code Successful Read Operation “00” The read operation was unconditionally successful. “02” This is possible only when a file has the INSERTIONORDER attribute. The key value for the alternate key that is serving as the current key of reference is equal to the value of that same key in the record that is the next one in the file with respect to that key of reference. “04” The file is not described as having variable-length records (by having the RECORD CONTAINS rec-1 TO rec-2 CHARACTERS clause or a RECORD VARYING clause in its file description), and a record was read that was shorter than the maximum size. The execution of the READ statement is successful. “97” A locked record was read successfully. (You must have called SETMODE to allow locked records to be read.) If, at the start of the read operation, the file position indicator is at the end-of-file mark or its value is not defined, execution of the READ statement is unsuccessful, and the file-status data item is set to a value other than “00.” Note. After an unsuccessful execution of a READ statement, these values are unpredictable: • • • The value of the file position indicator The contents of the current record area The key of reference Any key value found in the current record area: that is, the value of the current key for indexed files or the value of the alternate key for any type of file-system file, because in HP COBOL sequential and relative files can have alternate keys. The possible I-O status codes that result from unsuccessful read operations are: I-O Status Code Unsuccessful Read Operation “10” The end of file condition arose either in the normal course of events or because the program tried to read an optional file that was not present. “30” A permanent error exists. “46” The value of the file position indicator is undefined at the beginning of the execution of a READ statement. “47” The file is not open in the INPUT or I-O mode. “90” A logic error has occurred that is not covered by the “4x” file status codes, and no recovery is possible. “91” The file being read is a file in EDIT format, and some step in the read operation failed due to non-COBOL causes. The record is not read, and the execution of the READ statement is unsuccessful. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -183 Procedure Division Verbs • READ for Sequential or Dynamic Access Retrieval When the file position indicator has a value that permits positioning for the read operation, the run-time routines use that value to identify the record to be retrieved. In this topic, if the value of the file position indicator reflects a current key of reference that is a record key, the comparisons relate to the value of that key for records in the file; otherwise, the comparisons for a sequential file relate to the record number of the records in the file, and the comparisons for a relative file relate to the relative record number of the records in the file. If the file position indicator was established by a previous OPEN or START statement, then the record selected for retrieval is one of: ° If NEXT is specified or implied, the record whose record number or key value is greater than or equal to the file position indicator ° If REVERSED is specified, the record whose record number or key value is less than or equal to the file position indicator If the file position indicator was established by an earlier READ statement, and its setting does not reflect an alternate record key for which duplicates are allowed, then the record selected for retrieval is one of: ° If NEXT is specified or implied, the first existing record in the file whose record number or key value is greater than the file position indicator ° If REVERSED is specified, the first existing record in the file whose record number or key value is less than the file position indicator If the file position indicator was established by an earlier READ statement, and the setting of the file position indicator reflects an alternate record key for which duplicates are not allowed, then the record selected for retrieval is one of: ° If NEXT is specified or implied, the first record in the file whose key value is either equal to the file position indicator and whose logical position within the set of duplicates is immediately after the record that was made available by that previous READ statement, or whose key value is greater than the file position indicator ° If REVERSED is specified, the first record in the file whose key value is either equal to the file position indicator and whose logical position within the set of duplicates is immediately prior to the record that was made available by that previous READ statement, or whose key value is less than the file position indicator HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -184 Procedure Division Verbs READ for Sequential or Dynamic Access The execution of a START statement establishes a subset of the file’s records that can be retrieved by subsequent sequential or dynamic READ statements. If the current statement is one in a sequence of such READ statements executed after a START statement for the same file (without the execution of an OPEN, START, or Random READ having intervened), then the record (if any) selected for retrieval by the preceding rules is tested to determine whether it is a member of the file subset established by the START statement. If it is not, then the record is disqualified and the effect is the same as if no record had been selected. If the read operation is successful, the record selected by the file position indicator is retrieved and placed into the record area associated with the file. If the file is a multiple-reel tape file, and the end-of-reel condition occurs during the retrieval operation, the run-time routines perform a reel-swap sequence, and the first record of the next reel is retrieved. (For information on the reel-swap sequence, see OPEN.) If there is no next reel, the at-end condition exists. In this case, the read operation terminates, and execution of the READ statement is unsuccessful. The at-end condition exists because one of these conditions is true: ° The file is present but there is no record at the position specified by the file position indicator (such as the position immediately beyond the last record in the file). ° The file has an OPTIONAL phrase in its SELECT clause and, although open, is not actually present. ° The START GENERIC reached the end of a set of duplicates. If the at-end condition exists, the read operation terminates, and execution of the READ statement is unsuccessful. When the at-end condition exists, the I-O status code of the read operation is set to “10.” If the AT END phrase is specified, control passes to the imperative statement in that phrase, and no USE procedure is executed. If neither the AT END nor the NOT AT END phrase is specified, and an applicable USE procedure exists, that procedure is executed. • Relative Key Data Item of Relative Files A successful execution of the READ statement for a relative file also assigns the relative record number of the retrieved record to the file’s relative key data item if the file description defines one. The relative key data item is optional for relative files being accessed sequentially. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -185 Procedure Division Verbs • READ for Sequential or Dynamic Access LOCK Phrase When the READ statement includes a LOCK phrase, the read operation also locks the retrieved record. The concept of record locking applies only to disk files and queued files. A successful record lock operation guarantees you exclusive access to the record until the program executes one: ° ° ° A REWRITE statement with the UNLOCK option for the same record An UNLOCKRECORD statement for the same record An UNLOCKFILE statement for the file If the program already holds a record lock for the record in question, the read operation notes this and preserves the lock. If your HP COBOL process opens the same file twice (that is, treats the file as two separate files with separate file-control entries, each with its own file-name, executes a READ LOCK statement on one file-name and then executes another READ LOCK statement on the other file-name ), the process deadlocks. This problem does not occur if the process opens the file only once or if you use time limits. • Interaction of LOCKFILE and READ LOCK Statements If your process executes a READ LOCK statement on a file that it or any other process has locked with a LOCKFILE statement, or your process executes a LOCKFILE statement against a file that has an outstanding READ LOCK, the TIME LIMIT phrase determines what happens. If the second statement attempting to lock the file has a TIME LIMIT phrase, it keeps trying to lock the file until the time limit expires. Either it fails and then times out or it succeeds in locking the file. If the second statement attempting to lock the file has no TIME LIMIT phrase, it suspends execution until the statement succeeds because the contending lock is removed or until the program is terminated by an external agency such as the TACL command STOP. • INTO Phrase When the READ statement includes an INTO phrase, the retrieved logical record is moved from the file record area to the data item specified in the INTO phrase. Any specified subscript or index evaluation involved occurs after the record is retrieved and placed in the record area and just before it is moved to the data item. The size of the sending operand in the implicit MOVE statement is the size of the record as placed into the record area. This move does not occur if the execution of the READ statement is unsuccessful for any reason. See INTO Phrase. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -186 Procedure Division Verbs • READ for Sequential or Dynamic Access GUARDIAN-ERR Special Register The GUARDIAN-ERR special register is updated each time a file-manipulating statement is executed. The value of GUARDIAN-ERR usually provides more specific information about the cause of an unsuccessful completion signaled by the file-status data item. For example, if the file status is “30” (permanent error), GUARDIAN-ERR contains the file system error number identifying the cause. See Diagnosing Input-Output Errors. • Handling Exception Conditions The READ statement enables you to specify explicitly that when an at-end condition occurs, a particular statement is to be executed. For general exception handling, a group of statements called declaratives can be placed at the beginning of the Procedure Division to respond to error conditions arising for a single file or for all files open in the same input mode (INPUT, OUTPUT, I-O, or EXTEND). See USE AFTER EXCEPTION. The USE AFTER EXCEPTION statement specifies what to do when a filemanipulating statement encounters an exception condition. Declaratives can be called for at-end, invalid key, and other exception conditions. If, for example, the program includes a USE statement referring to the file being read, and a read operation is attempted when no next logical record exists, then the process executes either an AT END phrase or the USE statement: ° ° If an AT END phrase is present, it is executed. If no AT END phrase is present, the USE statement is executed. If a READ operation encounters a recoverable permanent error (Status Key 1 equals 3, or Status Key 1 equals 9 but Status Key 2 does not equal 7), no at-end condition occurs; however, if a declarative is present for the file, that declarative is activated, then any NOT AT END phrase is executed. Either the declarative or the NOT AT END phrase can then determine the nature of the error (usually by checking GUARDIAN-ERR) and take appropriate action. See Recovering from Input-Output Errors. After an at-end condition for a sequentially accessed file (other than $RECEIVE), you must close and reopen or reposition the file before any further operations can be done on it. You can reposition the file with the START statement, the routine COBOL85^REWIND or COBOL_REWIND_. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -187 Procedure Division Verbs • READ for Sequential or Dynamic Access Variable-Length Records An Enscribe structured file is always capable of containing variable-length records. The file has a stated maximum allowable record length, but records can vary from a length of 0 up to the stated maximum. If the file is written as variable-length records, the COBOL program can read it under a declaration of RECORD CONTAINS rec-1 TO rec-2 CHARACTERS or RECORD IS VARYING IN SIZE FROM rec-1 TO rec-2 CHARACTERS DEPENDING ON rec-size (although in COBOL you cannot explicitly state rec-1 as 0). The only way to determine the length of the record read is to use the DEPENDING phrase of the VARYING clause. The contents of the record area beyond the data fetched by any given read is undefined. Other HP products are capable of writing records of length 0 in such files. A COBOL program can read a record of length 0; however, in an entry-sequenced file with fixed-length records, such a record is ignored and the next record is immediately read. • Setting the Value of the DEPENDING Item (Variable-Length Records) When the file has variable-length records whose sizes are reflected by the recsize item specified in the RECORD VARYING clause of the file description entry, the value associated with the rec-size at the beginning of a read operation is ignored. The read operation obtains the record and moves the number of character positions the record contains into rec-size. • Use of wait-time wait-time must be either a numeric data item or a numeric literal, signed or unsigned, having a maximum of seven digits to the left of the decimal. Any fractional part to the right of the decimal is rounded to two decimal places; for example: 05 WAIT-FILEX PIC 9(7)V9(2) COMPUTATIONAL. A nonnegative value of wait-time indicates the time interval within which the operation must complete. If the record is locked or reading a process and the operation does not complete within that time interval, it is terminated, and no error message is generated. The file-status item is set to “30,” the GUARDIAN-ERR register is set to 40, and the value of the file position indicator becomes undefined. The file position indicator is undefined because it is not clear at what point of the read operation wait-time was exceeded. There is no guarantee that you can try the operation again. If the value of wait-time is -1 or the TIME LIMIT phrase is not present, no time limit is placed on the operation. The program can wait indefinitely for its request to complete. Any other negative value has the same effect as -1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -188 Procedure Division Verbs READ for Sequential or Dynamic Access If the TIME LIMIT phrase is specified with a nonnegative value and the file is not opened with time limits enabled, the program terminates with an I-O status code “90,” and a message (File is not opened for timed I-O) is delivered to the process’s home terminal. The effect of declaratives on time-limit termination is: ° If there is no declarative procedure applicable to the file when the operation is abandoned, the process terminates, and an ABEND message is reported to the process’s home terminal. ° If the applicable declarative procedure is present (but no AT END phrase is present) and the time interval expires, the declarative procedure is performed. Then program execution continues with the imperative statement in the NOT AT END phrase, if one is present, or otherwise with the statement following the one terminated. When a file is being read with APPROXIMATE positioning (see START), the value used for wait-time must take into account that a read operation can take somewhat longer than expected. This can occur when a nonexistent record is sought, because the file system searches through the file looking for the next defined record before reporting the absence of the record sought. See the Guardian Programmer’s Guide for more information on the action of READ. • Concept of Next Record READ NEXT is used to read the next record of a file whose access mode is SEQUENTIAL or DYNAMIC. Files whose access mode is SEQUENTIAL can be read without the NEXT keyword, but each such read gets the “next record” in the file. The “next record” means “next existing record within the established key of reference.” ° If the last operation on the file was a start operation (or open operation, in the case of relative, indexed, or queue files), and the record selected by the file position indicator is still accessible through the file position indicator, that record is read. ° If the last operation on the file was a read operation (either a READ KEY or a READ NEXT), or if the record selected by the file position indicator is no longer accessible through the file position indicator (due to deletion or a change of the alternate key), the file position indicator is updated to point to the next existing record in the file, and that record is read. ° If the value of the file position indicator for the file is undefined when execution of the READ statement begins, the read operation is unsuccessful, and any file-status data item declared for the file in the file-control entry is updated to specify the reason. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -189 Procedure Division Verbs • READ for Sequential or Dynamic Access Use of the READ NEXT Statement on Relative, Indexed, or Queue Files The READ NEXT statement operates on a relative, indexed, or queue file only if the file is declared with ACCESS MODE SEQUENTIAL or ACCESS MODE DYNAMIC. • Sequential Block Buffering and HP COBOL Fast I-O Sequential block buffering, enabled by the RESERVE clause of the FILECONTROL Paragraph, is an Enscribe feature that speeds the reading of a sequential, relative, indexed, or queue file by reading a block of records together into a memory buffer. HP COBOL Fast I-O is a variant of sequential block buffering that is even faster, because the run-time routines handle the record deblocking. For either of these features, the file’s access must be sequential. In the non-CRE environment, its organization must be sequential. In the CRE, its file organization must be sequential, relative, indexed, or queue. See FILE-CONTROL Paragraph. • Eight-Character Volume Names and HP COBOL Fast I-O If you use an eight-character volume name in this context, you do not get an error or warning, but you get normal output instead of fast output. (Input is not affected.) Example 9-57. Reading a Sequential File IDENTIFICATION DIVISION. ... ENVIRONMENT DIVISION. ... SELECT INPUT-DATA ASSIGN TO "$TAPE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL FILE STATUS IS INPUT-DATA-FILE-STATUS. ... DATA DIVISION. FILE SECTION. FD INPUT-DATA. 01 INPUT-RECORD. ... WORKING-STORAGE SECTION. ... 01 FILE-STATUSES. 03 INPUT-DATA-FILE-STATUS PICTURE XX. ... PROCEDURE DIVISION. ... READ INPUT-DATA AT END CLOSE INPUT-DATA END-READ IF ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -190 Procedure Division Verbs READ for Sequential or Dynamic Access Example 9-58. Reading a Dynamic Indexed File IDENTIFICATION DIVISION. ... ENVIRONMENT DIVISION. ... SELECT MASTER-IN ASSIGN TO "$WOOSTR.BERTIE.MASTER" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS CUSTOMER-NUMBER FILE STATUS IS MASTER-IN-FILE-STATUS. ... DATA DIVISION. FILE SECTION. FD MASTER-IN LABEL RECORDS ARE OMITTED. 01 MASTER-IN-RECORD. ... WORKING-STORAGE SECTION. ... 01 FILE-STATUSES. 03 MASTER-IN-FILE-STATUS PICTURE XX. ... PROCEDURE DIVISION. ... MOVE 1 TO CUSTOMER-NUMBER START MASTER-IN KEY IS LESS THAN CUSTOMER-NUMBER IF MASTER-IN-FILE-STATUS NOT EQUAL TO ZERO PERFORM START-ERROR-ROUTINE ELSE READ MASTER-IN NEXT RECORD AT END PERFORM WRITE-TOTALS-AND-QUIT END-READ END-IF HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -191 Procedure Division Verbs READ for Sequential or Dynamic Access Example 9-59. Reading $RECEIVE With Timed Input-Output IDENTIFICATION DIVISION. ... ENVIRONMENT DIVISION. ... SELECT REQUEST ASSIGN TO "$RECEIVE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL FILE STATUS IS REQUEST-FILE-STATUS. ... DATA DIVISION. FILE SECTION. FD REQUEST LABEL RECORDS ARE OMITTED. 01 REQUEST-RECORD. ... WORKING-STORAGE SECTION. ... 01 FILE-STATUSES. 03 REQUEST-FILE-STATUS PICTURE XX. ... 01 WAIT-TIME PICTURE PICTURE 9(5)V99 VALUE 30. PROCEDURE DIVISION. DECLARATIVES. DECL SECTION. USE AFTER ERROR PROCEDURE ON REQUEST. DECL-ROUTINE. IF GUARDIAN-ERR NOT = 40 STOP RUN. END DECLARATIVES. MAIN-STUFF SECTION. MAIN-PROCESSING. ... OPEN INPUT REQUEST WITH TIME LIMITS READ REQUEST TIME LIMIT WAIT-TIME IF REQUEST-FILE-STATUS NOT = "00" IF GUARDIAN-ERR = 40 PERFORM NO-MESSAGE END-IF END-IF ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -192 Procedure Division Verbs READ for Line Sequential Files READ for Line Sequential Files READ for line sequential files reads the next record in the file. READ file-name INTO data-name END imperative-stmt-1 AT NOT END imperative-stmt-2 AT END-READ VST630.vsd file-name is the file description name of the file to retrieve a record from. NEXT indicates that the next record is to be read (that is, the record after the current record, according to the key of reference). NEXT is required for sequential reading of a relative, indexed, or queue file whose access is DYNAMIC. data-name is the identifier of the data area defined by your program to which the contents of the record area are transferred after the read operation is complete. data-name cannot be an index-name or the identifier of an index data item. The transfer is conducted as if it were a move from an alphanumeric item to an alphanumeric item. The INTO phrase is allowed only when one of these conditions is true: ° ° Only one record is associated with file-name. The record associated with file-name is defined as a data structure or as an elementary alphanumeric item and data-name is either a data structure or an elementary alphanumeric item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -193 Procedure Division Verbs READ for Line Sequential Files LOCK keeps other programs from accessing the record retrieved until an UNLOCKFILE statement, UNLOCKRECORD statement, or REWRITE UNLOCK statement executes. The file that file-name specifies must be associated with a disk device. imperative-stmt-1 is an imperative statement to be performed when the end of the file is encountered at the beginning of the read operation. This phrase is required if no USE statement is applicable for the file. If both a USE statement and an AT END phrase are present, only the AT END phrase is used. imperative-stmt-2 is an imperative statement to be performed when the end of the file is not encountered at the beginning of the read operation. END-READ ends the scope of the READ statement, causing the READ to be a delimited-scope statement. If the READ statement does not end with an END-READ phrase, the presence of the AT END or the NOT AT END phrase causes the READ statement to be a conditional statement, which ends at the next period separator. See these usage considerations in READ for Sequential or Dynamic Access: • • • • • • • • • • In Action of the READ Statement (Sequential Read): ° ° ° Retrieval of a logical record Alignment within record area Unsuccessful read operation File-Status Data Item Retrieval GUARDIAN-ERR Special Register Handling Exception Conditions Variable-Length Records Setting the Value of the DEPENDING Item (Variable-Length Records) Concept of Next Record Sequential Block Buffering and HP COBOL Fast I-O Eight-Character Volume Names and HP COBOL Fast I-O HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -194 Procedure Division Verbs READ for Random or Dynamic Access READ for Random or Dynamic Access READ is for random or dynamic access reads a record from a file according to the value of a key, rather than according to the present value of the file position indicator. For relative files, READ without NEXT sets the file position indicator to the item selected by RELATIVE KEY (if KEY is omitted) or to the specified alternate key. For indexed and queue files, READ without NEXT sets the file position indicator to the item selected by either the key of reference (if KEY is omitted) or to the specified prime or alternate key. When the selected record exists, the process places its contents in the record area. If it does not exist, an invalid-key condition occurs, and the process executes either the INVALID KEY statement or, if there is no INVALID KEY phrase, a USE AFTER EXCEPTION procedure. When duplicate alternate key values are allowed, the order of records with equal values depends on the INSERTIONORDER parameter of the alternate key file: records with duplicate alternate key values are retrieved in either prime key order (the way NonStop systems software ordinarily works) or in the order in which they were inserted in the file (as specified in the 1985 ISO/ANSI COBOL standard). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -195 Procedure Division Verbs READ READ for Random or Dynamic Access file-name RECORD INTO data-name LOCK WITH TIME LIMIT wait-time KEY key IS INVALID imperative-stmt-1 KEY NOT INVALID KEY imperative-stmt-2 END-READ VST202.vsd file-name is the file description name of the file to retrieve a record from. data-name is the identifier of the data area defined by your program to which the contents of the record area are transferred after the read operation is complete. data-name cannot be an index-name or the identifier of an index data item. The transfer is conducted as if it were a move from an alphanumeric item to an alphanumeric item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -196 Procedure Division Verbs READ for Random or Dynamic Access LOCK keeps other programs from using the record retrieved until an UNLOCKFILE statement, UNLOCKRECORD statement, or UNLOCK phrase is executed on the record. wait-time is the time interval, in seconds, in which the operation must complete. wait-time can be a literal or the name of a data item. In either case, it must have a value described with at most seven digits preceding any decimal point position. Any fractional portion is truncated to two decimal places. If file-name was not opened with a TIME LIMITS phrase, including wait-time in the READ statement causes a run-time error. key is the key of reference. If file-name specifies a relative file, key must be an alternate key for that file. If file name specifies an indexed file, key can be the prime key or an alternate key. If file-name specifies a queue file, key must be the prime key for that file. Unlike the START statement, the KEY clause provides only APPROXIMATE positioning—not GENERIC positioning. When the KEY phrase is absent, the relative key (for a relative file) or the prime record key (for an indexed or queue file) is established as the key of reference. imperative-stmt-1 is an imperative statement to be performed when an invalid key is encountered at the beginning of the READ. It is required if no USE statement is applicable for the file. If both a USE statement and an INVALID KEY phrase are present, only the INVALID KEY phrase is used. imperative-stmt-2 is an imperative statement to be performed when no invalid key is encountered at the beginning of the read operation. END-READ ends the scope of the READ statement, causing the READ to be a delimited-scope statement. If the READ statement does not end with an END-READ phrase, the presence of the INVALID KEY or the NOT INVALID KEY phrase causes the READ statement to be a conditional statement, which ends at the next period separator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -197 Procedure Division Verbs READ for Random or Dynamic Access Usage Considerations: • Action of the READ Statement (Read According to Key Value) The execution of this form of the READ statement proceeds: ° For a file with indexed organization, or a file being accessed according to an alternate key, the run-time routines set the file position indicator to the first record in the file with a key data item value that matches the value in the key of reference. This record is then made available in the file’s record area. ° For a file with relative organization being accessed according to the relative record number, the run-time routines set the file position indicator to the record whose relative record number is contained in the data item named in the RELATIVE KEY clause for the file. This record is then made available in the file’s record area. ° In either case, if no such record exists in the file, the invalid-key condition exists, and the read operation is unsuccessful. A successful execution of the READ statement for a relative file, when the key of reference is an alternate record key, also assigns the relative record number of the retrieved record to the file’s relative key data item. When the execution of the READ statement is successful and the access mode is dynamic, the key of reference established for the read operation is used for subsequent sequential-type READ statements executed for the same file until the execution of some other statement explicitly establishes a different key of reference. • File-Status Data Item If the file has an associated file-status data item, execution of the READ statement always assigns an appropriate I-O status code. One possible I-O status code that results from unsuccessful random or dynamic read operations is: I-O Status Code Unsuccessful Random or Dynamic Read Operation “23” The invalid-key condition exists, and the read operation is unsuccessful HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -198 Procedure Division Verbs READ for Random or Dynamic Access For other possible I-O status codes representing successful and unsuccessful operations, see File-Status Data Item. Note. After an unsuccessful execution of a READ statement, these values are unpredictable: • • • The value of the file position indicator The contents of the current record area The key of reference Any key value found in the current record area: that is, the value of the current key for indexed files or the value of the alternate key for any type of file-system file, because in HP COBOL, sequential and relative files can have alternate keys. • Key of Reference to Specify a Record The program specifies which record is to be read by assigning the appropriate value to the data item established as the key of reference, before the READ statement is to be executed. • Handling Exception Conditions For general exception handling, put declaratives at the beginning of the Procedure Division. They can respond to error conditions arising for a single file or for all files open in the same mode (INPUT, OUTPUT, I-O, or EXTEND). (See USE.) The USE AFTER STANDARD ERROR PROCEDURE statement specifies what to do when a file-manipulating statement encounters an error. Declaratives can be called for AT END, INVALID KEY, and other error conditions. If an invalid-key condition is encountered at the beginning of a read, and the READ statement contains the INVALID KEY phrase, control passes to imperativestmt-1 and no USE procedure is executed. If the READ statement does not contain an INVALID KEY phrase, but an applicable USE procedure exists, that procedure is executed. After an invalid-key condition arises for a relative, indexed, or queue file, sequential read operatons cannot be done on the file until you either: • ° ° ° Close and reopen the file Execute a successful START statement on the file Execute a successful random READ statement on the file Timed Input-Output Errors If a READ statement includes the TIME LIMIT phrase, and the I-O request exceeds the time interval indicated, the codes FILE STATUS 30 and GUARDIAN-ERR 40 are returned. For information about the special register GUARDIAN-ERR, see Diagnosing Input-Output Errors. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -199 Procedure Division Verbs • RELEASE See these usage considerations in READ for Sequential or Dynamic Access: ° ° ° ° ° ° ° File-Status Data Item LOCK Phrase Interaction of LOCKFILE and READ LOCK Statements INTO Phrase GUARDIAN-ERR Special Register Variable-Length Records Use of wait-time Example 9-60. Reading a Random Indexed File SELECT MASTER-IN ASSIGN TO "MASTER" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS INVOICE-NUMBER. ... PROCEDURE DIVISION. ... MOVE WS-INVOICE-NUMBER TO INVOICE-NUMBER READ MASTER-IN INVALID KEY PERFORM RANDOM-READ-ERROR-RTN END-READ RELEASE RELEASE, which must be within a SORT input procedure, sends the next input record to the sorting process. RELEASE record-name FROM data-name VST203.vsd record-name is a record-name in a sort-merge file description (SD) entry. data-name is the identifier of the item containing the record to be sent. Before the record is sent, it is moved to record-name. For more details and an example, see SORT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -200 Procedure Division Verbs REPLACE REPLACE REPLACE substitutes zero or more words of pseudotext for one or more words of pseudotext. You can use REPLACE in any division. For more information, see REPLACE Statement. RETURN RETURN, which must be within a SORT or MERGE output procedure, gets the next output record from the SORT or MERGE. RETURN file-name INTO END data-name imperative-stmt-1 AT NOT END imperative-stmt-2 AT END-RETURN VST204.vsd file-name is a file name described by a sort-merge file description (SD) entry. data-name is the identifier of the area in your program (other than record area associated with file-name ) where the record is stored. imperative-stmt-1 is an imperative statement to be performed when the end of the file is encountered at the beginning of the return operation. This phrase is required. imperative-stmt-2 is an imperative statement to be performed when the end of the file is not encountered at the beginning of the return operation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -201 Procedure Division Verbs REWRITE END-RETURN ends the scope of the RETURN statement, causing the RETURN to be a delimitedscope statement. If the RETURN statement does not end with an END-RETURN phrase, the presence of the AT END or the NOT AT END phrase causes the RETURN statement to be a conditional statement, which ends at the next period separator. For more details and an example, see: • • SORT MERGE REWRITE REWRITE replaces an existing record in a disk file that is open for I-O. Forms: • • REWRITE for Sequential, Relative, Indexed, and Queue Files REWRITE for Line Sequential Files REWRITE for Sequential, Relative, Indexed, and Queue Files REWRITE record-name FROM data-name UNLOCK WITH INVALID imperative-stmt-1 KEY NOT INVALID KEY imperative-stmt-2 END-REWRITE VST205.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -202 Procedure Division Verbs REWRITE for Sequential, Relative, Indexed, and Queue Files record-name is the record-name in a file description entry whose current contents replaces a record in the file. The file must be open in I-O mode. data-name is the identifier of the item that contains the new record instead of record-name. When this phrase is used, an implicit MOVE statement occurs to copy the data to record-name before the rewrite operation occurs. data-name cannot specify an index-name or an index data item. data-name cannot specify a data item allocated within the record area in which record-name is located. UNLOCK permits access by other processes to a record (after the rewrite operation) that was previously locked with a LOCK phrase. imperative-stmt-1 is an imperative statement to be performed when an invalid-key condition is encountered by the REWRITE operation. It is required if no USE statement is applicable for the file. If both a USE statement and an INVALID KEY phrase are present, only the INVALID KEY phrase is used. imperative-stmt-2 is an imperative statement to be performed when no invalid-key condition is encountered by the REWRITE operation. END-REWRITE ends the scope of the REWRITE statement, causing the REWRITE to be a delimited-scope statement. If the REWRITE statement does not end with an ENDREWRITE phrase, the presence of the INVALID KEY or the NOT INVALID KEY phrase causes the REWRITE statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • Action of the REWRITE Statement The rewrite operation releases a logical record to the run-time routines as a replacement for a record that exists in the file. The size of the logical record (the number of character positions in the record) is determined: ° When the file has fixed length records (the file description entry includes a RECORD CONTAINS n CHARACTERS, or contains no RECORD clause at all), the size of the logical record is the fixed record size. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -203 Procedure Division Verbs REWRITE for Sequential, Relative, Indexed, and Queue Files ° When the file has variable-length records whose sizes are controlled by the DEPENDING item specified in the RECORD clause (RECORD VARYING SIZE DEPENDING name), the value of the DEPENDING item determines the size of the logical record. ° When the file has variable-length records but no DEPENDING item is specified in the RECORD clause of the file description entry (RECORD CONTAINS m TO n CHARACTERS), the size of the logical record is the size of the data item referenced by record-name. If the data item has a variable size because it contains a table that is described with an OCCURS DEPENDING clause, the current size of the item is used. When the file is described with the RECORD VARYING clause, the logical record size must not be greater than the maximum or less than the minimum number of character positions specified in that clause. (See I-O status code “44.”) The content of the logical record released by the rewrite operation is the leftjustified value of the data item specified by record-name. If the logical record size is greater than the data item’s size, the value is logically extended on the right with arbitrary characters (that is, you cannot predict what the extending characters will be). If the logical record size is less than the data item’s size, the value is logically truncated on the right. The execution of a REWRITE statement, whether successful or not, does not normally affect the key of reference, the value of file position indicator, or the value of the depending item specified in the DEPENDING phrase of the RECORD clause associated with record-name ; however, the value of the file position indicator can be left undefined in some cases when the I-O status is set to 30. Note. The logical record released by a successful execution of the REWRITE statement is no longer available in the record area unless the file name associated with record-name is specified in a SAME RECORD AREA clause. The logical record is available to the program as a record of other files referenced in the SAME RECORD AREA clause as the associated output file, as well as the file associated with record-name. • File-Status Data Item If the file has an associated file-status data item, execution of the REWRITE statement always assigns an appropriate I-O status code as its value. The status “00” reports a successful rewrite operation with no duplicate alternate keys written. The status code “02” reports a successful rewrite operation that created a duplicate alternate key value for at least one alternate record key for which duplicates are allowed (only when the file has the INSERTIONORDER attribute). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -204 Procedure Division Verbs REWRITE for Sequential, Relative, Indexed, and Queue Files The rewrite operation cannot succeed if the device associated with the file is not a disk device. Note. After an unsuccessful execution of a REWRITE statement, these values are unpredictable: • • • The value of the file position indicator The contents of the current record area The key of reference Any key value found in the current record area: that is, the value of the current key for indexed files or the value of the alternate key for any type of file-system file, because in HP COBOL sequential and relative files can have alternate keys. The possible I-O status codes for an unsuccessful rewrite are: I-O Status Code Unsuccessful Rewrite (page 1 of 2) “21” The file’s access mode is sequential, the file organization is indexed, and the prime record key value of the logical record is not equal to the value of the prime record key of the last record read. The invalid-key condition arises. “22” One of the alternate key values in the logical record is equal to the value of that key in a record that already exists in the file, and the DUPLICATES phrase is not specified for that key. The invalid-key condition arises. “23” The file’s access mode is random or dynamic, and the specified relative key value or prime record key value does not correspond to that of any record existing in the file. The invalid-key condition arises. “30” The rewrite operation failed due to non-COBOL causes. The specified record might or might not have been rewritten. The runtime routines always return this status when the file is not assigned to a disk, in which case nothing is rewritten. The value of the file position indicator can be left undefined in some cases when the I-O status code is “30.” Whenever the rewrite operation terminates with an I-O status code greater than or equal to “30,” execution of the REWRITE statement is unsuccessful. In this case, the applicable USE procedure, if any, is executed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -205 Procedure Division Verbs REWRITE for Sequential, Relative, Indexed, and Queue Files I-O Status Code Unsuccessful Rewrite (page 2 of 2) “43” The access mode is sequential, and the last input or output statement executed for the file was not a successful READ statement. The record is not released. “44” There are two possibilities: • • “49” • The file is described with the RECORD VARYING clause, and the logical record size is greater than the maximum or less than the minimum number of character positions specified in that clause. The logical record is not released. The file is a sequential file described with the RECORD VARYING clause, and the size of the logical record is not equal to the size of the record being replaced. The logical record is not released. The file is not open in I-O mode. The rewrite operation terminates immediately. Access Mode and REWRITE ° Sequential-access files When a sequential file has variable-length records, the number of character positions in the logical record specified by record-name must be equal to the number of character positions in the record being replaced. If this is not so, the rewrite operation is unsuccessful and terminates with I-O status code “44.” When the access mode of the file affected by the rewrite operation is sequential, the last input-output statement executed for the file must have been a successful READ statement. If it was not, the record is not released and the rewrite operation terminates with the I-O status code “43;” otherwise, the rewrite operation logically replaces the record that was accessed by the READ statement; therefore, for an indexed or queue file, the program logic must verify that the prime record key in the logical record has the same value as the prime record key of the record previously read. ° Random-access or dynamic-access files For relative files with random or dynamic access, the record replaced is the one indicated by the value of the RELATIVE KEY item. If the old record does not exist, an invalid-key condition occurs. For indexed files with random or dynamic access or for files being accessed through alternate keys using random or dynamic access, the prime record key data item (the RECORD KEY item) selects the old record to be replaced. The value of alternate keys can differ in the new records, unless this would create duplicate key values for a key whose values must be unique. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -206 Procedure Division Verbs • REWRITE for Sequential, Relative, Indexed, and Queue Files UNLOCK Phrase If the UNLOCK phrase appears, the rewrite operation also assures that the record is not in the locked state at the completion of the rewrite operation. If the record was not in the locked state at the beginning of the rewrite operation, no report of this is made to the program. • Invalid-Key Condition Any of these circumstances can lead to an invalid-key condition: ° The access mode is sequential, the file organization is indexed, and the prime record key value of the logical record is not equal to the value of the prime record key of the last record read. This results in a completion status of 21. ° The access mode is random or dynamic, and the specified relative key value or prime record key value does not correspond to that of any record existing in the file. This results in I-O status code “23.” ° One of the alternate key values in the logical record is equal to the value of that key in a record that already exists in the file, and the DUPLICATES phrase is not specified for that key. This results in an I-O status code of “22.” When the invalid-key condition exists, the rewrite operation does not occur and execution of the REWRITE statement is unsuccessful. The content of the record area is unaffected. If the INVALID KEY phrase is specified, control passes to the imperative statement in that phrase and no USE procedure is executed. If the INVALID KEY phrase is not specified but an applicable USE procedure exists, that procedure is executed. When the invalid-key condition does not exist, and the rewrite operation is successful, and the NOT INVALID KEY phrase is specified, control passes to the imperative statement in that phrase. Example 9-61. REWRITE Statement for Indexed File READ MASTER-IN WITH LOCK IF NO-ERROR PERFORM GET-INPUT REWRITE MASTER-RECORD WITH UNLOCK IF NO-ERROR ADD 1 TO UPDATE-COUNTER ELSE UNLOCKRECORD MASTER-IN END-IF ELSE ... Note. Invalid-key conditions are taken care of by USE procedures instead of by INVALID KEY phrases on the READ and REWRITE statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -207 Procedure Division Verbs REWRITE for Line Sequential Files REWRITE for Line Sequential Files REWRITE FROM record-name data-name END-REWRITE VST721.vsd record-name is the record-name in a file description entry whose current contents replaces a record in the file. The file must be open in I-O mode. data-name is the identifier of the item that contains the new record instead of record-name. When this phrase is used, an implicit MOVE statement occurs to copy the data to record-name before the rewrite operation occurs. data-name cannot specify an index-name or an index data item. data-name cannot specify a data item allocated within the record area in which record-name is located. END-REWRITE ends the scope of the REWRITE statement, causing the REWRITE to be a delimited-scope statement. If the REWRITE statement does not end with an ENDREWRITE phrase, the REWRITE ends at the next period separator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -208 Procedure Division Verbs SEARCH 9 Procedure Division Verbs SEARCH SEARCH scans a table for an element that satisfies a condition. If SEARCH finds the element, SEARCH sets an index-name to the element’s offset value. Form Description SEARCH VARYING Performs a serial search beginning with the current index. Can also set the value of a data item or another index-name. SEARCH ALL Performs a binary search until it finds the element satisfying the conditions or has searched every element of the table. Before executing SEARCH, the program must: • • Initialize the relevant index-names and the table with appropriate values Determine what criteria define successful completion of the search operation A search proceeds by successively selecting candidates from among the elements of the table and then evaluating the test conditions. For a variable-size table, only elements currently defined as a part of the table can be searched. The last of these is the one referenced by the maximum occurrence number, which is the value of the associated DEPENDING data item. The search ends when a condition evaluates to TRUE or when every element of the table has been searched, whichever occurs first. SEARCH operates on a single table dimension. To search an entire multi-dimensional table, the program must execute a SEARCH for each dimension, beginning with the outermost table level and ending with the innermost table level. SEARCH VARYING SEARCH VARYING performs a serial search beginning with the current index setting. SEARCH VARYING can also set the value of a data item or another index-name. SEARCH table END VARYING indexer imperative-stmt-1 AT WHEN condition imperative-stmt-2 NEXT SENTENCE END-SEARCH VST206.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -209 Procedure Division Verbs SEARCH VARYING table is the name of a data item described with an “OCCURS … INDEXED BY index-1 … KEY …” clause. The search is done with index-1, which the search operation initializes to the middle of the table before beginning to scan. Only the name of table can appear, qualified if necessary, but not subscripted or reference modified. indexer is one of: ° ° ° One of the index-names in the INDEXED phrase in the definition of table An integer data item (which can, itself, be subscripted) An index data item indexer cannot specify a special register. indexer cannot be subscripted by the first (or the only) index-name specified in the INDEXED phrase of the OCCURS clause of the definition of table. When indexer is from the INDEXED phrase, that index is used to start the search. When it is a separate item, index-1 from the INDEXED option is used to search table, and indexer is incremented by 1 when index-1 is incremented. The SEARCH statement does not initialize its index (either indexer or index-1 ). The value of the index at the time the search begins is used. imperative-stmt-1 is an imperative statement to be executed when an at-end condition is detected during the search. condition specifies a conditional expression used to control the search for an element. imperative-stmt-2 is an imperative statement to be executed when a condition is satisfied. NEXT SENTENCE specifies that control be passed directly to the end of the SEARCH statement. It is not recommended (see Usage Considerations:). END-SEARCH ends the scope of the SEARCH statement, causing the SEARCH to be a delimitedscope statement. Without the END-SEARCH phrase, the SEARCH statement is a conditional statement, which ends at the next period separator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -210 Procedure Division Verbs SEARCH VARYING Usage Considerations: • CONTINUE is Recommended Over NEXT SENTENCE NEXT SENTENCE transfers control to the next period (.), while CONTINUE transfers control to END-SEARCH. Either imperative-stmt-1, imperativestmt-2, or both can be CONTINUE statements. • Execution The SEARCH VARYING statement specifies a serial search through elements of the table referenced by table. In general terms, the search operation successively increments the value of an index-name, which represents the occurrence number of an element in the table, until either some condition evaluates to TRUE or the occurrence number represented by the value of the index-name exceeds the maximum defined for the table. When the VARYING phrase is present, and if it specifies an index-name associated with table (by its OCCURS clause), then that index-name is used for the search. If it specifies an index-name not associated with table, or if it specifies a separate integer data item or an index data item, the primary index of table is used in the search (starting at its current setting), and these operations occur: ° If you specify an index-name associated with another table, the process increments the occurrence number that index-name represents by the same amount and at the same time as it increments the occurrence number the primary index represents. ° If you specify an index data item, the process increments the value of the item by the same amount and at the same time as it increments the index associated with table. ° If you specify an integer data item, the process increments the value of the item by 1 at the same time as it increments the index associated with table. Without the VARYING phrase, the search varies the value of the primary index of table (starting at its current setting). Any other indexes specified with table remain unchanged. If, when execution of the SEARCH statement begins, the value of the index-name corresponds to an occurrence number greater than the one that identifies the last element of the table, the at-end condition exists and the search operation terminates immediately; otherwise, the search operation proceeds: 1. Each condition is evaluated, in the order in which they appear in the statement, until one of them evaluates to TRUE or all of them evaluate to FALSE. For each operand of a condition, the process of operand identification occurs just prior to its use each time the operand participates in the determination of that condition’s value. For details, see Condition Evaluation Rules. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -211 Procedure Division Verbs SEARCH VARYING 2. When a condition evaluates to TRUE, the search operation terminates immediately. If that condition is followed by the NEXT SENTENCE phrase, control passes to the next executable sentence; otherwise, the associated imperative-stmt-2 is executed and control passes to the end of the SEARCH statement (unless the imperative-stmt-2 explicitly transfers control elsewhere using a GO TO statement). 3. When all conditions evaluate to FALSE, the index-name value is incremented to correspond to the next occurrence number. 4. When the new value of the search index-name corresponds to an occurrence number greater than the one that identifies the last element of the table, the atend condition exists and the search operation terminates immediately; otherwise, the search operation repeats from Step 1. When the search operation terminates due to the at-end condition, imperativestmt-1 is executed, if the AT END phrase is specified. Control then passes to the end of the SEARCH statement (unless imperative-stmt-1 explicitly transfers control elsewhere using a GO TO statement). • Multidimensional Tables If table is an element of another table, you have a multidimensional table. Each dimension of the multidimensional table must be declared with an INDEXED phrase. A SEARCH statement uses only the first index of each dimension. To search an entire multidimensional table, you must execute several SEARCH statements. Before each execution of a SEARCH statement, you must execute a SET statement to adjust index-names to appropriate settings. The index-names must be used in the SEARCH statement’s condition. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -212 Procedure Division Verbs SEARCH VARYING Figure 9-11. Execution of a SEARCH VARYING Statement With WHEN Phrases Enter TRUE Index is indexer FALSE AT END? TRUE indexer from INDEXED BY? FALSE Index is index-1 from INDEXED BY Index >max ? Increment index FALSE TRUE Execute imperative-stmt-1 Another WHEN? TRUE FALSE Index is indexer ? FALSE Increment indexer TRUE FALSE condition ? TRUE FALSE NEXT Execute SENTENCE imperative-stmt-2 ? TRUE Execute next sentence Exit VST514.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -213 Procedure Division Verbs SEARCH ALL Example 9-62. SEARCH VARYING Statement WORKING-STORAGE SECTION. 01 COMMANDS. 05 FILLER PIC X(6) VALUE "ADD". 05 FILLER PIC X(6) VALUE "DELETE". ... 01 COMMANDS-IN-TABLE REDEFINES COMMANDS. 05 COMMAND-ENTRIES PIC X(6) OCCURS 6 TIMES INDEXED BY TABLE-INDEX. 77 COMMAND-IN PIC X(6). ... PROCEDURE DIVISION. ... SET TABLE-INDEX TO 1 SEARCH COMMAND-ENTRIES VARYING TABLE-INDEX AT END PERFORM COMMAND-ERROR-ROUTINE WHEN COMMAND-ENTRIES(TABLE-INDEX) = COMMAND-IN CONTINUE END-SEARCH ... SEARCH ALL SEARCH ALL performs a binary search on a table. The table must be declared with a KEY phrase in its OCCURS clause. SEARCH ALL table END imperative-stmt-1 AT WHEN match-1 AND match-n imperative-stmt-2 NEXT SENTENCE END-SEARCH VST207.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -214 Procedure Division Verbs SEARCH ALL table is the name of a data item described with an “OCCURS … INDEXED BY index-1 … KEY …” clause. The search is done with index-1, which the search operation initializes to the middle of the table before beginning to scan. Only the name of table can appear, qualified if necessary, but not subscripted or reference modified. imperative-stmt-1 is an imperative statement to be executed when an at-end condition is detected (the end of the search is reached with no entry satisfying all specified conditions). match-1 match-n identifier-1 equal-part identifier-2 literal-2 arithmetic-expression-2 condition-name-1 VST208.vsd are matches that terminate the search operation. identifier-1 is a data-name that is subscripted by the first index-name listed in the INDEXED clause that defines the indexes of table, along with any other subscripts that are required to identify the element in a multidimensional table. identifier-1 must be defined as the first key of table. It can be qualified, but it cannot include a reference modifier. equal-part EQUAL IS TO = VST209.vsd identifier-2 is any identifier. literal-2 is any literal. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -215 Procedure Division Verbs SEARCH ALL arithmetic expression-2 is any arithmetic expression. condition-name-1 is a condition (a level-88 item) that terminates the search operation. condition-name-1 must be defined as having a single value. The dataname with which condition-name-1 is associated must be specified as the first in the KEY phrase of the OCCURS clause of table. imperative-stmt-2 is an imperative statement to be executed when the condition that conditionname-1 specifies is satisfied. NEXT SENTENCE specifies that control be passed directly to the end of the SEARCH statement. It is not recommended (see Usage Considerations:). END-SEARCH ends the scope of the SEARCH statement, causing the SEARCH to be a delimitedscope statement. Without the END-SEARCH phrase, the SEARCH statement is a conditional statement, which ends at the next period separator. Usage Considerations: • CONTINUE is Recommended Over NEXT SENTENCE NEXT SENTENCE transfers control to the next period (.), while CONTINUE transfers control to END-SEARCH. Either imperative-stmt-1, imperativestmt-2, or both can be CONTINUE statements. • Binary Search HP COBOL performs a binary search when these conditions are met: ° Each condition-name referenced in the WHEN clause must be defined as having a single value. ° The data-name associated with a condition-name must appear in the KEY phrase in the OCCURS clause of the data definition of table. ° Each identifier-1 must be subscripted by the first index-name associated with table, along with other subscripts as required, and must be referenced in the KEY phrase in the OCCURS clause of the data definition of table. ° The identifiers mentioned in the operands must not be referenced in the KEY phrase in the OCCURS clause associated with table, and must not be subscripted by the first index-name associated with table. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -216 Procedure Division Verbs ° SEARCH ALL When a data-name in the KEY phrase of the OCCURS clause associated with table is referenced, or when a condition-name associated with such a dataname is referenced, all preceding data-names (or the associated conditionnames) in the KEY phrase of that OCCURS clause must also be referenced. When a SEARCH ALL statement does not meet these conditions, the compiler issues a warning and does a linear search. • Additional Syntactic Constraints If the WHEN phrase mentions either a data-name in the KEY phrase of the OCCURS clause of the definition of table or a condition-name associated with a data-name in that KEY phrase, all preceding data-names in the KEY phrase must also be mentioned in the WHEN phrase. To illustrate, suppose you have this OCCURS clause: 05 DEPT-TABLE OCCURS 500 TIMES ASCENDING KEY IS DIV SEC DEPARTMENT INDEXED BY NDEX, MDEX. 07 DIV PIC 9(4). 07 SEC PIC 9(3). 07 DEPARTMENT PIC 9(3). 88 R-AND-D VALUE 555. You can search on DIV, or DIV and SEC, or all three keys. You cannot search on SEC without searching on DIV, and you cannot search on DEPARTMENT without searching on DIV and SEC. • Order of Table Elements Verify that the table is ordered as specified in the ASCENDING or DESCENDING phrase of the OCCURS clause of the table’s definition. If it is not, the result of the search is undefined. • Execution The SEARCH ALL statement specifies a search through the elements of a table. The results of a SEARCH ALL statement are predictable only when both of these are true: ° The data in the table are ordered in the manner described in the KEY phrase of the OCCURS clause that describes the table. ° The condition specified in the WHEN phrase (called the “target condition”) evaluates to TRUE only during the consideration of exactly one of the table elements. The search operation varies the value of the first index-name that appears in the INDEXED phrase of the OCCURS clause describing the table. The search operation insures that the varying value always corresponds to an occurrence number defined for the table. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -217 Procedure Division Verbs SEARCH ALL The SEARCH ALL operation proceeds in a binary fashion, successively setting the index-name to correspond to different table elements and evaluating the target condition. For each operand of the target condition, the process of operand identification occurs just before its use each time the operand participates in the determination of the value of the target condition. • When Exactly One Matching Element Is Found When the target condition evaluates to TRUE, the search all operation terminates and the value of the index-name corresponds to the element under consideration. If the NEXT SENTENCE phrase is specified, control passes to the next executable sentence; otherwise, imperative-stmt-2 is executed and then control passes to the end of the SEARCH ALL statement (unless execution of imperativestmt-2 explicitly transfers control elsewhere using a GO TO statement). If more than one element satisfies the condition, the index can point to any one of them. • When No Matching Element Is Found When the value of the target condition is FALSE, the search operation terminates with the at-end condition and the value of the index-name is undefined. If the AT END phrase is specified, imperative-stmt-1 is executed. Control passes to the end of the SEARCH statement (unless execution of imperative-stmt-2 explicitly transfers control elsewhere using a GO TO statement). • Tables Defined With a DEPENDING Phrase For a variable-occurrence table, only those elements currently defined as a part of the table can be candidates. The last of these is the one specified by the maximum occurrence number, which is the value of the associated DEPENDING data item. • Index Values During the search operation, the first index-name appearing in the INDEXED phrase of the OCCURS clause describing the table is varied so that its value always corresponds to an occurrence number defined for the table. The value of this index-name at the start of execution of the SEARCH statement is immaterial. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -218 Procedure Division Verbs SET Example 9-63. SEARCH ALL Statement WORKING-STORAGE SECTION. 01 COMMANDS. 05 FILLER PIC X(6) VALUE "ADD". 05 FILLER PIC X(6) VALUE "DELETE". 05 FILLER PIC X(6) VALUE "EXIT". 05 FILLER PIC X(6) VALUE "LIST". ... 01 COMMANDS-IN-TABLE REDEFINES COMMANDS. 05 COMMAND-ENTRIES PIC X(6) OCCURS 6 TIMES ASCENDING KEY IS COMMAND-ENTRIES INDEXED BY TABLE-INDEX. ... 01 COMMAND-NUMBERS. 05 COMMAND-INDEX PIC 99 COMP VALUE 1. 05 COMMAND-IN PIC X(6). ... PROCEDURE DIVISION. ... SEARCH ALL COMMAND-ENTRIES AT END PERFORM COMMAND-ERROR-ROUTINE GO TO GET-ANOTHER-COMMAND WHEN COMMAND-ENTRIES(TABLE-INDEX) = COMMAND-IN CONTINUE END-SEARCH SET COMMAND-INDEX TO TABLE-INDEX ... SET Form Description SET TO Sets the values of data item addresses, indexes, switches, or conditional variables SET UP or SET DOWN Increments or decrements data item addresses or indexes SET TO SET TO sets the values of data item addresses, indexes, switches, or conditional variables. Topics: • • POINTER Data Items Nonpointer Data Items HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -219 Procedure Division Verbs SET TO POINTER Data Items SET TO pointer address VST605.vsd pointer ADDRESS OF identifier-1 identifier-2 VST606.vsd address ADDRESS OF identifier-3 identifier-4 NULL NULLS VST607.vsd identifier-1 is a level-01 or level-77 data item in the Linkage Section that does not have an ACCESS MODE STANDARD clause in its data description entry. If pointer is ADDRESS OF identifier-1, identifier-1 is relinked so that subsequent references to identifier-1 reference the item whose address is specified by address. If address is ADDRESS OF identifier-3, then identifier-1 is linked to the address of identifier-3 (not the value of identifier-3 ). If address is identifier-4, then identifier-1 is linked to the address that identifier-4 contains. If address is NULL or NULLS, then identifier-1 is linked to a null address guaranteed to point to no data item. identifier-2 is a data item with USAGE POINTER. If pointer is identifier-2, the address specified by address is moved into identifier-2. This address is valid until the program terminates or returns control to its calling program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -220 Procedure Division Verbs SET TO identifier-3 is a data item of any level except 88, anywhere in the Data Division. The value of ADDRESS OF identifier-3 is the address of identifier-3, not the value of identifier-3. identifier-4 is a data item with USAGE POINTER. NULL NULLS is a null address guaranteed not to point to any data item. A reference to a pointer whose value is NULL causes a trap 1 instruction failure. If you redefine a VS COBOL II pointer variable as a COMPUTATIONAL field and perform an arithmetic operation on the field to change the value of the pointer, the pointer does not behave the same as it would in IBM/370 COBOL. The reason is that pointer format depends on machine architecture, and NonStop servers and IBM/370 machines have different architectures. Nonpointer Data Items SET TO can: • • • • • Set an index-name to one of these values: ° A value that corresponds to the occurrence number designated by another index-name ° A value that corresponds to the occurrence number corresponding to the value of an integer literal or an integer data item ° The value of an index data item Set the value of an index data item to the value of an index-name or the value associated with the contents of another index data item Set the value of an integer data item to the occurrence number of an index Set an external switch to ON or OFF Set a conditional variable to a value that makes an associated condition true HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -221 Procedure Division Verbs SET TO SET TO identifier-1 identifier-2 index-name-2 index-name-1 integer mnemonic-name TO ON OFF condition-name TO TRUE VST211.vsd identifier-1 is the name of an integer elementary item or an index data item to be set. identifier-2 is the name of an integer data item or an index data item. index-name-1 is the name of an index to be set. index-name-2 is the name of an index. integer is a numeric literal having no fractional part. If signed, it must have a positive value. mnemonic-name is the mnemonic name associated with an external switch in the SPECIAL-NAMES paragraph of the Environment Division. A SET statement can refer to any of the 15 external switches. condition-name is the condition-name (level-88 item) associated with a conditional variable. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -222 Procedure Division Verbs SET TO Usage Considerations: • Index-Names and Index Data Items An index-name is directly associated with a table and is declared in the INDEXED phrase of the table’s data description entry. The value associated with an indexname is related only to the table with which it is defined. An index data item is a separate data item, not associated with any table, that is declared with the USAGE INDEX clause. • Copying and Converting Values The SET statement performs copying between indexes and index data items. It also performs conversions from indexes to integer data items (occurrence numbers) or from integer data items (occurrence numbers) to indexes. This conversion is necessary because the values associated with indexes and index data items are machine-architecture related, whereas the occurrence numbers are not. Table 9-10 summarizes these rules: ° The receiving item (index-name-n ) is set to a value causing it to refer to the table element corresponding in occurrence number to the table element specified by the sending item (identifier-1, index-name-1, or integer ). If the sending item is an index data item, or if it is an index-name that is related to the same table as the receiving item, no conversion occurs. ° If the receiving item is an index data item, it can be set equal to the contents of either an index-name or another index data item. No conversion occurs. ° If the receiving item is not an index data item, it can be set only to an occurrence number corresponding to the value of an index-name. The sending item cannot be a numeric integer literal or a numeric integer data item. ° The assignment process is repeated for any other receiving data-names specified. Each time, the value of a sending data item is used as it was at the beginning of the execution of the statement. Any subscripting or indexing associated with the sending data item is evaluated immediately before the value of the receiving data item is changed. Table 9-10. Valid SET TO Combinations Receiving Item Sending Item Integer Data Item Index-Name Index Data Name Integer literal No (rule 3) OK (rule 1) No (rule 2) Integer data item No (rule 3) OK (rule 1) No (rule 2) Index-name OK (rule 3) OK (rule 1) OK (rule 2)* Index data item No (rule 3) OK (rule 1) OK (rule 2)* * No conversion occurs HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -223 Procedure Division Verbs • SET TO Index Values Before and After Execution If the sending item is an index-name, then before the execution of the SET TO statement, the value of the index must correspond to an occurrence number of an element in the associated table. If the receiving item is an index-name, then after the execution of the SET TO statement, the value of the index must correspond to an occurrence number of an element in the associated table. • External Switches The SET statement modifies the status of the external switch associated with each specified mnemonic-name. When the SET statement changes the status of a switch to ON, any condition-name associated (in the SPECIAL-NAMES paragraph) with the ON setting of that switch evaluates to TRUE. When the SET statement changes the status of a switch to OFF, any condition-name associated (in the SPECIAL-NAMES paragraph) with the ON setting of that switch evaluates to FALSE. • Condition Names The SET statement assigns to the conditional variable associated with the condition-name the value of the first literal in the VALUE clause of the definition of the condition-name. When more than one condition-name appears in the SET statement, the results are the same as if a separate SET statement had been written for each condition-name in the same order as specified in the SET statement. • integer Out of Range In the statement SET index-name-n TO integer the value of integer must be at least zero and not greater than the maximum number of occurrences plus one. If the value of integer is outside this range, a warning message is produced. If the warning message is produced and subscript checking is active, the run unit terminates abnormally. If the value of integer is greater than 2,147,483,647 or less than 2,147,483,648, or if the product of integer and the occurrence length of the associated table (the length of one occurrence of the table) is not within that range, a run-time error occurs. • Any Sending Item Out of Range If the value of any sending item (identifier-1, index-name-1, or integer ) is greater than 2,147,483,647 or less than -2,147,483,648 and subscript checking is active, an error message is produced and the run unit terminates abnormally. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -224 Procedure Division Verbs SET UP or SET DOWN SET UP or SET DOWN SET UP increments data items addresses or indexes; SET DOWN decrements them. Topics: • • POINTER Data Items Nonpointer Data Items POINTER Data Items SET UP increments a pointer by an integral number of memory locations. SET DOWN decrements a pointer by an integral number of memory locations. SET UP pointer BY number-of-locations DOWN VST608.vsd pointer is a data item with USAGE POINTER. In these parameter descriptions, assume that the value of pointer is the address p. number-of-locations identifier-1 integer VST609.vsd identifier-1 is either an elementary numeric data item described as an integer or a function that returns an integer value. If number-of-locations is identifier-1, and the value of identifier-1 is n, then pointer is adjusted so that it references the address p +n bytes for SET UP or p -n bytes for SET DOWN. integer is a numeric literal whose value is an integer. If number-of-locations is integer, then pointer is adjusted so that it references the address p +integer bytes for SET UP or p -integer bytes for SET DOWN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -225 Procedure Division Verbs SET UP or SET DOWN Usage Considerations: • Do Not Use SET UP or SET DOWN for Record Pointers Do not use SET UP or SET DOWN to point a record pointer at a different record. This would be syntactically correct, but the memory positions of records are not defined in HP COBOL and can vary between implementations. • Incompatibility With IBM/370 Mainframe Pointer Variables If you redefine a VS COBOL II pointer variable as a COMP field and perform an arithmetic operation on the field to change the value of the pointer, the pointer does not behave the same as it would in IBM/370 COBOL. The reason is that pointer format depends on machine architecture, and HP and IBM/370 machines have different architectures. Nonpointer Data Items SET UP increments an index value by an integer amount. SET DOWN decrements an index value by an integer amount. SET index-name UP DOWN BY identifier integer VST212.vsd index-name is the name of an index whose value is to be incremented or decremented. identifier is the identifier of an integer numeric item whose value UP adds to the index or DOWN subtracts from the index. integer is an integer that UP adds to the index or DOWN subtracts from the index. It can be signed. The value of each index-name is incremented (UP) or decremented (DOWN) by a value corresponding to the number of occurrences represented by identifier or integer. Each time, the identifier of an integer numeric item is used as it was at the beginning of the execution of the statement. Both before and after the execution of the SET statement, the value of the index must correspond to an occurrence number of an element in the associated table. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -226 Procedure Division Verbs SORT SORT SORT orders a set of records according to one or more keys. The records can either be in a file or an input procedure can send them to SORT, one at a time. SORT can either write the sorted records to a file or it can send them to an output procedure, one at a time. SORT calls the FastSort utility. SORT sd-name key-specifier DUPLICATES phrase COLLATING SEQUENCE phrase input-specifier-1 output-specifier-1 input-specifier-2 output-specifier-2 VST213.vsd sd-name is the file name given in a sort-merge file description (SD) entry. key-specifier ASCENDING ON DESCENDING key KEY VST214.vsd specifies one or more of the items described in the record descriptions of sdname. key is used to sort the records in ascending or descending order. The first key is compared first, the second next, and so on. Two records equal in all sort keys are sorted by their original order in the file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -227 Procedure Division Verbs SORT DUPLICATES phrase DUPLICATES WITH IN ORDER VST215.vsd specifies that, if two or more records contain equal values for all sort keys, their final order within the sort file is the order in which they were released to the sort file. If this phrase is omitted, the order of such duplicate records is arbitrary. COLLATING SEQUENCE phrase SEQUENCE COLLATING alphabet-name IS VST216.vsd specifies a collating sequence for sorting. The alphabet-name must be associated with a sorting sequence in the SPECIAL-NAMES paragraph of the Environment Division (see SPECIAL-NAMES Paragraph). input-specifier-1 INPUT PROCEDURE inproc-1 IS THROUGH inproc-2 THRU VST217.vsd specifies a procedure that sends records one at a time to SORT using one or more RELEASE statements. The procedure input-specifier-1 cannot terminate before it finishes sending records. inproc-1 inproc-2 are sections or paragraphs of the Procedure Division. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -228 Procedure Division Verbs SORT input-specifier-2 USING infile VST381.vsd specifies one or more files (a maximum of 31) that contain the records to be sorted. infile is a file description name. During execution of the SORT statement, infile must either be closed or be open in another process or by another file description entry, but not in conflict with a following open for protected input. output-specifier-1 OUTPUT PROCEDURE outproc-1 IS THROUGH outproc-2 THRU VST218.vsd specifies a procedure that processes the sorted records, one at a time. Each record is returned by a RETURN statement. The procedure output-specifier1 cannot terminate before it finishes returning all the sorted records. outproc-1 outproc-2 are sections or paragraphs of the Procedure Division. output-specifier-2 GIVING outfile VST382.vsd specifies one or more files (a maximum of 31) where the sorted records are to be written. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -229 Procedure Division Verbs SORT outfile is a file description name. During execution of the SORT statement, outfile must be closed and cannot be locked. Usage Considerations: • Using the Features of FastSort Three utility routines that enable you to control the features of FastSort (such as multi-processor parallel sorting) are: Non-CRE Routine CRE Routine COBOL85^SET^SORT^PARAM^VALUE COBOL85_SET_SORT_PARAM_VALUE_ COBOL85^SET^SORT^PARAM^TEXT COBOL85_SET_SORT_PARAM_TEXT_ COBOL85^RETURN^SORT^ERRORS COBOL85_RETURN_SORT_ERRORS_ For descriptions of the preceding routines, see Section 13, Libraries and Utility Routines. • How the Scratch File is Determined In this explanation, if a scratch file is specified but its value is all spaces, assume that no scratch file was specified. If COBOL_SET_SORT_PARAM_TEXT_ specifies a SCRATCH-FILE, then that file is the scratch file. If the SELECT statement associated with sd-name specifies the =_SORT_DEFAULTS DEFINE as the define-name-literal, then: ° If the =_SORT_DEFAULTS DEFINE exists and specifies a scratch file, then that file is the scratch file. ° If the =_SORT_DEFAULTS DEFINE exists but does not specify a scratch file, then a temporary file on the volume $SYSTEM is the scratch file. ° If no =_SORT_DEFAULTS DEFINE exists, then a temporary file on the volume $SYSTEM is the scratch file. ° If the SELECT statement associated with sd-name does not specify the =_SORT_DEFAULTS DEFINE as the define-name-literal, then the file that the SELECT statement specifies is the scratch file. For instructions for creating the =_SORT_DEFAULTS DEFINE, see the FastSort Manual. • How the Volume of the Temporary Swap File is Determined The operating system assigns a swap file to swap pages in and out of memory while the compiler is running. The swap file mirrors all of the data areas that the compiler uses. The ideal swap file is a fast device that is neither busy nor mirrored. To redirect the swap file, give define-name-literal the value =_SORT_DEFAULTS. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -230 Procedure Division Verbs SORT The swap file is a temporary file with a volume but no subvolume. If you specify a swap file, the file-id you specify is not used, only the volume. If you specify only the file-id, the default volume is used. In this explanation, if a swap file is specified but its value is all spaces, assume that no swap file was specified. If COBOL_SET_SORT_PARAM_TEXT_ specifies a SWAP-FILE, then the swap file is created on that file’s volume. If the SELECT statement associated with sd-name specifies the =_SORT_DEFAULTS DEFINE as the define-name-literal, then: ° If the =_SORT_DEFAULTS DEFINE exists and specifies a swap file, then the swap file is created on that file’s volume. ° If the =_SORT_DEFAULTS DEFINE exists but does not specify a swap file, then the swap file is created on the volume used for the scratch file. ° If no =_SORT_DEFAULTS DEFINE exists, then the swap file is created on the volume used for the scratch file. ° If the SELECT statement associated with sd-name does not specify the =_SORT_DEFAULTS DEFINE as the define-name-literal, then the swap file is created on the volume of the file that the SELECT statement specifies. For instructions for creating the =_SORT_DEFAULTS DEFINE, see the FastSort Manual. • Placement of SORT Statements A SORT statement cannot appear in the Declaratives Portion of the Procedure Division. It can appear anywhere in the other portion except within the range of a sort input procedure or a sort or merge output procedure. • File Descriptions File sd-name must be described by a sort-merge file description entry (sort-merge file description entry) in the File Section of the Data Division. The file can be described as having fixed-length or variable-length records. Every file record must contain all of the sort key fields. • Restrictions on Sort Keys Each key identifies a sort key data item and is subject to these restrictions: ° The data item specified by key must be described within a record associated with sd-name. When sd-name has more than one record description, a sort key item can be defined within any one of those record descriptions. ° No sort key data item can have a variable size (have a subordinate described with an OCCURS DEPENDING clause). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -231 Procedure Division Verbs ° • SORT No sort key data item can be described with an OCCURS clause or can be subordinate to an item described with an OCCURS clause. Sort Input and Sort Output Files Files specified by infile and outfile must be defined as data files; that is, none of them can be defined in a sort-merge file description entry. If the file identified by sd-name has variable-length records, the size of the records contained in the file identified by infile must not be less than the size of the smallest record described for sd-name ; likewise, the size must not be greater than the size of the largest record described for sd-name. If sd-name is described as having fixed-length records, the size of the records contained in the file described by infile must not be larger than the largest record defined for sd-name. If the file identified by outfile has variable-length records, the size of the records contained in the file identified by sd-name must not be less than the size of the smallest record described for outfile ; likewise, the size must not be greater than the size of the largest record described for outfile. If outfile is described as having fixed-length records, the size of the records contained in the file described by sd-name must not be larger than the largest record defined for outfile. If infile specifies a file whose SELECT clause does not include the OPTIONAL phrase, the file must be present at execution time. If an instance of outfile identifies an indexed or queue file, the major key must be associated with the ASCENDING phrase and the first instance of key must specify the same character positions in its record as are specified for the prime record key for that file. A COBOL program can sort to and from these types of files: ° ° ° ° Disk files Tape files Multiple-reel tape files Tape files on a multiple-file reel No more than one file name from a multiple-file reel can be in a SORT statement. • Sort Input Procedures The INPUT PROCEDURE phrase defines a sort input procedure that extends from inproc-1 to inproc-2, each of which must identify a Procedure Division section or paragraph. If THROUGH or THRU is omitted, the compiler assumes an inproc-2 that specifies the same section or paragraph as inproc-1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -232 Procedure Division Verbs • SORT Sort Output Procedures The OUTPUT PROCEDURE phrase defines a sort output procedure that extends from outproc-1 to outproc-2, each of which must identify a Procedure Division section or paragraph. If THROUGH or THRU is omitted, the compiler assumes an outproc-2 that specifies the same section or paragraph as outproc-1. • Execution Phases The execution of the SORT statement consists of three phases: • ° The input phase transfers records to the sort file sd-name, either from one or more infile files specified in a USING phrase or from a sort input procedure specified in an INPUT PROCEDURE phrase. ° The sort phase reorders these records according to the sort keys and the applicable collating sequence. ° The output phase either transfers the sorted records to a set of one or more files specified by outfile in the GIVING phrase or returns them to the sort output procedure specified in an OUTPUT PROCEDURE phrase. Input Phase of Execution ° USING phrase If the USING phrase appears, the input phase transfers all of the records in each input file infile to the sort file sd-name. When the SORT statement begins executing, each input file must be either closed but not locked, or open but not in conflict with a following open for protected input (that is, the same file connector cannot be open). For each input file, the input phase implicitly opens it in the input mode, executes implicit “READ infile NEXT AT END …” statements to retrieve the records and implicit release operations to release them to the sort file, then it implicitly closes the input file. The open and close operations are equivalent to OPEN INPUT and CLOSE statements without any optional phrases. All of these implicit functions are performed such that any associated declarative procedures are executed; however, the execution of a declarative procedure must not cause the execution of any statement that manipulates any of the input files or accesses the record area associated with any input file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -233 Procedure Division Verbs ° SORT INPUT PROCEDURE phrase If the INPUT PROCEDURE phrase appears, the input phase executes an implicit PERFORM procedure-group statement (where proceduregroup is procedure name, optionally followed by THROUGH or THRU and another procedure name). The sort input procedure thereby specified is responsible for releasing the records to be sorted by one or more executions of RELEASE statements. The sort input procedure must not open a file specified by outfile. Control automatically returns to the sort operation after completing the execution of the implicit PERFORM statement. The range of the implicit procedure must not cause the execution of a MERGE, RETURN, or SORT statement or a RELEASE statement that references any sort or merge file other than the one identified by sd-name. • Sort Phase of Execution The sort phase reorders the records within the sort file according to their sort key values. The records of sd-name are first sorted in accordance with their values for the most significant (first listed) sort key. When two or more records have equal values for the current sort key, that group of records is then sorted in accordance with the record values for the next most significant key, and so on. When two or more records contain equal values for all sort keys, their final order within the sort file depends on the DUPLICATES phrase. If DUPLICATES is specified, their order will be the order in which they were released to the sort file. If DUPLICATES is not specified, their order is arbitrary. The key s are listed from left to right within the SORT statement in order of decreasing significance, without regard to how the list of keys is divided into ASCENDING KEY or DESCENDING KEY phrases; therefore, the data item specified by the first key is the most significant sort key, and the data item specified by the last key is the least significant sort key. The ordering implied by a sort key depends upon its KEY phrase: ° When the sort key is specified in an ASCENDING KEY phrase, the sorted sequence is from the record having the lowest value in the sort key data item to the record having the highest value in the sort key data item. ° When the sort key is specified in a DESCENDING KEY phrase, the sorted sequence is from the record having the highest value in the sort key data item to the record having the lowest value in the sort key data item. ° In both cases, the determination of which value is higher is made according to the rules for comparison of operands in a relation condition. The collating sequence that applies to the comparison of nonnumeric sort key data items is the one specified by the alphabet-name in the COLLATING SEQUENCE phrase. When this phrase is not specified, the program collating sequence applies. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -234 Procedure Division Verbs • SORT Output Phase of Execution ° GIVING phrase If the GIVING phrase appears, the output phrase transfers all records in the sd-name file to each output file outfile. Each output file must be in the closed state, but not in the locked state, when the output phase begins executing. First, the output phrase implicitly opens each output file in the output mode. The output phase then executes implicit return operations to retrieve the records from the sort file and implicit WRITE statements write operations to release them to each of the output files. Finally, the output phase implicitly closes each of the output files. The open and close operations are equivalent to OPEN OUTPUT and CLOSE statements having no optional phrases. All of these implicit functions are performed such that any associated declarative procedures are executed; however, the execution of a declarative procedure must not cause the execution of any statement that manipulates any of the output files or accesses the record area associated with any output file. When more than one instance of outfile is specified, each operation is performed on each file in the order that they appear in the GIVING phrase. That is, the output files are opened in order, each retrieved record is written to each file in order, and then the files are closed in order. If an output file is a relative file, the relative key data item is set to the value 1 for the first record returned, 2 for the second, and so forth. After the SORT statement finishes executing, the content of the relative key data item indicates the last record returned to the file. If an output file has fixed-length records, each record retrieved from the sort file containing fewer character positions than the fixed size specified for the output file is extended on the right with as many space characters as needed before it is written to the output file. The first attempt to write beyond the defined boundaries of an output file causes a boundary violation condition. This in turn causes the execution of the applicable USE procedure, if one exists. If the logic of the non-CRE environment permits continued execution of the run unit, control then returns to the output phase. In this case no additional implicit write operations are executed for that file; however, the logic of the output phase closes it as described earlier. The sort operation automatically closes the sort file after the end of the output phase. Then the SORT statement terminates execution. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -235 Procedure Division Verbs ° SORT OUTPUT PROCEDURE Phrase If the OUTPUT PROCEDURE phrase appears, the output phase executes an implicit PERFORM procedure-group statement (where proceduregroup is the procedure name, optionally followed by THROUGH or THRU and another procedure name). The sort output procedure thereby specified is responsible for retrieving the sort file records by one or more executions of RETURN statements. The sort output procedure must not open the sort input file infile. Control automatically returns to the sort operation after execution passes beyond the last statement in the range of the PERFORM statement. The range of the output procedure must not cause the execution of a MERGE, RELEASE, or SORT statement or a RETURN statement that references any sort or merge file other than the one identified by sd-name. • Sort Scratch File The FastSort utility determines the default scratch file size if the file-system file named in the file-control entry does not exist. If the file does exist, SORT uses it. You can use the File Utility Program CREATE or command interpreter CREATE command to create the scratch file on disk. If the sort input file is defined to be on tape, or if the sort receives its records from an input procedure, the default number of records in the scratch file is 50K. SORT deletes the scratch file after it completes ordering the records unless you specify SAVE-SCRATCH in the routine COBOL85^SET^SORT^PARAM^VALUE or COBOL_SET_SORT_PARAM_VALUE_. Example 9-64. Typical Use of Input and Output Procedures (page 1 of 2) FILE-CONTROL. SELECT EMPLOYEE-MASTER ASSIGN TO "EMPMST" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. SELECT SORT-WORK ASSIGN TO "SORTWORK". DATA DIVISION. FD EMPLOYEE-MASTER LABEL RECORDS ARE OMITTED RECORD CONTAINS 52 CHARACTERS. 01 EMPLOYEE-DETAIL. 05 EMPLOYEE-NUMBER PIC X(05). 05 EMPLOYEE-NAME PIC X(20). 05 DEPT PIC X(03). 05 JOB-CLASS PIC X(05). 05 HOURLY-RATE PIC 9(3)V99. 05 DEDUCTIONS PIC 9(3)V99. 05 ANNUAL-SALARY PIC 9(7)V99. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -236 Procedure Division Verbs START Example 9-64. Typical Use of Input and Output Procedures (page 2 of 2) SD SORT-WORK RECORD CONTAINS 52 CHARACTERS. 01 SORT-RECORD. 05 EMPLOYEE-NUMBER PIC X(05). 05 EMPLOYEE-NAME PIC X(20). 05 DEPT PIC X(03). 05 JOB-CLASS PIC X(05). 05 HOURLY-RATE PIC 9(3)V99. 05 DEDUCTIONS PIC 9(3)V99. 05 ANNUAL-SALARY PIC 9(7)V99. ... PROCEDURE DIVISION. ... IF NO-ERROR SORT SORT-WORK ON ASCENDING KEY EMPLOYEE-NAME OF SORT-RECORD INPUT PROCEDURE IS SORTIN-PROC OUTPUT PROCEDURE IS SORTOUT-PROC ... SORTIN-PROC SECTION. READ EMPLOYEE-MASTER NEXT RECORD AT END GO TO SORTIN-EXIT END-READ IF WS-DEPT EQUAL DEPT OF EMPLOYEE-DETAIL OR WS-DEPT EQUAL SPACES RELEASE SORT-RECORD FROM EMPLOYEE-DETAIL GO TO SORTIN-PROC END-IF. SORTIN-EXIT. EXIT. SORTOUT-PROC SECTION. RETURN SORT-WORK AT END GO TO SORTOUT-EXIT END-RETURN MOVE CORRESPONDING SORT-RECORD TO LIST-RECORD WRITE LIST-RECORD GO TO SORTOUT-PROC. SORTOUT-EXIT. EXIT. SORT-END SECTION. EXIT. START START positions a file, in sequential or dynamic access mode, for subsequent read operations. START cannot reference a file that is open for HP COBOL Fast I-O. If the START statement executes successfully, it establishes the key of reference and the initial record position needed for subsequent sequential record retrievals. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -237 Procedure Division Verbs START HP COBOL includes two extensions that are of particular interest if you are writing a server program: Phrase Description GENERIC Lets you position a file at the first record in a subset of a file that consists of all records that satisfy a certain (EQUALS) key relation. After such a START, you can execute sequential READ statements (READ NEXT, for dynamic-access mode) to read all records of the subset. When, eventually, a record does not satisfy the key relation, the run-time routine simulates an at-end condition. POSITION Lets you position a file at a specific point in a set of duplicate values of an alternate key (as specified in the KEY phrase). The position-key must be a unique value: a prime or relative key or a unique alternate key. By using this feature, a context-free server can return a series of groups of records to its requester. With each group, it returns the value of the unique key last used. The requester can then send both the alternate key value for the KEY phrase and the unique value for the POSITION phrase to the server, to specify where to begin the next group. START file-name KEY phrase APPROXIMATE GENERIC TIME LIMIT wait-time INVALID imperative-stmt-1 KEY NOT INVALID imperative-stmt-2 KEY END-START VST219.vsd file-name is the file description name of the file to position. It must have an access mode of sequential or dynamic and be opened for INPUT or I-O but not for HP COBOL Fast I-O. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -238 Procedure Division Verbs START KEY phrase KEY relationship key IS position VST220.vsd must appear if the file has sequential organization or if the file has relative organization but is not described with a RELATIVE KEY clause. If KEY phrase is omitted, the file’s prime key is used. relationship GREATER THAN OR EQUAL TO > >= = LESS NOT THAN < VST221.vsd If position is present, relationship is limited to: EQUAL TO = VST223.vsd key determines, with relationship, where the file position indicator is to be set. The file position indicator is to be set such that the next record to be read from file-name contains a key value having the specified relationship to the current value of key. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -239 Procedure Division Verbs START The value of key is restricted by the presence or absence of position. If position is present, key must be either: • • A prime record key or leftmost subordinate of a prime key for an indexed or queue file An alternate key or leftmost subordinate of an alternate key for an indexed, queue, or relative file If position is absent, key can be one of: • • • The relative key for a relative file The prime record key or leftmost subordinate of the prime key for an indexed or queue file An alternate key or leftmost subordinate of an alternate key for a file of any organization A reference modifier can be applied to key, but leftmost-characterposition must be the constant 1. For reference modifier syntax, see Reference Modifier Syntax. position POSITION position-key BEFORE AFTER VST222.vsd specifies that a combination of alternate key or prime key (specified by key in the KEY phrase) and position-key (specified either by the file prime key or by a unique alternate key) is to be used to position the file. This phrase is not permitted for files having sequential organization, or files having the INSERTIONORDER attribute. BEFORE specifies that the file position indicator is set to the record before the position defined by the values of key and position-key. Note. BEFORE is available only for the NMCOBOL compiler. Note. Only use BEFORE when the file will subsequently be read in reverse. If the file is not read in reverse, reading is slightly less efficient. AFTER specifies that the file-position indicator is set to the record after the position defined by the values of key and position-key. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -240 Procedure Division Verbs START If neither BEFORE nor AFTER is present, the file-position indicator is set to the record at the position defined by the values of key and position-key. position-key is either the file prime key or a unique alternate key. If position-key is the file prime key (the prime record key of an indexed or queue file or the relative key of a relative file), then key must refer to one of: • • • • The prime key A leftmost subordinate of the prime key An alternate key A leftmost subordinate of an alternate key If position-key is a unique alternate key (a key described without the DUPLICATES clause), then key must refer to the same alternate key (or to a leftmost subordinate of that alternate key). If position-key is a leftmost subordinate of a prime or alternate key, see GENERIC. APPROXIMATE is the default positioning mode. APPROXIMATE means that reading begins at the first record that satisfies the relationship that the KEY phrase specifies. Subsequent READ statements read the records in file key order or physical order, depending on the file’s organization, until the end of the file is reached. GENERIC is an alternative positioning mode. If GENERIC is used, then relationship must be EQUAL, EQUAL TO, or =. Reading begins at the first record that satisfies the relationship and continues until the relationship is not satisfied (logical end of file). GENERIC is usually used with a partial key; that is, a subordinate item of the key defined for the file. Use of the leftmost subordinate governs the action of the GENERIC clause, but the complete alternate key is used for positioning (as explained in START Statement With the POSITION Phrase). wait-time is the time interval, in seconds, in which the operation must complete. wait-time can be a literal or the name of a data item. In either case, it must have a value described with at most seven digits preceding any decimal point position. Any fractional portion is truncated to two decimal places. If file-name was not opened with a TIME LIMITS phrase, including wait-time in the START statement causes a run-time error. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -241 Procedure Division Verbs START imperative-stmt-1 is an imperative statement to be executed when an invalid-key condition is encountered by the START operation. It is required if no USE statement is applicable for the file. If both a USE statement and an INVALID KEY phrase are present, only the INVALID KEY phrase is used. imperative-stmt-2 is an imperative statement to be executed when no invalid-key condition is detected in the START operation. END-START ends the scope of the START statement, making the START statement a delimitedscope statement. If the START statement does not end with an END-START phrase, the presence of the INVALID KEY or the NOT INVALID KEY phrase makes the START statement a conditional statement, which ends at the next period separator. Usage Considerations: • Action of the START Statement The START statement proceeds in this manner: 1. It establishes the specified key as the key of reference and searches the file for the first logical record whose value for that key satisfies the specified relation with respect to the comparison data item values. When the specified key is the prime record key or an alternate record key, the comparison data item is handled as if it were an alphanumeric data item (regardless of its actual description) and the normal nonnumeric comparison rules apply, except that the standard collating sequence for the first 128 characters is always used. Note. The program collating sequence does not apply to file key comparisons. When the size of the comparison data item in character positions is less than that of the file key, the comparison proceeds as if the record’s key value were truncated on the right so as to reduce its size to the equivalent number of characters. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -242 Procedure Division Verbs START 2. When the file does not contain a qualifying record, the invalid-key condition exists and the start operation terminates with the I-O status code “23.” When the search operation succeeds, the file position indicator is set to the value of the key of reference for the record found. The execution of the START statement does not alter the contents of the record area associated with file-name or the content of the depending item specified in the DEPENDING phrase of the RECORD clause that describes file-name. Note. Use care in specifying the starting record. When you are starting a file with APPROXIMATE positioning (which is the default), the value you use for wait-time must take into account that a START can take somewhat longer than expected. This can occur when the START leads to a nonexistent record, because the file system searches through the file looking for the next defined record before reporting the absence of the record sought. Suppose that your file contains alternate keys that can have duplicates, and one such alternate key is DEPT-NUM. If you want to start at the department whose number follows 5440, it is more efficient to use a START of the form MOVE "5441" TO DEPT-NUM. START MYFILE KEY IS NOT LESS THAN DEPT-NUM. than it is to use MOVE "5440" TO DEPT-NUM. START MYFILE KEY IS GREATER THAN DEPT-NUM. because the latter form causes the file system to sequentially read each record having the key value “5440” until it finds a record whose key exceeds 5440. The time saved depends upon the number of duplicates in the file. See the Guardian Programmer’s Guide for more information on the action of READ (which is called by the START logic). • File-Status Data Item If file-name has an associated file-status data item, execution of the START statement always assigns an appropriate I-O status code to it. The value “00” reports an unconditionally successful start operation. The value “97” reports a successful start operation that validated a position by reading a locked record. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -243 Procedure Division Verbs START The values of the I-O status data item for unsuccessful start operations are: • I-O Status Code Unsuccessful Start Operation “23” The file position indicator indicates that an optional input file is not present, the invalid-key condition exists, and the start operation terminates. “30” Either the time specified in the TIME LIMIT phrase elapsed before the start operation completed (indicated by the special register GUARDIAN-ERR having the value “40”), or the start operation failed for some non-COBOL reason. In either case, the value of the file position indicator becomes undefined. “47” The file identified by file-name is not open for INPUT or for I-O. The start operation terminates. “90” The program attempted to use the TIME LIMIT phrase when the associated OPEN statement does not specify TIME LIMITS. “91” The program attempted to use the POSITION phrase when the file has insertion-ordered alternate keys. The start operation fails. Invalid-Key Condition If the START statement contains the INVALID KEY phrase, control passes to the imperative statement in that phrase, and no USE procedure is executed. If the START statement does not contain an INVALID KEY phrase, but an applicable USE procedure exists, that procedure is executed. • Key Data Item The data item specified by key is the comparison data item for the start operation. When this data item is a file key data item, that key is the specified key for the start operation; otherwise, the file key data item of which key is a leftmost subordinate specifies the file key for the start operation. The key data item can be reference-modified. It can be a level 66 (RENAMES) item. key can also be an item whose description contains a REDEFINES clause or subordinate to an item whose description contains a REDEFINES clause. The redefining data item and, in the latter case, the data item subordinate to the redefining item must contain the leftmost character positions of the redefined data item. When the KEY phrase does not appear, the start operation behaves as if the START statement includes the phrase KEY EQUAL TO the-key, in which thekey is either the relative key data item (for files with relative organization) or the prime record key data item (for files with indexed organization). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -244 Procedure Division Verbs • START TIME LIMIT Phrase If the TIME LIMIT phrase appears, the time limit operand is evaluated and rounded, if necessary, to include at most two fractional digits. When the result is negative, the TIME LIMIT phrase does not apply, and the operation is not subject to a time limit; otherwise, the result specifies the time interval, in seconds, within which the start operation must complete. The start operation fails if an acceptable record cannot be located within the time interval specified. If the TIME LIMIT phrase is specified with a nonnegative value, and the file is not opened with time limits enabled, the program terminates with an I-O status code “90,” and a message, “File is not opened for timed I-O,” is delivered to the process’s home terminal. • Effect of Declaratives on Termination If there is no declarative procedure applicable to the file when the operation is terminated, the program terminates, and an error message is reported to the process’s home terminal. If the applicable declarative procedure is present (but no INVALID KEY phrase is present) and the time interval expires, the declarative procedure is performed. Then program execution continues with the imperative statement in the NOT INVALID KEY phrase, if one is present, or otherwise with the statement following the one terminated. • Result of Successful Start Operation A successful start operation identifies a subset of the file’s records that can be retrieved by subsequent sequential READ statements. The initial record in the subset is the one located by the search. When the APPROXIMATE phrase appears, the subset includes all records that follow the initial record according to the key of reference. When the GENERIC phrase appears, the subset includes only those records whose value for the key of reference satisfies the specified relation with respect to the comparison data-item value. During the execution of subsequent READ NEXT statements, the at-end condition occurs when the run-time routines detect the end of the subset. When neither the APPROXIMATE nor the GENERIC phrase is present, the start operation behaves as if the APPROXIMATE phrase is present. When the execution of the START statement is successful, the key of reference established for the start operation is also used for any subsequently executed READ NEXT statements for the file, until the execution of some statement explicitly establishes a different key of reference. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -245 Procedure Division Verbs START Whenever the start operation is successful, if a NOT INVALID KEY phrase is specified, control passes to the imperative statement in that phrase. If that imperative statement does not transfer control elsewhere using a GO TO statement, control then passes to the end of the START statement. • Result of Unsuccessful Start Operation When the execution of a START statement is unsuccessful for any reason, the file position indicator is set to indicate that no valid next record has been established, and the key of reference for the file is undefined. • START Statement Without the POSITION Phrase Execution of the START statement establishes the specified key as the key of reference for the file: ° ° ° ° For sequential files, an alternate key For relative files, the relative key item or an alternate key For indexed files, a prime key or alternate key For queue files, a prime key The start operation searches the file for the first record whose value for the key of reference satisfies the specified relation with respect to the comparison data item. When the specified key is the prime record key or an alternate record key, the comparison data item is handled as if it were an alphanumeric data item (regardless of its actual description) and the normal nonnumeric comparison rules (using the ASCII collating sequence) apply. When the size of the comparison data item in character positions is less than that of the file key, the comparison proceeds as if the record’s key value were truncated on the right to reduce its size to the equivalent number of characters. When the file does not contain a qualifying record, the invalid-key condition exists, and the execution of the START statement is unsuccessful. When the search succeeds, the file position indicator for the file is set to point to the record found. • START Statement With the POSITION Phrase A START statement that includes a POSITION phrase also serves to establish a key of reference and to establish a value for the file position indicator. If more than one record has the same alternate key, the POSITION phrase determines which record is read. If the program is reading according to a partial alternate key that has duplicate values in the file, but the complete alternate key values are unique, the POSITION phrase has no effect (even if the alternate key is specified with the DUPLICATES phrase). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -246 Procedure Division Verbs START Suppose a requester asks for a set of records from a member of a context-free server class: all the records that have a certain alternate key value, or partial value. If the message buffer cannot hold all such records, the server can return the first group of records plus the value of the unique key with the reply. This value is that of the prime record key, the relative key, or the entire alternate key declared as having no duplicates. Then the requester can ask for another group, supplying the value of both the partial alternate key and the unique key, and the server can resume with the last record it had sent or (by using the AFTER phrase) the record beyond that. The server can remain context-free, because the information necessary to do the positioning and to establish the key of reference and the comparison length (for partial keys) accompanies the request. ° GENERIC Positioning Mode and the POSITION Phrase The choice of APPROXIMATE or GENERIC positioning mode, coupled with the KEY clause, govern where the next READ statement starts reading and what constitutes the end of the file (or the beginning of the file, if the file is being read in reverse). A common use of GENERIC involves reading all records that have a common value in the leftmost subordinate of a given alternate key; for example, all records that have a 10-character alternate key, where the first five characters of that key have the value “A5R32.” Under the GENERIC mode, the program reads records until it encounters one that has something different in the first five characters for that alternate key, then the program receives an end-of-file condition instead of a new record value. Only if the file contains multiple records that have the same value for the complete alternate key (not just the leftmost subordinate) can the POSITION phrase be used as outlined in the general discussion earlier to process groups of records. ° BEFORE and AFTER Phrases If neither the BEFORE phrase nor the AFTER phrase is included, the execution of the START statement sets the file position indicator to point to the record uniquely identified by the two key values. If the BEFORE phrase is included, the execution of the START statement sets the file position indicator to point to the record preceding the one that the two key values uniquely identify. If the AFTER phrase is included, the execution of the START statement sets the file position indicator to point to the record following the one that the two key values uniquely identify. • INSERTIONORDER Attribute Incompatible with POSITION Phrase The POSITION phrase can be used only if the file on which the START statement is operating has the NO INSERTIONORDER attribute; that is, records with duplicate values of an alternate key are delivered in principal key order. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -247 Procedure Division Verbs • START Next READ After a START with POSITION Might Fail When you use the POSITION phrase, there is no guarantee that the record you specify actually exists. In this aspect, the start-with-position operation differs from the ordinary COBOL start operation. The positioning operation merely sets the file position indicator to the file location where the record can be found if it exists; therefore, the invalid-key condition does not occur when the record does not exist. Instead, the first subsequent sequential READ statement encounters the at-end condition (if the physical end of the file has been reached, or if the logical end of file associated with the generic positioning mode has been reached). • Determining Key Value of Last Record of an Indexed or Queue File To determine the key value of the last record of an indexed or queue file, which is especially important when using the READ REVERSED statement, move HIGHVALUES to the key and then use the START statement with the relationship LESS THAN. START LESS THAN positions the indexed file so that a READ NEXT or READ REVERSED statement accesses the last record in the file. Table 9-11. Using the POSITION and KEY Phrases Position-Key Key Length Used and Restriction Effect Relative key (ORGANIZATION RELATIVE) Alternate or alternate(1:n ) length (entire alternate) + 4 < 254 Full value of alternate AND of relative used Relative key 4 (which is the length of the relative key) Relative key used alone Prime key (ORGANIZATION INDEXED) Alternate or alternate (1:n ) length (entire alternate) + length (prime) < 254 Full value of alternate AND of prime used Prime key length (prime) Prime key used alone Alternate key (ORGANIZATION RELATIVE or INDEXED) Same alternate or alternate (1:n ) Full alternate must be unique (no DUPLICATES) < 254 Full value of alternate used alone Example 9-65. START Statement for Indexed File (page 1 of 2) SELECT RECEIVABLES-MASTER ASSIGN TO "RECMAST" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS INVOICE-NUMBER ALTERNATE RECORD KEY IS COMPANY-NAME WITH DUPLICATES. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -248 Procedure Division Verbs Example 9-65. START Statement for Indexed File (page 2 of 2) PROCEDURE DIVISION. ... OPEN I-O RECEIVABLES-MASTER ... MOVE LOW-VALUES TO COMPANY-NAME START RECEIVABLES-MASTER KEY NOT LESS THAN COMPANY-NAME INVALID KEY DISPLAY "ERROR STARTING READ FOR REPORT" GO TO REPORT-EXIT END-START. GET-NEXT-RECORD. READ RECEIVABLES-MASTER NEXT RECORD AT END PERFORM... Example 9-66 reads all records for employees whose last names start with G. Example 9-66. START Statement With GENERIC Phrase for Sequential File SELECT INPUT-FILE ASSIGN TO "INFILE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL ALTERNATE RECORD KEY IS EMP-NAME WITH DUPLICATES. ... FD INPUT-FILE LABEL RECORDS ARE OMITTED RECORD CONTAINS 95 CHARACTERS DATA RECORD IS PERSONNEL-DATA. 01 PERSONNEL-DATA. 05 DEPT-NO PIC 9(5). 05 EMPLOYEE-NO PIC 9(7). 05 EMP-NAME. 10 LAST-NAME. 15 FIRST-LETTER PIC X. 15 FILLER PIC X(14). 10 FIRST-NAME PIC X(9). ... PROCEDURE DIVISION. ... OPEN I-O INPUT-FILE ... MOVE "G" TO FIRST-LETTER START INPUT-FILE KEY = FIRST-LETTER GENERIC INVALID KEY GO TO START-ERROR-ROUTINE END-START READ INPUT-FILE AT END HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -249 START Procedure Division Verbs START Example 9-67, fragments of a server program, shows the use of a START statement with a POSITION phrase. The query the server gets through $RECEIVE includes a department number and a unique employee number. The server is to return an array containing information about all employees in the specified department. At the first call, the requester sends the chosen department number but an employee number of zero. If there are more than ten employees in a department, the server reports only the first ten it found. The requester can then send another query, but this time it includes the employee number of the last array entry of the previous reply. By using this technique, the server remains context-free, able to serve another requester. When the server executes the START statement, the key of reference used with the GENERIC phrase is still the department number, but the presence of a unique record key value of EMP-NO in the AFTER POSITION phrase says to resume reading along the DEPT-NO path after the record for the specified employee. Example 9-67. START Statement With POSITION Phrase (page 1 of 2) SELECT EMP-FILE ASSIGN TO "EMPL1093" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS EMP-NO ALTERNATE RECORD KEY IS DEPT-NO WITH DUPLICATES ALTERNATE RECORD KEY IS EMP-NAME WITH DUPLICATES FILE STATUS IS EMP-STATUS. ... DATA DIVISION. FILE SECTION. ... FD EMP-FILE. 01 EMP-DATA. 05 EMP-NO 05 EMP-NAME 05 EMP-DEPT ... PIC 9(6). PIC X(45). PIC 9(7). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -250 Procedure Division Verbs START Example 9-67. START Statement With POSITION Phrase (page 2 of 2) PROCEDURE DIVISION. ... OPEN INPUT EMP-FILE ... * Read $RECEIVE to get the query READ REC-IN ... * If this is an initial request, do a nonposition start IF DEPT-NO OF EMP-LIST-REQUEST = ZEROS START EMP-FILE KEY = DEPT-NO OF EMP-DATA GENERIC * Otherwise, resume after record last reply array ended with ELSE START EMP-FILE KEY = DEPT-NO OF EMP-DATA AFTER POSITION EMP-NO GENERIC END-IF * Zero the counter * Perform (with test after) until EOF or 10 employees found: * Read EMP-FILE NEXT record * If EOF, return array to requester with signal for EOF * else add 1 to the counter * copy info to the array * end-if In Example 9-67, suppose that department 1572 has 12 employees: 000131Smith 001552Nguyen 001744Dietrich 001745Wellhausen 001746Thomas 001991Chew 004451O'Hara 005433Logan 006112McClure 009733Kinoshita 012255Bostrup 013146Tilden Jan Tracy Pat Robin Kim Meredith Flemming Shannon Beck Lynn Stacy Tex 0001572 0001572 0001572 0001572 0001572 0001572 0001572 0001572 0001572 0001572 0001572 0001572 If the requester sends a request with an EMP-NO value of zero for department 1572, the server returns the records for the first 10 employees (131 through 9733) in response. If the requester sends EMP-NO as 9733 in the second request for department 1572, the START AFTER positions the file to resume reading after that number, so the server returns the last 2 records in the file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -251 Procedure Division Verbs STARTBACKUP STARTBACKUP Note. • • Do not use this directive in the OSS environment. Before RVU D46.00 and G06.00, software product revision T8107AAT (run-time library T8108AAR), tThe NMCOBOL compiler ignores this directive and issues a warning. STARTBACKUP defines options for handling process pairs and starting the backup process. STARTBACKUP cpu options backup-ext VST224.vsd cpu is the processor module where the backup process is to run. The cpu parameter is either an integer numeric literal or an identifier that designates an integer numeric data item. The value associated with cpu must not be less than 0 nor greater than 15 and cannot designate the same processor in which the process executing the STARTBACKUP statement is running. options is either an integer numeric literal or an identifier that designates an integer numeric data item. The value must be 0, 1, 2, or 3. Value Meaning (page 1 of 2) 0 The fault-tolerant facility is to read and process system messages, and the primary process is to terminate abnormally if a trap condition occurs. If this option is specified and the primary process is stopped (because of a command interpreter STOP command or by a third process), the backup process stops. The non-CRE environment run-time processes relevant system messages, such as CPU-DOWN, as part of this activity. The occurrence of a trap condition in the primary process causes it to fail (see the explanation of ARMTRAP in the Guardian Programmer’s Guide.) Additionally, if the backup process fails, the primary process automatically starts a new backup process when it is possible to do so. 1 This option is the same as option 0 except that if the primary process stops, the backup process takes over processing of the application. 2 This option is the same as option 1 except that if the primary process encounters a trap condition, it enters the DEBUG procedure instead of being terminated abnormally. (For an explanation of traps and the DEBUG procedure, see the Guardian Programmer’s Guide.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -252 Procedure Division Verbs STARTBACKUP Value Meaning (page 2 of 2) 3 The primary process, rather than the fault-tolerant facility, reads the $RECEIVE file and takes appropriate action for system messages. In addition, if the primary process encounters a trap condition, it enters the DEBUG procedure. When this option is in force and the backup process fails, the primary process must re-execute the STARTBACKUP statement to reestablish the backup. (This is considered an advanced option because it requires direct calls to the operating system. If you use this option, see the information on interprocess communication and checkpointing in the Guardian Programmer’s Guide.) backup-ext is ignored by the NMCOBOL compiler. For a program compiled by the COBOL85 compiler, backup-ext works only if the program runs in the Guardian environment and in the CRE. It is an integer numeric literal or an integer numeric data item. Its legal values and their meanings are: Value Meaning 0 (default) The Extended-Storage Section is not to be backed up. 1 The Extended-Storage Section is to be backed up. Note. If the primary process executes a STOP RUN statement, the backup process also stops, regardless of the specified option. Usage Considerations: • When STARTBACKUP Statement Has No Effect In the OSS environment, or in the Guardian environment when PARAM NONSTOP OFF is active, the STARTBACKUP statement has no effect. • NONSTOP Compiler Directive The STARTBACKUP statement can appear in a source program only when the compiler finds the NONSTOP directive before it finds an Identification Division header (see NLD). • Backup Process and Takeover Points When the process is qualified to execute as a process pair, successful execution of the STARTBACKUP statement establishes and initializes a backup process. The STARTBACKUP statement does not itself establish a valid takeover point; this is a function of the CHECKPOINT, OPEN, or CLOSE statement. Code a CHECKPOINT statement after each STARTBACKUP statement so that the new backup process will have all the data it needs for a possible takeover. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -253 Procedure Division Verbs • STARTBACKUP Creation and Maintenance of a Backup Process Execution of the STARTBACKUP statement assigns a value to the special register PROGRAM-STATUS, reflecting the success or failure of the creation of the backup process. PROGRAM-STATUS is a record with two fields, PROGRAM-STATUS-1 and PROGRAM-STATUS-2: 01 PROGRAM-STATUS. 02 PROGRAM-STATUS-1 02 PROGRAM-STATUS-2 PIC X. PIC XXX. Automatic backup process maintenance (for levels below 3) does not take effect until after the successful execution of a STARTBACKUP statement. For PROGRAM-STATUS values, see Table 32-1 and Table 32-2. • Unnamed Processes If the process to which the STARTBACKUP statement applies was not initiated as a named process (that is, with the NAME option of the RUN command), the STARTBACKUP statement returns a specific value in the special register PROGRAM-STATUS. In the CRE, the value is 4922; in the non-CRE environment, it is 4013. • STARTBACKUP Options For most applications, use option 0 or 1. For either of these options, a STARTBACKUP statement must execute once during the initialization phase of the program (check the outcome of the STARTBACKUP execution by examining the PROGRAM-STATUS variable). At each successive checkpoint, the fault-tolerant facility checks the state of the backup process and processor. If the backup process is inoperable, the fault-tolerant facility re-creates the backup process. If the backup’s processor is operable, the fault-tolerant facility re-creates the backup process immediately. If the backup’s processor is inoperable, the fault-tolerant facility re-creates the backup process when backup’s processor becomes operable. • What Fault-Tolerant Facility Checkpoints ° TNS The fault-tolerant facility checkpoints the lower 32 KB of user data space, all open files, and (if selected) extended storage when the STARTBACKUP statement is executed; however, your program must contain a CHECKPOINT statement to verify the creation of a backup process and to establish a valid takeover point in the program code (rather than in the run-time library). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -254 Procedure Division Verbs ° STARTBACKUP TNS/R The fault-tolerant facility checkpoints the global-data portion of the globalsheap segment, the main stack, and all open files when the STARTBACKUP statement is executed; however, your program must contain a CHECKPOINT statement to verify the creation of a backup process and to establish a valid takeover point in the program code (rather than in the run-time library). • Whether to Back Up the Extended-Storage Section (COBOL85 Compiler Only) If the value of backup-ext is 0, the STARTBACKUP statement does not back up the Extended-Storage Section. If a backup process takes over, the contents of any data item in the Extended-Storage Section is undefined unless that data item is explicitly referenced in a CHECKPOINT statement. If the contents are undefined, VALUE clauses have no effect and the extended stack functions incorrectly. (The extended stack is important only if the HP COBOL program calls a non-COBOL routine that uses it. FORTRAN routines, for example, can use the extended stack.) If the value of backup-ext is 1, the STARTBACKUP statement backs up the Extended-Storage Section. If a backup process takes over, the contents of any data item in the Extended Storage Section are determined: If the data item … Then its contents are … has a VALUE clause as specified by the VALUE clause has no VALUE clause and the BLANK directive applies spaces and the NOBLANK directive applies undefined HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -255 Procedure Division Verbs STOP STOP STOP halts the execution of a run unit, either permanently or only to display a message. Note. The 1985 COBOL standard classifies the latter use as obsolete, so you are advised not to use it. STOP RUN «message» VST225.vsd RUN halts the execution of a run unit and transfers control to the operating system, closing any open files. message Note. The 1985 COBOL standard classifies message as obsolete, so you are advised not to use it. Instead, use a DISPLAY statement followed by an ACCEPT statement. is a nonnumeric literal string. Execution stops temporarily and message is sent to the home terminal. When any response or carriage return is entered, execution resumes. The routine COBOL85^COMPLETION or COBOL_COMPLETION_ provides the application program a means of reporting a completion code to the operating environment and terminating execution. This statement suspends processing until the home terminal sends a carriage return: STOP "Press Return to show you are out there.". This sequence of statements is equivalent: DISPLAY "Press Return to show you are out there.". ACCEPT USER-REPLY. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -256 Procedure Division Verbs STRING STRING STRING combines some or all the characters from two or more data items into one other data item. STRING DELIMITED part-1 delimiter BY INTO SIZE result POINTER pointer WITH OVERFLOW imperative-stmt-1 ON NOT OVERFLOW imperative-stmt-2 ON END-STRING VST226.vsd part-1 is an alphanumeric literal or identifier of a DISPLAY data item. The concatenation of their values is stored in the data item named by result. If a data item is numeric, it must be described as an integer without P in its PICTURE characterstring. When a figurative constant is used, it represents a one-character nonnumeric literal. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -257 Procedure Division Verbs STRING delimiter is an alphanumeric literal or the identifier of a DISPLAY data item. It specifies the portion of part-1 that is moved. It also specifies that all characters up to but not including the value of delimiter are moved. If the literal is a figurative constant, it represents the equivalent one-character nonnumeric literal. If the data item is numeric, it must be described as an integer whose PICTURE character-string does not include P. SIZE specifies that all the characters in part-1 are moved. result is an identifier for an alphanumeric data item where the characters chosen from the part-1 s are stored. If result is an elementary item, its PICTURE character-string must not contain editing symbols or a JUSTIFIED clause. Reference modification is not permitted. Storing begins at the position identified by the initial value of pointer. When pointer is not used, the leftmost position is the beginning place. An internal index keeps track of the next available position in result. result cannot reference a special register. pointer is the identifier of an integer data item whose PICTURE character-string does not include P. The initial value of pointer (which you must set) is the position in result to which the first character of data will be moved. The value of the first position is 1. At the conclusion of STRING, pointer ’s value is its initial value plus the total number of characters moved. pointer cannot reference a special register. imperative-stmt-1 is an imperative statement to be executed when the internal index points past the end of result. OVERFLOW also occurs if the initial value of pointer is less than 1 or greater than the length of result. If no OVERFLOW statement is given, control passes to the next statement after STRING. imperative-stmt-2 is an imperative statement to be executed when the internal index does not point past the end of result. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -258 Procedure Division Verbs STRING END-STRING ends the scope of the STRING statement, causing the STRING to be a delimitedscope statement. If the STRING statement does not end with an END-STRING phrase, the presence of the OVERFLOW or the NOT OVERFLOW phrase causes the STRING statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • Operand Identification For each identifier, the process of operand identification occurs only once, at the beginning of the execution of the STRING statement. • Initialization The execution of the STRING statement begins in this manner: 1. The data item specified by result is established as the receiving item. 2. When the POINTER phrase appears, the data item specified by pointer is established as the pointer variable. If the initial value of pointer is less than 1 or greater than the size of the receiving item, then the overflow condition exists immediately and no string operation occurs; otherwise, the initial value of pointer determines the relative character position within result at which the first sending value is assigned. The leftmost character position is designated to be 1. When the POINTER phrase does not appear, the string operation presumes an initial relative character position of 1. • String Operation Cycle The string operation transfers data from each part-1, in the same order as they are specified in the STRING statement. The steps involved in the transfer of a sending value are: ° Determining the transfer string If the applicable DELIMITED phrase specifies delimiter, then the value of the current part-1 is examined character by character from left to right until either of these is found: the end of the value, or a sequence of contiguous characters that matches the value of delimiter. If a match is found, the transfer string consists of the portion of the sending value preceding the character that matches the first character of the delimiter; otherwise, the transfer string consists of the entire sending value. If the applicable DELIMITED phrase specifies SIZE, then no delimiter exists and the transfer string always consists of the entire sending value. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -259 Procedure Division Verbs ° STRING Copying the transfer string to the receiving item Assignment of the transfer string to the receiving item (result ) proceeds on a character by character basis. Beginning with the leftmost character, each character of the transfer string is moved into the receiving item character position designated by the pointer value, which is incremented by 1 after each character is moved. ° Overflowing the size of the receiving item Overflow occurs if not all of the characters of a transfer string can be moved to the receiving item. The overflow condition exists when the pointer value exceeds the size of the receiving item during assignment of any transfer string or after completing assignment of any transfer string except the last one. After assignment of the last transfer string, the pointer value can be one character past the end of the receiving item, and overflow does not occur unless there are leftover characters in the transfer string. If the overflow condition exists, the string operation terminates immediately. Any remaining characters in the current transfer string are ignored; any sending values not yet processed are ignored. • State of the Rest of result After termination of the string operation, only the portion of the data item specified by result that was referenced as described earlier is changed. That is, any portions preceding the first character assigned or following the last character assigned retain their previous value. When the execution of a STRING statement specifying a POINTER phrase terminates, either normally or due to an overflow condition, the contents of the data item specified by pointer contains a value equal to its initial value plus the total number of characters transferred into the data item specified by result. • Overflow Condition When an overflow condition exists, execution of the STRING statement terminates at that point. If the OVERFLOW phrase is specified, the imperative statement in that phrase is executed; otherwise control passes directly to the end of the STRING statement. • Overlapping Operands If any part of the storage area referenced by result or of that referenced by pointer is the same as the storage area referenced by any other identifier appearing in the STRING statement, the execution of the STRING statement will produce unpredictable results. • National Data Items and National Literals If any of the data items part-1, delimiter, and result is a national data item or national literal, then all of them must be national items. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -260 Procedure Division Verbs STRING In Example 9-68, STRING builds a single data item from several data items. Also see the examples in UNSTRING. Example 9-68. STRING Statement Input: WORKING-STORAGE SECTION. 77 PART-1 PIC X(10). 77 PART-2 PIC X(26). 77 PART-3 PIC X(10). 77 RESULT-1 PIC X(80) VALUE SPACES. 77 COUNT-1 PIC 99. PROCEDURE DIVISION. A10-START. DISPLAY "ENTER PART-1 (MAX 10 NUMERIC CHARACTERS)" ACCEPT PART-1 INSPECT PART-1 REPLACING ALL " " BY "0" IF PART-1 NOT NUMERIC DISPLAY "NOT NUMERIC" GO TO A10-START END-IF DISPLAY "ENTER PART-2 (MAX 26 CHARACTERS)" ACCEPT PART-2 DISPLAY "ENTER PART-3 (MAX 10 CHARACTERS)" ACCEPT PART-3 MOVE 1 TO COUNT-1 STRING PART-1 DELIMITED BY ZERO SPACE DELIMITED BY SIZE PART-2 DELIMITED BY SPACE SPACE DELIMITED BY SIZE PART-3 DELIMITED BY SPACE INTO RESULT-1 WITH POINTER COUNT-1 END-STRING DISPLAY "PART-1 = " PART-1 DISPLAY "PART-2 = " PART-2 DISPLAY "PART-3 = " PART-3 DISPLAY "COUNT-1 = " COUNT-1 DISPLAY "RESULT-1 AFTER STRING = " RESULT-1 STOP RUN. Output: >RUN rununit ENTER PART-1 (MAX 10 NUMERIC CHARACTERS) ?1234 67 ENTER PART-2 (MAX 26 CHARACTERS) ?MINNIE MOUSE ENTER PART-3 (MAX 10 CHARACTERS) AAAAA PART-1 = 1234067000 PART-2 = MINNIE MOUSE PART-3 = AAAAA COUNT-1 = 18 RESULT-1 AFTER STRING = 1234 MINNIE AAAAA HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -261 Procedure Division Verbs SUBTRACT SUBTRACT SUBTRACT computes differences between numeric values. Form Description SUBTRACT FROM Subtracts one or more values from the values of one or more identifiers and stores the results in the identifiers; for example, SUBTRACT A B C FROM D E stores D - (A + B + C) in D and stores E - (A + B + C) in E SUBTRACT GIVING Subtracts one or more values from the values of one or more identifiers and stores the results in another set of identifiers; for example, SUBTRACT A B C FROM D GIVING E stores D - (A + B + C) in E SUBTRACT CORRESPONDING Subtracts elements of one data structure from corresponding elements of another data structure HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -262 Procedure Division Verbs SUBTRACT FROM SUBTRACT FROM SUBTRACT FROM subtracts one or more values from the values of one or more identifiers and stores the results in the identifiers. SUBTRACT subtrahend FROM minuend-result ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-SUBTRACT VST227.vsd subtrahend is the identifier of a numeric elementary data item or a numeric literal. minuend-result is the identifier of a numeric elementary data item. ROUNDED specifies that the result is to be rounded before being stored. imperative-stmt-1 is an imperative statement to be executed when a size error is detected in the subtraction or in storing the result. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -263 Procedure Division Verbs SUBTRACT FROM imperative-stmt-2 is an imperative statement to be executed when no size error is detected in the subtraction or in storing the result. END-SUBTRACT ends the scope of the SUBTRACT statement, causing the SUBTRACT to be a delimited-scope statement. If the SUBTRACT statement does not end with an END-SUBTRACT phrase, the presence of the SIZE ERROR or the NOT SIZE ERROR phrase causes the SUBTRACT statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • Mathematics The values of all the subtrahend s are totaled. That sum is subtracted from each result, and the result of each such subtraction is then stored after rounding, if ROUNDED was specified as the new value of the minuend-result. For example, the statement SUBTRACT A B C FROM D E means store D - (A + B + C) in D and store E - (A + B + C) in E. • Specifying the Same Data Item for More Than One Result If more than one minuend-result specifies the same data item, the final value of that item reflects multiple subtractions of the intermediate sum. For example, SUBTRACT A FROM B B means the final value of B is (B - A) - A. • Operand Identification For each minuend-result, the process of operand identification occurs just prior to the “subtract and store” operation; therefore, in SUBTRACT A, B, C FROM I, I, X(I) the subscript is not evaluated until the sum of A, B, and C is subtracted twice from I. • Arithmetic Operations See Arithmetic Operations for information on data conversion and alignment, intermediate results, multiple results (and subscript evaluation), and incompatible data. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -264 Procedure Division Verbs • SUBTRACT GIVING Precision For any series of items involved in a subtraction, when their decimal points are aligned, the composite picture must involve not more than 18 digits of representation, or a size error condition can result (which can cause a run unit to terminate abnormally with an arithmetic overflow condition). For information on precision of subtraction, see ADD and SUBTRACT Statements. • ROUNDED, SIZE ERROR, and NOT SIZE ERROR Phrases See ROUNDED Phrase and SIZE ERROR Phrase for information on these phrases. SUBTRACT GIVING SUBTRACT GIVING subtracts one or more values from a value of one identifier and stores the results in another set of identifiers. SUBTRACT GIVING FROM subtrahend minuend result ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-SUBTRACT VST228.vsd subtrahend is a numeric literal or the identifier of a numeric elementary data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -265 Procedure Division Verbs SUBTRACT GIVING minuend is a numeric literal or the identifier of an elementary numeric data item. result is the identifier of a numeric or numeric edited elementary data item. ROUNDED specifies that the result is to be rounded before being stored. imperative-stmt-1 is an imperative statement to be executed when a size error is detected in the subtraction or in storing the result. imperative-stmt-2 is an imperative statement to be executed when no size error is detected in the subtraction or in storing the result. END-SUBTRACT ends the scope of the SUBTRACT statement, causing the SUBTRACT to be a delimited-scope statement. If the SUBTRACT statement does not end with an END-SUBTRACT phrase, the presence of the SIZE ERROR or the NOT SIZE ERROR phrase causes the SUBTRACT statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • Mathematics The values of all the subtrahend s are totaled. That sum is subtracted from minuend, and the result of this subtraction is then stored after rounding, if ROUNDED was specified as the new value of each result. For example, the statement SUBTRACT A B C FROM D GIVING E means store D - (A + B + C) in E. • Changing Operand Values The SUBTRACT GIVING statement does not change the value of any subtrahend or the minuend, unless one is also named as a result. • Arithmetic Operations See Arithmetic Operations for information on data conversion and alignment, intermediate results, multiple results (and subscript evaluation), and incompatible data. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -266 Procedure Division Verbs • SUBTRACT CORRESPONDING Precision For any series of items involved in a subtraction, when their decimal points are aligned, the composite picture must involve not more than 18 digits of representation, or a size error condition can result (which can cause a run unit to terminate abnormally with an arithmetic overflow condition). For information on precision of subtraction, see ADD and SUBTRACT Statements. • ROUNDED and SIZE ERROR Phrases See ROUNDED Phrase and SIZE ERROR Phrase for information on these phrases. SUBTRACT CORRESPONDING SUBTRACT CORRESPONDING subtracts elements of one data structure from corresponding elements of another data structure. Caution. SUBTRACT CORRESPONDING is not recommended, because minor changes to one data structure can change the correspondence between its elements and those of the other data structure, and this is difficult to detect. SUBTRACT CORRESPONDING group-1 CORR FROM group-2 ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-SUBTRACT VST229.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -267 Procedure Division Verbs SUBTRACT CORRESPONDING group-1 is the identifier of a data structure in which some or all of the elementary items are numeric. group-2 is the identifier of a data structure that has one or more elementary numeric items. For each elementary numeric item in group-2 that corresponds to such an item in group-1, the difference between the values of the two items replaces the value of group-2. The composite picture of any pair of items aligned by decimal points must not involve more than 18 digits of representation. ROUNDED specifies that each difference be rounded before being stored. imperative-stmt-1 is an imperative statement for the compiler to execute when it detects a size error in any subtraction or in storing the result. imperative-stmt-2 is an imperative statement to be executed when no size error is detected in any subtraction or in storing the result. END-SUBTRACT ends the scope of the SUBTRACT statement, causing the SUBTRACT to be a delimited-scope statement. If the SUBTRACT statement does not end with an END-SUBTRACT phrase, the presence of the SIZE ERROR or the NOT SIZE ERROR phrase causes the SUBTRACT statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • Definition of Correspondence Groups of data correspond if they have the same names and qualifier names, beyond the group-names in the SUBTRACT statement, and if they meet restraints explained under CORRESPONDING Phrase. • Problem Inherent in Using SUBTRACT CORRESPONDING The SUBTRACT CORRESPONDING statement can save keystrokes, but can cause problems when someone adds a name to a data structure: the name might be included in an unintended subtraction operation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -268 Procedure Division Verbs UNLOCKFILE UNLOCKFILE UNLOCKFILE restores access to any records in a file previously locked with LOCKFILE or to those records locked with a LOCK phrase on previous READ statements. Other processes can then read or write records, depending on the file’s open mode. UNLOCKFILE file-name VST230.vsd file-name is the file description name of a file. Usage Considerations: • Action of the UNLOCKFILE Statement A successful UNLOCKFILE statement releases the exclusive file-access guarantee obtained by a previously executed LOCKFILE statement specifying the same file-name. It also releases all exclusive record-access guarantees for that file obtained by previously executed READ LOCK statements. If the file is not locked, or no records of the file are locked, no error occurs. • File-Status Data Item If file-name has an associated file-status data item, execution of the UNLOCKFILE statement always assigns an appropriate I-O status code as its value. The status code “00” reports a successful UNLOCKFILE operation. Whenever the statement terminates with an I-O status code greater than or equal to “30,” execution of the UNLOCKRECORD failed. The possible I-O status codes for an unsuccessful UNLOCKFILE operation are: • I-O Status Code Unsuccessful UNLOCKFILE Operation “30” The unlock operation failed due to non-COBOL causes. The file might or might not now be unlocked. “42” The file was not open. Disk Files Only The UNLOCKFILE statement has no effect unless the file specified is a disk file. • Key of Reference, File Position Indicator, and Record Area The key of reference, the file position indicator, and the record area are not affected by the execution of an UNLOCKFILE statement, whether it succeeded or not. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -269 Procedure Division Verbs UNLOCKRECORD In Example 9-69, the UNLOCKFILE statement precedes a CLOSE statement to unlock the file before the process closes it. Example 9-69. UNLOCKFILE Statement FD IN-MASTER-FILE ... PROCEDURE DIVISION. ... IF UPDATE-FILE OPEN INPUT IN-MASTER-FILE LOCKFILE IN-MASTER-FILE PERFORM UP-DATE-MASTER UNTIL DONE UNLOCKFILE IN-MASTER-FILE CLOSE IN-MASTER-FILE ELSE ... UP-DATE-MASTER. * Perform the update, during which time no other process * can read any record in that file. ... UNLOCKRECORD UNLOCKRECORD restores access by other processes to the last record read (the record selected by the file position indicator). The record was locked by execution of a READ LOCK statement. UNLOCKRECORD file-name VST231.vsd file-name is the file description name of a file. Usage Considerations: • Action of the UNLOCKRECORD Statement The UNLOCKRECORD statement affects only the record designated by the file position indicator for the specified file; therefore, in normal use, it follows a successful read operation or a successful read-then-rewrite sequence. A successful UNLOCKRECORD statement releases the exclusive record-access guarantee obtained by a previously executed READ LOCK statement. If the record is not locked, no error occurs. • UNLOCKRECORD Statement Immediately After START Statement If an UNLOCKRECORD statement is the first input-output statement after a START statement, a run-time error occurs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -270 Procedure Division Verbs • UNSTRING File-Status Data Item If file-name has an associated file-status data item, execution of the UNLOCKRECORD statement always assigns an appropriate I-O status code as its value. The status “00” reports a successful UNLOCKRECORD operation. Whenever the statement terminates with an I-O status code greater than or equal to “30,” execution of the UNLOCKRECORD failed. The possible I-O status codes for an unsuccessful UNLOCKRECORD operation are: • I-O Status Code Unsuccessful UNLOCKFILE Operation “30” The unlock operation failed due to non-COBOL causes. The record might or might not now be unlocked. “42” The file was not open. Disk Files Only The UNLOCKRECORD statement has no effect unless the file specified is a disk file. • Key of Reference, File Position Indicator, and Record Area The key of reference, the file position indicator, and the record area are not affected by the execution of an UNLOCKRECORD statement, whether it succeeded or not. UNSTRING UNSTRING partitions a data item (the source) into strings of consecutive characters and stores those strings into other data items (the results). You can determine the partitioning in two ways: • • Use the size of the result data items. Use the presence of specific character sequences in the source (like spaces in a person’s name or commas and decimal points in an edited number). When the statement executes, it stores these into data items of your choice: • • • • Each part For each part, the delimiter that ended that part (optional) and the number of characters stored (optional) A count of the parts stored (optional) A character-count pointer to specify where in the item the unstring operation terminates (optional) HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -271 Procedure Division Verbs UNSTRING UNSTRING source DELIMITED delim-1 BY OR ALL delim-2 ALL INTO result-list POINTER pointer WITH TALLYING tally IN OVERFLOW imperative-stmt-1 ON NOT OVERFLOW imperative-stmt-2 ON END-UNSTRING VST232.vsd source is the identifier of an alphanumeric data item containing a sequence of characters that the unstring operation is to separate into one or more sequences of characters and store them in one or more result items. source can be qualified or subscripted, but cannot include reference modification. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -272 Procedure Division Verbs UNSTRING ALL causes the unstring operation to handle all consecutive occurrences of the value of delim-1 as if they were only one occurrence of delim-1. Without ALL, the unstring operation handles only the first occurrence of the value of delim-1 as the delimiter. delim-1 is the identifier of an alphanumeric data item or an alphanumeric literal. If it is a figurative constant, it must represent a single character. The delimiter delim-1 marks the end of a portion of the value of source. The value that the unstring operation stores into a result item does not include the value of delim-1. ALL causes the unstring operation to handle all consecutive occurrences of the value of delim-2 as if they were only one occurrence of delim-2. Without ALL, the unstring operation handles only the first occurrence of the value of delim-2 as the delimiter. delim-2 is the identifier of an alphanumeric data item or an alphanumeric literal. If it is a figurative constant, it must represent a single character. The delimiter delim-2 marks the end of a portion of the value of source. The value that the unstring operation stores into a result item does not include the value of delim-2. result-list result DELIMITER delimstore IN COUNT count IN VST233.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -273 Procedure Division Verbs UNSTRING result specifies the identifier of an alphanumeric, alphabetic, or numeric DISPLAY elementary data item into which the unstring operation copies characters from source. If result identifies a numeric data item, the PICTURE clause that describes it cannot contain any P s. result cannot reference a special register. An UNSTRING statement can have at most 127 result fields. delimstore is the identifier of an alphanumeric data item. You can only use the DELIMITER phrase when you also use the DELIMITED phrase. The unstring operation copies the character or characters of source that matched the delimiter specified in the DELIMITED phrase to delimstore. delimstore cannot reference a special register. count is the identifier of an integer data item. You can only use the COUNT phrase when you also use the DELIMITED phrase. The unstring operation stores in count the number of characters it moved to result. If it did not move any characters, the unstring operation does not alter the value of count, so you must initialize count to a known value if you want to use it to determine whether the UNSTRING statement moved any characters to result. When the character-string from source is longer than result, the unstring operation truncates it to fit into result, and stores into count the length source had before it was truncated. pointer is the identifier of an integer data item. When you omit this phrase, the unstring operation begins at the first character of the source data item. When you include this phrase, the integer value in pointer specifies the position in the source data item where the unstring operation begins. When the unstring operation completes, the integer value in pointer specifies the position just beyond the last character processed by the unstring operation (delimiter or portion copied to a result data item). pointer must reference a data item that is capable of containing a numeric value equal to one plus the size of the item referenced by source. pointer cannot reference a special register. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -274 Procedure Division Verbs UNSTRING tally is the identifier of an integer data item to which the unstring operation adds the number of result data items it stored. The UNSTRING statement does not initialize tally but adds to its current value. If you want tally to begin at a given number, set it before the UNSTRING statement executes. tally cannot reference a special register. imperative-stmt-1 is an imperative statement to be executed when overflow occurs; that is, when these conditions exist: • • The initial value of pointer is less than 1 or greater than the length of source. All data-receiving areas have been acted upon, and source still contains unexamined characters. If you do not specify an OVERFLOW clause and an overflow occurs, control passes to the next statement after UNSTRING. imperative-stmt-2 is an imperative statement to be executed when overflow does not occur. END-UNSTRING ends the scope of the UNSTRING statement, causing the UNSTRING to be a delimited-scope statement. If you omit the END-UNSTRING phrase, the presence of the OVERFLOW or the NOT OVERFLOW phrase makes the UNSTRING statement a conditional statement, which ends at the next period separator. Usage Considerations: • Purpose In general terms, the UNSTRING statement partitions the value of the sending area (referenced by source ) into a sequence of strings of consecutive characters and stores them in the receiving areas (referenced by a list of one or more instances of result). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -275 Procedure Division Verbs • UNSTRING Execution of the UNSTRING Statement The execution of the UNSTRING statement consists of these three phases: 1. Initialization phase In the initialization phase, the UNSTRING statement performs these initialization operations before beginning to cycle through the list of INTO phrases: • • • • • • • It establishes the source item as the sending area. Even if the item has a variable size (is defined with the OCCURS DEPENDING clause), the initial size is used as the sending area size for the duration of statement execution. If the UNSTRING statement includes the POINTER phrase, the initialization establishes the pointer item as the pointer variable. The initial value of this item determines the relative character position within the sending area at which the unstring operation begins. The first character position is 1. This enables you to start the unstring operation at some character other than the first character in the source item, and to retain a record of where the unstring operation terminated. (A later UNSTRING statement could then begin its operation at the point where another one left off.) If the initial value of the pointer item is less than one or greater than the size of the source item, then the overflow condition exists immediately and no unstring operation occurs. If the UNSTRING statement does not include the POINTER phrase, the unstring operation begins at the first character position in the sending area. If the UNSTRING statement includes a TALLYING phrase, the initialization establishes tally as the tallying variable. Initialization establishes the first result item as the current receiving area. 2. UNSTRING cycle phase In the UNSTRING cycle phase, the unstring operation consists of one or more cycles. Each cycle examines characters in the “sending area” one by one. The sending area is the portion of the source item beginning at the current character position and ending at the last character of the source item. Each cycle assigns an appropriate string of characters to the current result. The identification of the item to be copied depends on the presence or absence of the DELIMITED phrase, and on when the unstring operation reaches the end of the source item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -276 Procedure Division Verbs UNSTRING If the statement includes the DELIMITED phrase, the examination proceeds left to right until it encounters either a delimiter string or the end of the sending area. A delimiter string is a contiguous set of characters, beginning with the character under examination, whose value exactly matches the value of any of the constants or data items specified in the DELIMITED phrase. If your program has these data items: 05 U PIC X(32) VALUE "The UNSTRING statement is handy." * ....'....'....'....'....'....'.. * 5 10 15 20 25 30 01 WORD-LIST. 03 WORD-1 PIC X(8). 03 WORD-2 PIC X(10). 03 WORD-3 PIC X(7). 03 WORD-4 PIC X(3). 03 WORD-5 PIC X(8). 03 WORD-6 PIC X(9). And if you execute UNSTRING U DELIMITED BY SPACE INTO WORD-1 WORD-2 WORD-3 WORD-4 WORD-5 WORD-6 the first item to be copied is “The” and the second is “UNSTRING” and so on. If you specify two or more delimiters, the unstring operation compares their values with the sending area in the same order as they appear in the phrase. If a match occurs, the corresponding set of characters in the sending area forms the delimiter string; any delimiters not yet tested are ignored. If no delimiter value matches the sending area at the current position, the unstring operation repeats the delimiter search beginning with the next character of the sending area. No character in the sending area can be considered a part of more than one delimiter. If you execute UNSTRING U DELIMITED BY SPACE OR "I" INTO WORD-1 WORD-2 WORD-3 WORD-4 WORD-5 WORD-6 the first item to be copied is “The,” the second item is “UNSTR,” the third is “NG,” and so on. Two special cases are consecutive delimiters and multicharacter delimiters. If ALL was not specified and the unstring operation encounters two consecutive delimiters, it interprets the sending item as zero if result is numeric. If result is not numeric, the unstring operation interprets the sending item as spaces. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -277 Procedure Division Verbs UNSTRING Each instance of delim-1 or delim-2 represents one delimiter. When a delimiter contains two or more characters, all of the characters must be present in contiguous positions in the source item, and in the order given, to be recognized as a delimiter. If you omit the DELIMITED phrase, the examination proceeds left to right until the number of characters examined equals the size of the current receiving area. If you execute UNSTRING U INTO WORD-1 WORD-2 WORD-3 WORD-4 WORD-5 WORD-6 the first item to be copied is “The UNST,” the second item is “RING state,” and so on. If the result item is numeric and its operational sign occupies a separate character position, the number of characters the unstring operation examines (when you omit the DELIMITED phrase) is one less than the size of the item. If the unstring operation reaches the end of the source item before it detects a matching delimiter (for the DELIMITED phrase), or before it fills all the receiving items, the examination terminates with the last character examined. If you execute UNSTRING U DELIMITED BY SPACE INTO WORD-1 WORD-2 WORD-3 WORD-4 WORD-5 WORD-6 The fifth item to be copied is “handy.” There is no sixth item to be copied. The unstring operation handles the set of characters thus examined (excluding the delimiter string, if any) as an elementary alphanumeric data item and copies it to the current receiving area in accordance with the rules for the MOVE statement. When the set contains no characters (that is, if a delimiter string begins at the very first character examined in this cycle), the unstring operation moves a null value to the current receiving area. If the current receiving area is described as numeric or numeric-edited, the value 0 is moved; otherwise the value spaces is moved. If you include a DELIMITER phrase in the INTO phrase for this cycle, the unstring operation handles the set of characters in the delimiter string as an elementary alphanumeric data item and copies it to delimstore in accordance with the rules for the MOVE statement. If the delimiting condition is the end of the sending area (that is, there is no delimiter string), then the unstring operation fills the delimiter data item with spaces. If the delimiter is described as a figurative constant with the ALL qualifier, only one occurrence of the unqualified figurative constant is moved. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -278 Procedure Division Verbs UNSTRING If you execute UNSTRING U DELIMITED BY SPACE OR "." INTO WORD-1 DELIMITER IN DEL-1 ... WORD-5 DELIMITER IN DEL-5 you get "The " in WORD-1, " " in DEL-1, and so on down to "handy " in WORD-5 and "." in DEL-5. If you include the DELIMITER phrase in the INTO phrase for this cycle, the unstring operation advances the current character position in the sending area to the first character following the delimiter string located in this cycle. If the specification of the matched delimiter includes the keyword ALL and the portion of the sending area following the delimiter string contains one or more repetitions of that set of characters, then the unstring operation advances the current character position past all repetitions; therefore the unstring operation considers two or more contiguous occurrences of the matched delimiter string as equivalent to a single occurrence in determining the beginning character for the next examination cycle. If you include a COUNT phrase in the INTO phrase for this cycle, the unstring operation assigns the numeric value equal to the number of characters examined (excluding the delimiter string, if any) to count in accordance with the rules for an elementary move operation. If you execute UNSTRING U DELIMITED BY SPACE OR "." INTO WORD-1 COUNT IN COUNT-1 ... WORD-5 COUNT IN COUNT-5 you get "The " in WORD-1, but 3 in COUNT-1, and you get "stateme" HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -279 Procedure Division Verbs UNSTRING in WORD-3 but 9 in COUNT-3. If you include the POINTER phrase, the unstring operation increments the value of the pointer item by one for each character examined as a part of this cycle. This includes each character in the value copied to the receiving area, each character in the delimiter string (if any), and each character in any contiguous repetitions of the delimiter string; therefore the resulting value of the pointer variable reflects the relative character position within the sending area at which the next cycle begins. If the sending area still contains any unexamined characters and the current receiving area is not the last one, then the unstring operation establishes the next result item as the new current receiving area and begins another unstring cycle. If the sending area still contains any unexamined characters but the current receiving area is the last one, then the overflow condition exists and the unstring operation terminates. If the sending area does not contain any unexamined characters, then the unstring operation terminates normally and any remaining receiving areas are ignored. When the execution of an UNSTRING statement with a TALLYING phrase terminates, either normally or due to an overflow condition, tally contains a value equal to its initial value plus the number of data receiving items that were assigned new values. If an overflow condition arises, execution of the UNSTRING statement terminates at that point. 3. OVERFLOW/NO OVERFLOW processing phase (optional) If you include an OVERFLOW phrase, the imperative statement in that phrase is executed; otherwise control is transferred to the next executable statement in the normal way. • Operand Identification For each identifier, the process of operand identification occurs only once, at the beginning of the execution of the UNSTRING statement. • Operand Overlap Neither the storage area referenced by pointer nor that referenced by tally can be the same as or overlap the storage area referenced by any other identifier appearing in the UNSTRING statement. The storage area referenced by result, delimstore, and count must not overlap or be the same as any of the storage areas referenced by source, delim-1, or delim-2. Violation of these rules produces unpredictable results. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -280 Procedure Division Verbs • UNSTRING National Data Items and National Literals If any of the data items delim-1, delim-2, result, or delimstore is a national data item or national literal, then all of them must be national items. In Example 9-70, UNSTRING breaks a data item into a collection of data items. UNSTRING uses the MOVE statement rules in transferring values into shorter data items. Example 9-70. UNSTRING Statement Input: DATA DIVISION. WORKING-STORAGE SECTION. 77 SOURCE-STRING PIC X(18) VALUE "12345 MICKEY ABCDE". 77 UNPART-1 PIC X(3). 77 UNPART-2 PIC X(3). 77 UNPART-3 PIC X(3). PROCEDURE DIVISION. A10-START. UNSTRING SOURCE-STRING DELIMITED BY " " INTO UNPART-1 UNPART-2 UNPART-3 DISPLAY "UNPART-1 = " UNPART-1 DISPLAY "UNPART-2 = " UNPART-2 DISPLAY "UNPART-3 = " UNPART-3 STOP RUN. Output: >RUN RUNUNIT UNPART-1 = 123 UNPART-2 = MIC UNPART-3 = ABC In Example 9-71, UNSTRING separates a name, entered as it would be typed on a mailing envelope, into a last name and a remainder. You could use this mechanism to build records that can be sorted on last and first name. Example 9-71. UNSTRING Statement (page 1 of 2) WORKING-STORAGE SECTION. 01 NAMES-TABLE. 03 NAMES PIC X(50) OCCURS 10 TIMES INDEXED BY NAME-INDEX, FIRST-NAME-INDEX. 01 WORK-GROUP. 03 NAME-COUNT 03 WHOLE-NAME 03 LAST-NAME 03 REST-OF-NAME 03 POINTER-1 PIC PIC PIC PIC PIC 99 COMP. X(50). X(50). X(50). 99 COMP. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -281 Procedure Division Verbs UNSTRING Example 9-71. UNSTRING Statement (page 2 of 2) PROCEDURE DIVISION. WHATS-NEXT. * PROMPT FOR A NAME AS IT WOULD BE TYPED ON AN ENVELOPE DISPLAY "Enter a name (or a space to terminate):". ACCEPT WHOLE-NAME IF WHOLE-NAME = SPACES STOP RUN END-IF * INITIALIZE MOVE SPACES TO NAMES-TABLE, REST-OF-NAME MOVE 0 TO NAME-COUNT * * GET EACH CONSECUTIVE BLOCK OF CHARACTERS ENDING IN ONE OR MORE SPACES INTO A NAME (I) AND COUNT THE BLOCKS. UNSTRING WHOLE-NAME DELIMITED BY ALL " " INTO NAMES (1) NAMES (2) NAMES (3) NAMES (4) NAMES (5) NAMES (6) NAMES (7) NAMES (8) NAMES (9) NAMES (10) TALLYING IN NAME-COUNT * LAST ONE COPIED IS LAST-NAME MOVE NAMES (NAME-COUNT) TO LAST-NAME IGNORE LEADING SPACES IF NAMES (1) = SPACES SET FIRST-NAME-INDEX TO 2 ELSE SET FIRST-NAME-INDEX TO 1 END-IF * * CONCATENATE OTHER NAMES INTO REST-OF-NAME MOVE 1 TO POINTER-1 PERFORM COLLECT-REST VARYING NAME-INDEX FROM FIRST-NAME-INDEX BY 1 UNTIL NAME-INDEX = NAME-COUNT DISPLAY "Last name is......" LAST-NAME DISPLAY "Rest of name is..." REST-OF-NAME DISPLAY " " GO TO WHATS-NEXT. COLLECT-REST. STRING NAMES (NAME-INDEX) DELIMITED BY SPACE INTO REST-OF-NAME POINTER POINTER-1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -282 Procedure Division Verbs USE This is a sample run of Example 9-71 with a typical name and a single-word name: Enter a name (or a space to terminate): ?Abraham Moyer Last name is......Moyer Rest of name is...Abraham Enter a name (or a space to terminate): ?Johann Philip Geissinger Last name is......Geissinger Rest of name is...JohannPhilip Enter a name (or a space to terminate): ?Copernicus Last name is......Copernicus Rest of name is... The portions of the rest of the name are not separated by spaces. If you want spaces, make the STRING statement look like this: STRING NAMES (NAME-INDEX) DELIMITED BY SPACE " " DELIMITED BY SIZE INTO REST-OF-NAME POINTER POINTER-1. USE USE defines debugging or exception-handling procedures beyond the standard techniques of the file system. USE also defines the conditions under which the procedure paragraphs following it are executed. Form Description USE DEBUGGING Obsolete. The NMCOBOL compiler ignores it. USE AFTER EXCEPTION Transfers control to an error-handling procedure when an error occurs USE can appear only as the first statement of a section in the Declaratives Portion of the Procedure Division, and it must be the only statement in the sentence containing it. Any other statements that the section contains must be organized into sentences belonging to paragraphs of the section. Empty debugging declarative sections serve no purpose. Each section containing a USE statement is a declarative procedure. A declarative procedure, together with any associated utility sections, forms a logically discrete area. (The other logically discrete area of a program is the remainder of the Procedure Division.) Control statements (ALTER, GO TO, and PERFORM) specified in one logically discrete area are, with a few exceptions, not permitted to refer to procedure-names defined within another logically discrete area. For the detailed restrictions and permissions, see ALTER, GO TO, and PERFORM. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -283 Procedure Division Verbs USE DEBUGGING USE DEBUGGING Note. The 1985 COBOL standard classifies USE DEBUGGING as obsolete, so you are advised not to use it, even in TNS HP COBOL programs. The NMCOBOL compiler does not recognize it. USE DEBUGGING traces procedure-names as a program executes. Immediately before a procedure is executed, the code for the section containing USE DEBUGGING is executed. If you collect and report procedure-names from a special register as the program executes, you can monitor the actual sequence of operations and detect logic errors. The symbolic debuggers are significantly more versatile than the USE DEBUGGING statement. For information on the symbolic debuggers, see Run-Time Debuggers. USE DEBUGGING FOR ON ALL REFERENCES OF . name filename procedure ALL PROCEDURES VST234.vsd ALL REFERENCES OF name is checked for syntactic correctness but diagnosed as unsupported. If the selected debugger is symbolic, use the BREAK command to observe all uses of and changes to a data item. file-name is checked for syntactic correctness but diagnosed as unsupported. If the selected debugger is symbolic, use the BREAK command to observe all uses of a file. procedure is one or more procedure-names to trace during program execution. procedure cannot be named in multiple USE statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -284 Procedure Division Verbs USE DEBUGGING ALL PROCEDURES traces every procedure-name and appears only once when used. It precludes the use of any USE procedure statements. Usage Considerations: • Declarative Procedures Procedure-names defined within a debugging declarative procedure (and procedure-names defined within utility sections associated with that declarative procedure) can be referred to by PERFORM statements located within other debugging declarative procedures (and utility sections associated with them). • Placement of Debugging Declarative Procedures Within the Declaratives Portion of the Procedure Division, all debugging declarative procedures must precede all nondebugging declarative procedures. • DEBUG-ITEM Special Register A special register, DEBUG-ITEM, is defined for you and available within a USE DEBUGGING statement. You can choose to display or print the contents of this register as is or move the fields to your own message description. The point here is that procedure-names are not automatically displayed as a trace is done. You are responsible for external evidence of a trace. Example 9-72. DEBUG-ITEM Special Register 01 DEBUG-ITEM. 05 DEBUG-LINE 05 FILLER 05 DEBUG-NAME 05 FILLER 05 DEBUG-SUB-1 PIC PIC PIC PIC PIC 05 05 FILLER DEBUG-SUB-2 PIC PIC 05 05 FILLER DEBUG-SUB-3 PIC PIC 05 05 FILLER DEBUG-CONTENTS PIC PIC X(6). X VALUE SPACE. X(30). X VALUE SPACE. S9999 SIGN IS LEADING SEPARATE CHARACTER. X VALUE SPACE. S9999 SIGN IS LEADING SEPARATE CHARACTER. X VALUE SPACE. S9999 SIGN IS LEADING SEPARATE CHARACTER. X VALUE SPACE. X(n). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -285 Procedure Division Verbs USE DEBUGGING Before the USE statement is executed, DEBUG-ITEM is filled with spaces. Immediately before the debugging section obtains control, DEBUG-ITEM is updated: DEBUG-LINE Contains the source line number where the procedure-name was called DEBUG-NAME Contains the first 30 characters of the procedure-name If it is a paragraph-name, any section-name qualifier is reported in DEBUG-ITEM. DEBUG-CONTENTS Contains a nonnumeric string varying in size and value. Depending on the situation when it is updated, it contains one of: • START PROGRAM When the first procedure in the program calls USE • A procedure-name When an ALTER statement specifies that procedure as a destination • Spaces When a GO TO statement specifies the procedure • PERFORM LOOP When the procedure is in a PERFORM loop • SORT INPUT When the procedure is in a SORT input procedure • SORT OUTPUT When the procedure is in a SORT output procedure • USE PROCEDURE When the procedure is in a USE procedure section • FALL THROUGH When the procedure is executed as a result of falling through from the previous procedure HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -286 Procedure Division Verbs USE DEBUGGING In Example 9-73, the debugging procedure displays the contents of the special register DEBUG-ITEM. Example 9-73. USE DEBUGGING Statement ... ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP WITH DEBUGGING MODE. ... PROCEDURE DIVISION. DECLARATIVES. TRACE-PROGRAM SECTION. USE FOR DEBUGGING ON ALL PROCEDURES. DISPLAY-DEBUG-ITEM. DISPLAY DEBUG-ITEM. END DECLARATIVES. BEGIN-PROCESSING. ... The COBOL process executes the debugging statements if the PARAM DEBUG is on (see PARAM Command). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -287 Procedure Division Verbs USE AFTER EXCEPTION USE AFTER EXCEPTION USE AFTER EXCEPTION intercepts control when an input-output exception occurs. The input-output system executes USE AFTER EXCEPTION procedures after it completes the standard input-output error routine. It also executes USE AFTER EXCEPTION procedures when invalid-key or at-end conditions arise and no INVALID KEY or AT END phrases apply to the file. After the USE procedure executes, it returns control to the calling routine, unless the I-O status code is “4x ” or “90,” in which case the process terminates. USE AFTER GLOBAL EXCEPTION STANDARD PROCEDURE ERROR file-name ON . INPUT OUTPUT I-O EXTEND VST235.vsd GLOBAL Note. If you are using the NMCOBOL compiler, do not use GLOBAL in the Declaratives Portion. applies the declarative exception procedure to the program in which the USE statement appears and to any programs nested within that program, unless such a nested program has its own declarative exception procedure for that particular exception. EXCEPTION ERROR introduce the exception procedure and specify that the procedure is to be performed after the COBOL run-time input-output error routine, or when an invalidkey or at-end condition arises and no INVALID KEY or AT END phrase is present in the statement then executing. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -288 Procedure Division Verbs USE AFTER EXCEPTION file-name is a file description name that is to use this USE statement when an exception occurs. A given file-name can occur in only one USE statement in a given program. Sort-merge file description names are not permitted. INPUT specifies that all files opened in INPUT mode that are not specified explicitly in another USE statement are to use this USE statement. OUTPUT specifies that all files opened in OUTPUT mode that are not specified explicitly in another USE statement are to use this USE statement. I-O specifies that all files opened in I-O mode that are not specified explicitly in another USE statement are to use this USE statement. EXTEND specifies that all files opened in EXTEND mode that are not specified explicitly in another USE statement are to use this USE statement. Usage Considerations: • • Restrictions ° Control statements (ALTER, GO TO, and PERFORM) specified in one logically discrete area are, with a few exceptions, not permitted to refer to procedurenames defined within another logically discrete area. For detailed restrictions and permissions, see ALTER, GO TO, and PERFORM. ° Procedure names defined within a nondebugging declarative procedure (and procedure-names defined within utility sections associated with that declarative procedure) can be referred to by PERFORM statements located anywhere in the Procedure Division. ° A declarative exception procedure in which the GLOBAL phrase is specified must not execute an EXIT PROGRAM statement. ° Declarative exception procedures apply only to data files, not to sort-merge files. Implicit and Explicit File Reference A USE statement that mentions a file by name is said to make an explicit reference to the corresponding file. A USE statement that mentions an open mode (INPUT, I-O, OUTPUT, or EXTEND) makes reference to a file implicitly, according to the mode in which the program opened (or attempted to open) the file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -289 Procedure Division Verbs USE AFTER EXCEPTION It is usually best to write USE statements that explicitly reference individual files, because this gives you better control over the handling of exceptions. The declarative called by implicit reference has no simple way to determine the identity of the file that generated an exception. The management of this generic sort of exception handling can be difficult, particularly when program maintenance might introduce additional files, or in nested programs when a GLOBAL declarative is active. • Precedence Rules for Nested Programs When a program contains other programs, these precedence rules apply. When the run-time routines detect an I-O exception, they apply these rules (in the order indicated) to select and perform only the first declarative procedure that qualifies. 1. If the program in which the exception-causing statement occurred contains an appropriate declarative, use it. 2. If no declarative in that program is appropriate, check the next containing program (the next one outward in the nesting). If the containing program contains an appropriate declarative in which the GLOBAL phrase is specified, use it. 3. Repeat Item 2 until the outermost program has been checked. If no qualifying declarative procedure has been found, none is executed. An outer program can contain a GLOBAL declarative procedure to handle each file, but a nested program can contain an overriding GLOBAL or local declarative procedure that governs the handling of exceptions for certain files within the nested program or any programs it contains. • File Status and GUARDIAN-ERR Special Register For information on file status and the special register GUARDIAN-ERR, see I-O Status Code. A USE AFTER EXCEPTION procedure can base its activity on the values of these data items. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -290 Procedure Division Verbs USE AFTER EXCEPTION In Example 9-74, two files use the same error routine and another file uses a separate error routine. Example 9-74. USE AFTER EXCEPTION Statement ... PROCEDURE DIVISION. DECLARATIVES. MASTER-FILES SECTION. USE AFTER EXCEPTION PROCEDURE ON MASTER-1 MASTER-2. MASTER-ERROR-ROUTINE. IF FILE-STATUS.... ... DETAIL-FILE SECTION. USE AFTER EXCEPTION PROCEDURE ON DETAIL-IN. DETAIL-ERROR-ROUTINE. ... END DECLARATIVES. MAIN-SECTION SECTION. BEGIN-PROGRAM. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -291 Procedure Division Verbs WRITE WRITE WRITE delivers a record to its associated file. Forms: • • • WRITE for Sequential Files WRITE for Line Sequential Files WRITE for Relative, Indexed, and Queue Files WRITE for Sequential Files WRITE record-name FROM ADVANCING clause NOT from-name end-of-page clause not-end-of-page clause invalid-key-phrase NOT not-invalid-key-phrase END-WRITE VST236.vsd record-name is a logical record described in the File Section of the Data Division. The recordname can be qualified by the name of the file with which the record is associated. The data written is the current contents of record-name. from-name is the identifier of a data area whose contents are to be moved to the record specified by record-name before the WRITE occurs. from-name must specify a data area other than that specified by record-name. It also cannot specify an index data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -292 Procedure Division Verbs WRITE for Sequential Files ADVANCING clause BEFORE AFTER no-of-lines ADVANCING LINE LINES mnemonic-name PAGE VST237.vsd advances the file (skips lines) before or after the record is written to it. The default ADVANCING clause is AFTER ADVANCING 1. The ADVANCING clause can be used only with files assigned to processes or printers. BEFORE specifies that the record is to be printed before any lines are skipped. AFTER specifies that the record is to be printed after any lines are skipped. no-of-lines is a numeric integer literal, or the identifier of a numeric integer data item, whose value is greater than or equal to zero and represents the number of lines to advance before or after the write operation. Note. When no-of-lines has the value -1, HP COBOL advances to the top of a page; however, setting no-of-lines to -1 is not recommended, because it could interfere with later extensions to COBOL that would allow backspacing one line. To go to the top of a page, use BEFORE PAGE or AFTER PAGE. mnemonic-name specifies a channel position on a carriage-control tape that directs the printer to skip lines (advancing to a particular channel is usually faster than printing lines of spaces). mnemonic-name is defined in a SPECIAL-NAMES paragraph for a printer (or a process simulating a printer) with the CHANNEL option. mnemonic-name is not permitted for a file described with a LINAGE clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -293 Procedure Division Verbs WRITE for Sequential Files PAGE advances the printer to the top of the page before or after the write operation. PAGE and end-of-page clause cannot appear in the same WRITE statement. end-of-page clause END-OF-PAGE AT imperative-statement EOP VST238.vsd executes imperative-statement when the write operation encounters the end-of-page condition. The file description must include a LINAGE clause. not-end-of-page clause END-OF-PAGE AT imperative-statement EOP VST238.vsd executes imperative-statement when the write operation does not encounter the end-of-page condition. The file description must include a LINAGE clause. imperative-statement is to be executed when the end-of-page condition is satisfied when LINAGECOUNTER is either greater than the defined page length or is at a line in the footing area. In both cases, the line is written before imperativestatement is executed. If an attempt is made to write beyond the allowable area on a page, whether at or after the end-of-page condition, the page is automatically advanced (this is called the page overflow condition). invalid-key-phrase INVALID imperative-statement KEY VST239.vsd executes imperative-statement when the write operation encounters the invalid-key condition. The file description cannot include a LINAGE clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -294 Procedure Division Verbs WRITE for Sequential Files imperative-statement is an imperative statement to be executed when an invalid-key condition arises because alternate keys are defined for the sequential file, and the write operation would create a duplicate key when the file definition did not specify that duplicates are allowed. If no INVALID KEY phrase is present, a USE procedure must be present for the file or files to be opened in OUTPUT mode. not-invalid-key-phrase INVALID imperative-statement KEY VST239.vsd executes imperative-statement when the write operation does not encounter the invalid-key condition. The file description cannot include a LINAGE clause. imperative-statement is an imperative statement to be executed when an invalid-key condition does not arise. END-WRITE ends the scope of the WRITE statement, causing the WRITE to be a delimitedscope statement. If the WRITE statement does not end with an END-WRITE phrase, the presence of the AT END-OF-PAGE, the NOT AT END-OF-PAGE, the INVALID KEY, or the NOT INVALID KEY phrase causes the WRITE statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • Action of the WRITE Statement The write operation releases a logical record to the run-time routines for inclusion in the file. For a file of sequential organization, the order of the records in the file therefore corresponds to the order in which they are released. In general, the logical record consists of the value of the data item specified by record-name ; however, when the file has fixed-length records, and the recordname item contains fewer than the defined number of character positions, the logical record is extended with arbitrary character values. • Printer or Spooler Files Release of a logical record does not necessarily imply immediate transmission to the file. The record can be held in an internal buffer. In the non-CRE environment, the actual transmission of a logical record to the file or spooler buffer can be deferred until some time after completion of the WRITE statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -295 Procedure Division Verbs WRITE for Sequential Files In the CRE, the logical record is always transmitted to the file or spooler buffer immediately. • Opening File Positions Printer at Top of First Page When you open a file, the printer is positioned at the top of the first page, as if BEFORE ADVANCING PAGE had been executed. If you use default advancing (AFTER ADVANCING 1), you get a blank line at the top of the first page. (You usually use BEFORE 1 before the first write operation.) • Files That Are Not Printers or Spooler Files If a file is not a printer or spooler file, each logical record is written to the file immediately, any ADVANCING clause is ignored, and no control information (for advancing or forms control) or extra blank lines are written to the file. • Writing to EDIT Files An HP COBOL program can write at most 239 characters to an EDIT file (a file with file code 101). The action of the WRITE statement depends on the existence of the file and on the form of OPEN used. ° Existing EDIT file, OPEN EXTEND Each write operation appends a line to the file. The line numbers of the new lines begin at a value one greater than the last line number in the file, and are incremented by one. ° Existing EDIT file, OPEN OUTPUT Existing records are deleted from the file. Each write operation appends a line to the file. Line numbers begin at one and are incremented by one. ° File does not exist, OPEN OUTPUT or EXTEND For the write operation to create the file, the run-time environment must contain an ASSIGN command that specifies CODE 101. Each write operation appends a line to the file. Line numbers begin at one and are incremented by one. To make the file an EDIT file before writing it, use the COBOL_ASSIGN_ routine with file-code 101. ° Program was compiled with the NONSTOP directive If a program was compiled with the NONSTOP directive, it can open an EDIT file for input, but not for either form of output. • File-Status Data Item If the file has an associated file-status data item, execution of the WRITE statement always assigns an appropriate I-O status code. The value “00” reports a successful write operation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -296 Procedure Division Verbs WRITE for Sequential Files The I-O status codes that result from an unsuccessful write operation are: • I-O Status Code Unsuccessful Write Operation “22” An alternate record key value of the logical record equals that of a record that already exists in the file and duplicate values are not allowed for that key (all access modes). “30” The write operation failed due to non-COBOL causes. The specified record might or might not have been written. “34” A boundary violation exception exists when execution of a WRITE statement would require exceeding the record storage capacity of the file. The logical record is not released. “44” When the file is described with the RECORD VARYING clause, the logical record size must be neither greater than the maximum nor less than the minimum number of character positions specified in that clause. This requirement is not met, and the logical record is not released. “48” Either the file has sequential organization and is not open in I-O, OUTPUT, or EXTEND mode; or the open mode is I-O, and the file device is not a terminal, process, or $RECEIVE. “90” The WRITE statement contains an ADVANCING phrase, and the value of no-of-lines is a negative number other than -1. Invalid-Key Condition When the sequential WRITE statement is used to write to an indexed file, or to write to a file with alternate keys, the invalid-key condition arises when the I-O status code is “21” or “22.” • Reel-Swap Sequence for Multiple-Reel Tape Files If execution of a WRITE statement for a multiple-reel tape file exhausts the capacity of the current reel, the run-time routine automatically performs a reelswap sequence. You can use the COBOL_SPECIAL_OPEN_ routine to notify the program. • Page Headers and Trailers If you want a page trailer, describe the footing area with a FOOTING value less than or equal to the LINES value in the LINAGE clause. Then use an END-OFPAGE phrase to write a page trailer; eject the page, if necessary; and write the next page header. If you want only a page header, omit the FOOTING phrase from the LINAGE clause. Multiple end-of-page conditions can occur during the production of one logical page if several successive WRITE statements cause printing or spacing within that logical page’s footing area. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -297 Procedure Division Verbs • WRITE for Sequential Files Page Overflow An automatic page overflow condition exists whenever the execution of a write statement cannot be fully accommodated within the current page body of a printer file described with a LINAGE clause. This situation arises when the execution of the WRITE statement would cause the LINAGE-COUNTER to assume a value greater than the number of lines in the current page body. In this case, the process prints the record on the logical page before or after advancing the device to the first line following the top margin of the next logical page. If the END-OF-PAGE phrase appears in the WRITE statement, then its imperative statement is executed after both the print and advancing operations are completed. When execution of a WRITE statement causes both the end-of-page and the page overflow conditions to occur, only the actions for the page overflow condition occur. • Buffered Cache Buffered cache, enabled by the RESERVE clause of the FILE-CONTROL paragraph, speeds the writing of disk files. This technique buffers records up in cache rather than writing them immediately to disk. Do not use buffered cache in applications that require each record to be actually written to disk before execution of the next statement in the program. See FILE-CONTROL Paragraph. • Variable-Length Records An Enscribe structured file can have variable-length records. See READ for Sequential or Dynamic Access. When you write to a file that is defined as having variable-length records, the length of the record written depends on whether the file is declared with RECORD CONTAINS rec-1 TO rec-2 CHARACTERS or RECORD IS VARYING IN SIZE FROM rec-1 TO rec-2 CHARACTERS DEPENDING ON rec-size form of the RECORD CONTAINS clause. In the former case, the length of the record specified in the WRITE statement is the number of characters written to the file system file. In the latter case, the length of the record written is the value present in the recsize data item specified in the DEPENDING clause at the time the WRITE statement is executed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -298 Procedure Division Verbs WRITE for Sequential Files Example 9-75. ADVANCING Phrase ENVIRONMENT DIVISION. ... INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT MASTER-RANDOM-FILE ASSIGN TO "$MARKT.PLATZ.RPT" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL FILE STATUS IS M-R-STATUS. ... DATA DIVISION. FILE SECTION. ... FD MKT-REPORT LABEL RECORDS ARE OMITTED RECORD CONTAINS 132 CHARACTERS LINAGE IS 60 LINES WITH FOOTING AT FOOTLINE LINES AT TOP TOPLINES LINES AT BOTTOM BOTTOMLINES. 01 PRINT-LINE-OUT PIC X(132). ... WORKING-STORAGE SECTION. 01 LINAGE-STUFF. 03 FOOTLINE PIC 99 VALUE 45. 03 TOPLINES PIC 99 VALUE 0. 03 BOTTOMLINES PIC 99 VALUE 6. ... PROCEDURE DIVISION. ... WRITE-DETAIL. WRITE PRINT-LINE-OUT FROM DETAIL-LINE AT EOP PERFORM ADD 1 TO PAGE-COUNTER MOVE PAGE-COUNTER TO PAGE-NUMBER * The next WRITE statement advances to the third * line after the one just written, leaving two lines * of spaces and printing on the third line. WRITE PRINT-LINE-OUT FROM PAGE-NUMBER-LINE AFTER ADVANCING 3 LINES * The next WRITE statement advances to the top of * the next page (issues a forms-control code to skip * to channel 1.) WRITE PRINT-LINE-OUT FROM DETAIL-HEADER AFTER ADVANCING PAGE MOVE SPACES TO PRINT-LINE-OUT WRITE PRINT-LINE-OUT END-PERFORM END-WRITE ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -299 Procedure Division Verbs WRITE for Line Sequential Files WRITE for Line Sequential Files WRITE record-name FROM from-name END-WRITE VST631.vsd record-name is a logical record described in the File Section of the Data Division. The recordname can be qualified by the name of the file with which the record is associated. The data written is the current contents of record-name. from-name is the identifier of a data area whose contents are to be moved to the record specified by record-name before the WRITE occurs. from-name must specify a data area other than that specified by record-name. It also cannot specify an index data item. END-WRITE ends the scope of the WRITE statement, causing the WRITE to be a delimitedscope statement. If the WRITE statement does not end with an END-WRITE phrase, the presence of the AT END-OF-PAGE, the NOT AT END-OF-PAGE, the INVALID KEY, or the NOT INVALID KEY phrase causes the WRITE statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • See these usage considerations in WRITE for Sequential Files: ° ° ° ° Action of the WRITE Statement File-Status Data Item Reel-Swap Sequence for Multiple-Reel Tape Files Buffered Cache HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -300 Procedure Division Verbs WRITE for Relative, Indexed, and Queue Files WRITE for Relative, Indexed, and Queue Files WRITE record-name FROM from-name invalid-key NOT not-invalid-key END-WRITE VST240.vsd record-name is a logical record described in the File Section of the Data Division. The recordname can be qualified by the name of the file with which the record is associated. from-name is the identifier of a data area whose contents are to be moved to the record specified by record-name before the WRITE occurs. from-name must specify a data area other than that specified by record-name. It also cannot specify an index data item. invalid-key INVALID imperative-statement KEY VST239.vsd executes imperative-statement when an invalid-key condition arises. This phrase is required if no USE statement is applicable for the file. not-invalid-key INVALID imperative-statement KEY VST239.vsd executes imperative-statement when no invalid-key condition arises. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -301 Procedure Division Verbs WRITE for Relative, Indexed, and Queue Files END-WRITE ends the scope of the WRITE statement, causing the WRITE to be a delimitedscope statement. If the WRITE statement does not end with an END-WRITE phrase, the presence of the INVALID KEY or the NOT INVALID KEY phrase causes the WRITE statement to be a conditional statement, which ends at the next period separator. Usage Considerations: • Action of the WRITE Statement The write operation releases a logical record to the run-time routines for inclusion in the file. For a file of relative or indexed organization, the order of the records in the file is determined by the relative record number or the prime record key, respectively. In general, the logical record consists of the value of the data item specified by record-name. Records in a relative, indexed, or queue file can be any length from zero up to the maximum length specified when the file was created. Release of a logical record does not necessarily imply immediate transmission to the file. For example, the actual transmission of a logical record to the file can be deferred until some time after completion of the WRITE statement. • File-Status Data Item If the file has an associated file-status data item, execution of the WRITE statement always assigns an appropriate I-O status code. The value “00” reports a successful write operation. The I-O status codes that result from an unsuccessful write operation are: I-O Status Code Unsuccessful Write Operation (page 1 of 2) “21” The file is defined to have indexed organization and sequential access mode, and the prime record key value of the logical record is less than or equal to the prime record key value of the most recently released record. “22” One of: • • • “24” The relative record number to be associated with the logical record equals that of a record that already exists in the file (random access or dynamic access only). The prime record key value of the logical record equals that of a record that already exists in the file (random access or dynamic access only). An alternate record key value of the logical record equals that of a record that already exists in the file and duplicate values are not allowed for that key all access modes. A boundary violation exception exists when execution of a WRITE statement would require exceeding the record storage capacity of the file. The logical record is not released. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -302 Procedure Division Verbs • WRITE for Relative, Indexed, and Queue Files I-O Status Code Unsuccessful Write Operation (page 2 of 2) “30” The write operation failed due to non-COBOL causes. The specified record might or might not have been written. “44” When the file is described with the RECORD VARYING clause, the logical record size must be neither greater than the maximum nor less than the minimum number of character positions specified in that clause. This requirement is not met, and the logical record is not released. “48” Either the file has sequential organization, and is not open in I-O, OUTPUT, or EXTEND mode; or the open mode is I-O, and the file device is not a terminal, process, or $RECEIVE. Variable-Length Records An Enscribe structured file can have variable-length records. See READ for Sequential or Dynamic Access. When you write to a file that is defined as having variable-length records, the length of the record written depends on whether the file is declared with RECORD CONTAINS rec-1 TO rec-2 CHARACTERS or RECORD IS VARYING IN SIZE FROM rec-1 TO rec-2 CHARACTERS DEPENDING ON rec-size form of the RECORD CONTAINS clause. In the former case, the length of the record specified in the WRITE statement is the number of characters written to the file system file. In the latter case, the length of the record written is the value present in the recsize data item specified in the DEPENDING clause at the time the WRITE statement is executed. • Sequential Access For files of relative organization, records are released in relative number order, beginning at 1. When the file has an associated relative key data item, that item is set to the current record number at each successful release. For files of indexed organization, the program is responsible for setting the prime record key data item to a desired value prior to the execution of a WRITE statement for that record. In the case of sequential access, the records must be released in ascending order of prime record key value. HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -303 Procedure Division Verbs • WRITE for Relative, Indexed, and Queue Files Relative and Dynamic Access For files of relative organization, the relative key data item must be set to the desired record number before the WRITE occurs. This can be done in either of two ways: ° ° Set the key item to the relative record number. Set the key item to -1 to have the record written at the end of the file or to -2 to have the record written in any available file position. When the second method is used, the relative key data item must be defined as a signed integer numeric item; at the completion of the write operation, the relative key data item is set to the file position number used. For files of indexed organization, the program is responsible for setting the prime record key data item to a desired value prior to the execution of a WRITE statement for that record. • Invalid-Key Conditions This condition occurs for relative files when any of these conditions is true: ° The RELATIVE KEY item defines an existing record or the alternate key is duplicated without DUPLICATES option (I-O status code “22”). ° The file is physically full or the relative key data item points outside the file’s boundary (I-O status code “24”). ° The value intended for the RELATIVE KEY item does not fit into the RELATIVE KEY item. This condition occurs for indexed or queue files when any one of these is true: ° ° Keys are not in ascending order in sequential access (I-O status code “21”). ° The file is physically full, or the key specifies a point outside the file’s boundary (I-O status code “24”). The prime key is duplicated, or the alternate key is duplicated without DUPLICATES option (I-O status code “22”). HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -304 Procedure Division Verbs WRITE for Relative, Indexed, and Queue Files Example 9-76. INVALID KEY Phrase ENVIRONMENT DIVISION. ... INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT MASTER-REL-FILE ASSIGN TO "$MARKT.PLATZ.DT" ORGANIZATION IS RELATIVE ACCESS MODE IS RANDOM RELATIVE KEY IS VKF-NR FILE STATUS IS M-R-STATUS. ... DATA DIVISION. FILE SECTION. ... FD MASTER-REL-FILE LABEL RECORDS ARE OMITTED RECORD CONTAINS 180 TO 250 CHARACTERS. 01 DOMESTIC-SALE PIC X(180). 01 FOREIGN-SALE PIC X(250). ... WORKING-STORAGE SECTION. 01 VKF-NR PICTURE 97. 01 J-W-D. 03 NATION PIC X(15). 03 SUBDIVISION PIC X(15). 03 CITY PIC X(15). ... PROCEDURE DIVISION. ... AUSLAND. ... ADD 1 TO VKF-NR WRITE FOREIGN-SALE FROM J-W-D INVALID KEY PERFORM RECOVER-M-R-BAD-KEY END-WRITE ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -305 Procedure Division Verbs WRITE for Relative, Indexed, and Queue Files HP COBOL Manual for TNS and TNS/R Programs —522555-006 9 -306 10 Source Text Manipulation Source manipulation comprises the COPY statement, COPY libraries, and the REPLACE statement. You can use the COPY and REPLACE statements in any division of the source program. The COPY statement summons source text from a COPY library and delivers merged text to the compiler. Its optional REPLACING phrase replaces every occurrence of a specified portion of library text with a specified portion of new text when it copies library text into a source program. You can specify more than one such replacement pair in a REPLACING phrase. With or without the REPLACING phrase, the COPY statement does not change the COPY library or the source file. The COPY statement appears in the listing unless a NOSHOWCOPY, NOLIST, or SUPPRESS directive is active. The library text appears in the listing unless a NOLIST or SUPPRESS directive is active. In the Guardian environment, a COPY library is a file in the EDIT format. It contains one or more sections of zero or more text lines, each preceded by a SECTION directive line and succeeded by either another SECTION directive line or the end of the file. In the OSS environment, a COPY library is an ASCII text file. The REPLACE statement replaces source program text. It is useful for establishing names for constants and abbreviations for words and phrases and for overcoming the introduction of new reserved words into the language. Topics: • • • • COPY Statement REPLACING Phrase COPY Libraries REPLACE Statement HP COBOL Manual for TNS and TNS/R Programs —522555-006 10- 1 Source Text Manipulation COPY Statement COPY Statement COPY summons source text from a file set up as a COPY library. In many systems, one section of code or data is common to several programs. Such a section can be written once, kept in a COPY library, and inserted into each program at compile time by COPY statements. In HP COBOL, the COPY statement is a mechanism for summoning text that is managed by the Data Definition Language (DDL) compiler. (Another such mechanism is the SOURCE directive.) COPY . text-name OF library-name IN REPLACING phrase VST244.vsd COPY is a reserved word that cannot be split across source program lines. text-name is the name of a section in a COPY library file. It is a COBOL word (1 to 30 letters, digits, and hyphens but not all digits) that appears in a SECTION directive in the file. library-name system-file-name define-name-literal VST245.vsd is the name of the COPY library file that contains the text to be copied. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10- 2 Source Text Manipulation COPY Statement If library-name is not specified, a default library file is selected: • In the Guardian environment: 1. If a COPY library is named in the COBOL85 command (see Starting a Compilation), then that file is the default library file. 2. If the condition in Item 1 is not true and the file COPYLIB exists on the current volume and subvolume, then that COPYLIB file is the default library file. 3. If the conditions in Item 1 and Item 2 are not true and a DEFINE of class SEARCH named =_SOURCE_SEARCH exists, then the default library file is the first file named COPYLIB in the search list defined by =_SOURCE_SEARCH. (See =_SOURCE_SEARCH.) 4. If none of the preceding conditions are true, the COPY statement is in error. • In the OSS environment, the -Wcopylib flag specifies the default COPY library. If library-name is specified, these definitions apply: system-file-name is the name of an EDIT file (code 101), OSS ASCII text file (code 180), or PC file. If system-file-name is a PC file name or does not begin with a dollar sign ($), backward slash (\), or number sign (#), then it must be enclosed in quotation marks unless it forms a COBOL word. For more information about operating system file names, see the Guardian Procedure Calls Reference Manual. define-name-literal is a nonnumeric literal that represents the name of a DEFINE of class MAP that is associated with an EDIT file. Quotation marks must enclose definename-literal. For more information on DEFINE names, see DEFINEs. If the file-system file name identified by define-name-literal is qualified (the subvolume and any other qualifiers are specified), then that specific file is the COPY library. If the file-system file name identified is not qualified, the file selected as the COPY library depends on the presence or absence of a DEFINE of class SEARCH named =_SOURCE_SEARCH. If =_SOURCE_SEARCH exists, the search list that it specifies is used to locate the COPY library. If =_SOURCE_SEARCH does not exist, only the current volume and subvolume is searched for the COPY library. REPLACING phrase specifies text-words for the compiler to replace with other specified text-words when it copies text. See REPLACING Phrase. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10- 3 Source Text Manipulation COPY Statement Usage Considerations: • Where COPY Statements Can Be Used With these exceptions, a COPY statement can occur anywhere in the source text that a character-string or separator can occur: • ° ° A COPY statement cannot appear within the body of another COPY statement. ° If the word COPY appears either in a comment-entry or in a place where a comment-entry can appear, it is considered part of the comment-entry, not as the keyword that begins a COPY statement. ° The keyword COPY must be preceded by a space character, unless it immediately follows the indicator field. ° A COPY statement cannot appear on the same line as an SQL/MP or SQL/MX statement. ° All four characters of the keyword COPY must appear on the same source text line. The remainder of the statement can extend across additional program text lines, in accordance with the continuation conventions of the reference format. A COPY statement cannot appear within source text that is introduced by another COPY statement or a REPLACE statement. How the Compiler Processes a COPY Statement The compiler processes a source program that includes COPY statements as though the compiler included a preprocessor that performs these operations in this order: 1. Locates each COPY statement 2. Replaces the COPY statement with the appropriate (and possibly edited) library text 3. Passes the resulting text to the compiler proper The effect of processing a COPY statement is to copy the specified library text into the source program. The copied text logically replaces the entire COPY statement, beginning with the keyword COPY and ending with the punctuation character period. If the source line on which the COPY statement begins contains other text preceding the word COPY, the compiler attempts to combine that portion of the line with the first library text line. If the source line on which the COPY statement ends contains other text following the terminating period, the compiler attempts to combine that portion of the line with the last library text line. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10- 4 Source Text Manipulation • COPY Statement Compiler Directives and the COPY Statement A compiler directive line cannot appear between the keyword COPY and the period separator that terminates the statement, unless it is part of pseudo-text (see REPLACE Statement). • Compiler Directives in Library Text Library text can include compiler directives, which the compiler obeys when it analyzes the copied text. If a TANDEM or ANSI format directive occurs as a qualifier on the SECTION directive in the library file, the specified formatting is active only for the copied text. When the copying is complete, the previous formatting is again active. If a TANDEM or ANSI format directive occurs within the library text, its effect (which overrides the effect of any format directive that is a qualifier on the SECTION directive) persists until the copying is complete. • Debugging Lines and the COPY Statement If the COPY statement itself begins on a debugging line (a line that has a D or d in the indicator field), all text that the copy operation introduces into the source program, except comment and compiler directive lines, appears on debugging lines. Because debugging lines and continuation lines are mutually exclusive, the compiler cannot introduce a continued text-word into the source text when the preceding rules require it to appear on debugging lines. • Sensitivity to Reference Format Because the compiler analyzes pseudo-text without the benefit of any contextual information, you must observe the COBOL reference format rules carefully. In particular, the compiler does not identify a comma, semicolon, or period character as a separator unless it is followed by at least one space character. Similarly, the compiler interprets the character sequence X/9 as one text-word (presumably a PICTURE character-string) rather than as three text-words; however, the compiler always considers a left parenthesis, right parenthesis, or colon character to be a separator unless it appears within a nonnumeric literal. Another reason to carefully observe the reference format rules is that, when the compiler is performing replacement editing, it analyzes library text without the benefit of any contextual information. • Including COPY Statements in a Listing The SHOWCOPY directive determines whether the COPY statement itself appears in the listing (see SHARED). If you do not specify NOSHOWCOPY, NOLIST, or SUPPRESS, the compiler lists the COPY statement as a comment followed by the copied text. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10- 5 Source Text Manipulation COPY Statement In Example 10-1, EMPLOYEE-DETAIL of the COPY statement is not qualified because the COPY library is named COPYLIB and resides on the current volume and subvolume for the compile process. Example 10-1. COPY Statement Contents of COPY library COPYLIB: ?SECTION EMPLOYEE-DETAIL 01 EMP-DATA-IN. 05 EMP-NO PIC 05 EMP-NAME PIC 05 DEPT PIC 05 JOB-CLASS PIC 05 HOURLY-RATE PIC 05 DEDUCTIONS PIC 05 SALARY PIC X(05). X(20). X(03). X(05). 9(3)V99. 9(3)V99. 9(7)V99. Source COBOL code: ... DATA DIVISION. FILE SECTION. FD EMP-MASTER COPY EMPLOYEE-DETAIL. FD LIST-OUT ... Source listing produced by compiler (lines from the COPY library are marked by < in the compilation listing): < < < < < < < < ... DATA DIVISION. FILE SECTION. FD EMP-MASTER *COPY EMPLOYEE-DETAIL. 01 EMP-DATA-IN. 05 EMP-NO PIC 05 EMP-NAME PIC 05 DEPT PIC 05 JOB-CLASS PIC 05 HOURLY-RATE PIC 05 DEDUCTIONS PIC 05 SALARY PIC FD list-out ... X(05). X(20). X(03). X(05). 9(3)V99. 9(3)V99. 9(7)V99. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10- 6 Source Text Manipulation REPLACING Phrase REPLACING Phrase The REPLACING phrase of the COPY statement directs the compiler to replace every occurrence of a portion of library text with a replacement portion when it copies library text into a source program. You can specify more than one pair of such portions for the compiler to replace when it executes a COPY statement. The compiler searches for each original portion in the order in which you declared them in the REPLACING phrase. . REPLACING OFF original BY new VST247.vsd original pseudo-text-1 identifier-1 literal-1 word-1 VST248.vsd new pseudo-text-2 identifier-2 literal-2 word-2 VST249.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 10- 7 Source Text Manipulation REPLACING Phrase pseudo-text-1 == text-word == VST250.vsd contains at least one text-word other than a comma or semicolon separator. A character-string within pseudo-text-1 can continue on the next line, but both characters of the pseudo-text delimiter (==) must be on the same line. pseudo-text-2 == == text-word VST251.vsd can be null. A character-string within pseudo-text-2 can continue on the next line, but both characters of the pseudo-text delimiter (==) must be on the same line. text-word is any character-string or separator, except space. identifier-1 identifier-2 are identifiers of data items. literal-1 literal-2 are literals (but not national literals). Neither can be a concatenation expression. word-1 word-2 are COBOL words. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10- 8 Source Text Manipulation REPLACING Phrase Usage Considerations: • Effect of REPLACE on Literals The REPLACE statement does not affect literals; for example, REPLACING ==Year== BY ==Month== does not change the original text-word "End of Year" to the new text-word "End of Month" • Matching Text in a COPY Library The compiler searches for portions of text in the order you specify in the REPLACING phrase. If you want to replace a sequence of text-words with something and a particular text-word with something else, specify the sequence first. For example, if you want to replace all occurrences of “XXX” with “BALANCE” and all occurrences of “XXX OF YYY” with “BALANCE OF BUDGET-REC,” the REPLACING phrases must be in this order: REPLACING "XXX OF YYY" BY "BALANCE OF BUDGET-REC" "XXX" BY "BALANCE" If you specify “XXX” first, the compiler first changes the “XXX” to “BALANCE,” producing “BALANCE OF YYY;” therefore, it can never find the sequence “XXX OF YYY.” For purposes of matching, the compiler handles identifier-1, word-1, and literal-1 as pseudo-text containing only identifier-1, literal-1, or word-1, respectively. • Comparison Operation The compiler determines which characters of source text to replace by comparing pseudo-text-1, identifier-1, literal-l to text-words in the COPY library. This is how the comparison operation works: 1. The compiler copies any separator comma, semicolon, and space that precedes the leftmost library text-word into the source program. 2. Starting with the leftmost library text-word, the compiler compares all the textwords in the first pseudo-text-1, identifier-1, literal-1, or word-1 to an equal number of contiguous text-words in the library. During the comparison, the compiler handles each occurrence of a separator comma or semicolon and each sequence of one or more space separators as a single space. The compiler ignores any comment or directive line in the library text or in pseudo-text-1. The REPLACING phrase operand matches the library text if the two sequences of text-words are equal, character for character. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10- 9 Source Text Manipulation REPLACING Phrase 3. If no match occurs, the compiler repeats the comparison with each successive pseudo-text-1, identifier-1, word-1, or literal-1, if any, in the REPLACING phrase until a match occurs or until it has compared each operand in the phrase to the leftmost library text-word or text-words. 4. If the compiler compares all the REPLACING phrase operands without finding a match, it copies the leftmost library text-word into the source program. Then the compiler uses the next successive library text-word as the leftmost textword and starts the comparison cycle again with the first pseudotext-1, identifier-1, literal-1, or word-1 in the REPLACING phrase. 5. Whenever a match occurs between pseudo-text-1, identifier-1, literal-1, or word-1, the compiler copies the corresponding pseudotext-2, identifier-2, literal-2, or word-2 into the source program. The compiler places the text-words into the program according to the rules of the reference format specified in the COPY statement or, if not specified, the reference format active before the statement. Then the compiler uses the library text-word immediately following the matching library text as the leftmost text-word and starts the comparison cycle again with the first pseudo-text1, identifier-1, literal-1, or word-1 in the REPLACING phrase. 6. The comparison operation ends after the rightmost text-word in the library text participates either in a match or as a leftmost text-word in a complete comparison cycle. • Comment Lines in Replacement Text The compiler copies any comment line in pseudo-text-2 into the source program unchanged. • Debugging Lines You can put debugging lines in library text and in pseudo-text-2 or in pseudotext-1. Text-words within a debugging line participate in the comparison cycle as though the indicator area did not contain a D or d. If a portion of the library text is replaced by a pseudo-text-2, any text-words of the replacement text specified on debugging lines appear on debugging lines in the resulting source text. If a portion of the library text that begins on a debugging line is replaced, all textwords of the replacement text appear on debugging lines in the resulting source text. If library text specified on debugging lines is copied without replacement, it appears on debugging lines in the resulting source text. A debugging line cannot contain embedded SQL/MP or SQL/MX statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10 -10 Source Text Manipulation COPY Libraries Example 10-2. COPY Statement With REPLACING Phrases COPY CUSTOMER REPLACING ==FULL NAME== BY ==Able X. Baker== ADDRESS BY STREET-ADDRESS. COPY Libraries A COPY library is either a file in the EDIT format or an OSS ASCII text file. Its text can be merged into a source program during compilation using a COPY statement. If the COPY statement contains a REPLACING phrase, specified portions of library text can be replaced by specified new text when the COPY statement copies the library text into the source program. With or without the REPLACING phrase, the COPY statement does not change the COPY library. Topics: • • Specifying Library Names Library Format Specifying Library Names There are three places you can specify the name of the library from which a COPY statement is to collect text: • • • The COPY statement itself can include an IN library-name phrase (see COPY Statement), in which the name can be a file-system file name or (in the Guardian environment) an alphanumeric literal containing a DEFINE name. The COBOL85 command that initiates the compilation can include a library name to be used whenever a COPY statement does not include a library name (see Starting a Compilation). On a command line, the library name parameter is either a file-system file name or (in the Guardian environment) a DEFINE name, but neither can be enclosed in quotation marks. In the OSS environment, you can specify the default COPY library with the -Wcopylib flag. If no name is specified on either the command line or the COPY statement, the compiler uses the name COPYLIB. If library-name is not fully qualified with volume and subvolume, the current default volume or subvolume is used. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10 -11 Source Text Manipulation Library Format Library Format section-text pre-text VST252.vsd pre-text is one or more text lines. These lines are never copied. When a library file begins with pre-text, this text can be comments about the library’s sections. The compiler examines pre-text only to look for a question mark (?) in column 1 followed by zero or more spaces followed by the directive COLUMNS (in any combination of cases). If it finds such a directive, it attempts to translate and use it. section-text ? SECTION text-name , format text-line VST253.vsd SECTION is the SECTION directive described in SECTION. text-name is the name of the section, the name that identifies the portion of the library file to be copied. It is a COBOL word (1 to 30 letters, digits, and hyphens but not all digits). format is the keyword TANDEM or ANSI. text-line is a line of source text. There is no limit on the number of such lines. No text line can begin with “?SECTION.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 10 -12 Source Text Manipulation Library Format Usage Considerations: • COLUMNS Directive The library can contain at most one COLUMNS directive. The COLUMNS directive must precede all SECTION directives and must appear alone in its compiler directive line. Furthermore, the line’s question mark must always be in column 1 (even if the ANSI source text format applies). • SECTION Directive Each SECTION directive must appear alone in a compiler directive line and the line’s question mark must always be in column 1 (even if the ANSI source text format applies). Each SECTION directive demarcates an individual text unrelated to any other contents of the source library. A SECTION directive cannot appear anywhere in the text of a COPY statement (between the word COPY and its terminating period in the input stream) or a REPLACE statement (between the word REPLACE and its terminating period in the input stream); however, the compiler detects and reports its appearance within pseudo-text only if that pseudo-text is introduced into the source as the result of expanding the COPY statement or by the editing effects of the REPLACE statement. During program compilation, the compiler identifies a section by locating the SECTION directive whose text-name matches the text-name specified in the COPY statement. For more information, see SECTION. • Copying Sections of Text The compiler copies text starting at the line after the SECTION directive line and continues until it recognizes another SECTION directive or reaches the end of the file. • No COPY Statements in COPY Library Sections The COPY statement cannot be within a section of a COPY library. • Reference Format The compiler assumes that the reference format of the library text is the same as that of the line containing the COPY statement, unless you specify a different format in the SECTION directive. (For information on Tandem format, see Reference Format for Source Program Lines. For information on ANSI format, see Section 16, ANSI Reference Format.) If you specify a reference format in a SECTION directive, that format is active only during execution of the COPY statement. After the compiler copies a section, it uses the reference format previously active. • Compiler Directives in a COPY Library Source text in a COPY library can contain compiler directives, which the compiler obeys when it analyzes the copied text. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10 -13 Source Text Manipulation • REPLACE Statement Compiler Builds a Directory of the COPY Library The first time the compiler reads from a COPY library, it begins to build a directory for itself that enables it to locate the individual sections. It reads through the library, building its directory, until it finds the selected section. After copying it, it resumes normal compilation. For subsequent COPY statements, it checks its directory. If the chosen section is in the directory, the compiler can go right to it; otherwise, it resumes reading the library where it left off, and continues as before. If you put sections that most programs use in the front of the library and those that few programs use at the end, compilation speed is improved. • Adding Source Text to a COPY Library Since COPY libraries are files in the EDIT format or OSS ASCII files, you can add a section of source text to a library by editing it. You can put a SECTION directive line and the source text that follows it before, between, or after sections already in the library. REPLACE Statement REPLACE substitutes zero or more words of pseudo-text for one or more words of pseudo-text. REPLACE pseudo-text-1 BY pseudo-text-2 . OFF VST254.vsd REPLACE is a reserved word that cannot be split across source program lines. pseudo-text-1 == text-word == VST250.vsd contains at least one text-word other than a comma or semicolon separator. A character-string within pseudo-text-1 can continue on the next line, but both characters of the pseudo-text delimiter (==) must be on the same line. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10 -14 Source Text Manipulation REPLACE Statement pseudo-text-2 == == text-word VST251.vsd can be null. A character-string within pseudo-text-2 can continue on the next line, but both characters of the pseudo-text delimiter (==) must be on the same line. text-word is any character-string or separator except space. It cannot be a concatenation expression. OFF marks the end of the scope of replacement of the most recent REPLACE statement. Usage Considerations: • Comment Lines and Directive Lines in Pseudo-Text Pseudo-text can contain comment lines and directive lines (that is, the text-words in pseudo-text can be organized as comment lines and directive lines). • Where REPLACE Statements Can Be Used With these exceptions, a REPLACE statement can occur anywhere in the source text that a character-string can occur: ° A REPLACE statement cannot appear within the body of another REPLACE statement. ° A REPLACE statement cannot appear within source text introduced by another REPLACE statement. ° If the word REPLACE appears either in a comment-entry or in a place where a comment-entry can appear, it is considered part of the comment-entry, not as the keyword that begins a REPLACE statement. ° The keyword REPLACE must be preceded by a period separator, except when it begins the first statement of a separately compiled program. ° A REPLACE statement cannot appear on the same line as an SQL/MP or SQL/MX statement. All seven characters of the keyword REPLACE must appear on the same source text line. The remainder of the statement can continue across additional program text lines, in accordance with the continuation conventions of the reference format. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10 -15 Source Text Manipulation • REPLACE Statement Persistence A given occurrence of the REPLACE statement is active from the point at which you specify it until the next occurrence of a REPLACE statement or the end of the separately compiled program, respectively. • REPLACE Statements and the Listing The listing the compiler produces shows the lines containing REPLACE statements like any other lines. When any replacement occurs, the image in the listing is that of the text after replacement. • Order of Processing Conceptually, the compiler processes any REPLACE statements in a source program after it has processed any COPY statements. • Comparison Operation The compiler determines which sequences of text-words to replace by comparing pseudo-text-1 to text-words in the source text. This is how the comparison operation works: 1. Starting with the leftmost source program text-word and the first pseudotext-1, the compiler compares the word or words of pseudo-text-1 with the equivalent number of contiguous text-words in the source program. 2. During the comparison, the compiler handles each occurrence of a separator comma or semicolon and each sequence of one or more space separators as a single space. The compiler ignores any comment or directive line in the source text or in pseudo-text-1. The pseudo-text-1 matches the source text if the two sequences of text-words are equal, character for character. 3. If no match occurs, the compiler repeats the comparison with each successive occurrence of pseudo-text-1, if any, in the REPLACE statement until a match occurs or until it has compared each operand in the pseudo-text-1 to the leftmost source program text-word or text-words. 4. If the compiler compares all the occurrences of pseudo-text-1 without finding a match, it considers the next text-word of the source program as the leftmost source program text-word and starts the comparison cycle again with the first occurrence of pseudo-text-1. 5. Whenever a match occurs between pseudo-text-1 and the source program text, the compiler replaces the matched text in the source program with the corresponding pseudo-text-2. The compiler then considers the source program text-word immediately following the rightmost text-word that participated in the match to be the leftmost source program text-word, and starts the comparison cycle again with the first occurrence of pseudotext-1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10 -16 Source Text Manipulation REPLACE Statement 6. The compiler continues its comparison operation until either the rightmost textword in the source program text (within the scope of the REPLACE statement) has participated in a match or has been considered as a leftmost text-word and participated in a complete comparison cycle. • Comment Lines and Blank Lines in Replacement Text The matching operation ignores any comment lines or blank lines occurring in the source program text. The compiler determines the sequence of text-words in the source program text and in pseudo-text-1 by the rules for reference format. The replacement operation copies comment lines or blank lines in pseudotext-2 into the source program text without change whenever it copies pseudotext-2 into the source program. The compiler does replace a comment line or blank line in source program text if that comment line or blank line appears within the sequence of text-words that match pseudo-text-1. • Debugging Lines You can put debugging lines in pseudo-text-1 or in pseudo-text-2. textwords within a debugging line participate in the comparison cycle as though the indicator area did not contain a D or d. If a portion of the apparent source text is replaced, any text-words of the replacement text specified on debugging lines appear on debugging lines in the final source text. If a portion of the apparent source text that begins on a debugging line is replaced, all text-words of the replacement text appear on debugging lines in the final source text. If the REPLACE statement itself begins on a debugging line, all replacement text, except comment and compiler directive lines, appears on debugging lines. Because debugging lines and continuation lines are mutually exclusive, the compiler cannot introduce a continued text-word into the source text when the preceding rules require it to appear on debugging lines. • Sensitivity to Reference Format Because, when a REPLACE statement is in force, the compiler analyzes pseudotext (and source text) without the benefit of any contextual information, you must observe the COBOL reference format rules carefully. In particular, the compiler does not identify a comma, semicolon, or period character as a separator unless it is followed by at least one space character. Similarly, the compiler interprets the character sequence X/9 as one text-word (presumably a PICTURE character-string) rather than as three text-words; however, the compiler always considers a left parenthesis, right parenthesis, or colon character to be a separator unless it appears within a nonnumeric literal. HP COBOL Manual for TNS and TNS/R Programs —522555-006 10 -17 Source Text Manipulation REPLACE Statement The REPLACE statement in Example 10-3 enables you to declare a name for a constant in your program, then use that name in various places in a program. While OFFICES could have been declared as a data-item for this purpose, SQ-FTSIZE could not have. Of course, with either EDIT or PS Text Edit (TEDIT), you could easily change all instances of reserved words in a source program to another word; but if your data dictionary contains any fields whose names have become reserved words, you might find the REPLACE statement a handy tool. The REPLACE operation occurs conceptually after the COPY operation, but before the remainder of the compilation. Example 10-3. REPLACE Statement DATA DIVISION. REPLACE ==OFFICES== BY ==10== ==SQ-FT-SIZE== BY ==5==. ... 01 OFFS. 03 OFFICE-INFO OCCURS OFFICES TIMES. 05 DISTRICT PICTURE 99. 05 SQUARE-FEET PICTURE S9(SQ-FT-SIZE). ... PROCEDURE DIVISION. ... PERFORM REPORT-OFFICE OFFICES TIMES. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 10 -18 11 Program Compilation Throughout this section, “compiler” means both the COBOL85 and NMCOBOL compilers unless otherwise stated. The compiler can run at a high PIN (a process identification number greater than 255) and can be requested by other processes running at high PINs. The compiler accepts one source file as input. That source file can use SOURCE directives and COPY statements to read text from other source files. The source file that is input to the compiler and the source files from which it reads text can contain one or more source programs, each consisting of HP COBOL statements, comment lines, and compiler directives (instructions to the compiler). Compiler directives can also appear on the compiler command line. Compiler directives specify the source format, control listing features, control selective compilation of portions of the source code, and request compilation options; therefore, they affect the output of the compiler. By default, if the source file has no errors, the compiler outputs a listing and an object file. The NOLIST and SUPPRESS directives can suppress all or parts of the listing file. The COBOL85 compiler produces an object file that can be both executed and input to the Bind utility. The NMCOBOL compiler produces an object file that can either be input to the nld utility (the default), input to the ld utility, or executed. The SYNTAX directive can suppress all or parts of the object file. Syntax errors in the source file can also suppress all or parts of the object file: Syntax errors are in: COBOL85 produces: NMCOBOL produces: All programs in the compilation No object file No object file Some programs in the compilation Partial object file No object file No programs in the compilation Complete object file Complete object file The rest of this section applies primarily to the Guardian environment. If you are compiling HP COBOL programs in the OSS environment, see Section 19, Using HP COBOL in the OSS Environment. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 1 Program Compilation Compiler Input Figure 11-1. Compiler Input and Output (affected by NOLIST and SUPPRESS directives) Listing File Compiler Source File (affected by SYNTAX directives and errors) Object File VST515.vsd Topics: • • • • • Compiler Input Compilation Details Compiler Output Running the Compiler Compiler Directives Compiler Input Input to the compiler is always a single source file, but that source file can read text from other source files (using SOURCE directives and COPY statements). The source file that is input to the compiler and the source files from which it reads text can contain one or more source programs. One of these source programs can be a main program. The source programs can call each other, and, under some circumstances, they can also call non-COBOL programs. The source file that is input to the compiler is also called a compilation unit. Topics: • • • • Main Programs Calling and Called Programs How an HP COBOL Program Calls a Non-COBOL Program Compilation Units HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 2 Program Compilation Main Programs Main Programs A main program is either compiled with the MAIN directive (see MAIN) or it has no Linkage Section (see Absent Linkage Section). A loadfile must contain exactly one main program. It can also contain other programs. When the loadfile is executed, the NonStop operating system calls the main program. Then the main program can call the other programs and the other programs can call each other. The NonStop operating system does not call the other programs. In Example 11-1, the MAIN directive makes A-PROGRAM a main program. If A-PROGRAM and A-FRIEND are compiled in the same compilation unit, A-FRIEND is not a main program. If A-FRIEND is compiled alone, it is a main program, because it does not have a Linkage Section. Example 11-1. Main Program and Another Program ?MAIN A-PROGRAM IDENTIFICATION DIVISION. PROGRAM-ID. A-PROGRAM. ENVIRONMENT DIVISION. ... SPECIAL-NAMES. FILE "$SYSTEM.COBSYS.BFILES" IS B-FILE. DATA DIVISION. ... PROCEDURE DIVISION. ... CALL "A-FRIEND" ... CALL "B-FRIEND" IN B-FILE ... STOP RUN. END PROGRAM A-PROGRAM. IDENTIFICATION DIVISION. PROGRAM-ID. A-FRIEND. ENVIRONMENT DIVISION. ... SPECIAL-NAMES. FILE "$SYSTEM.COBSYS.BFILES" IS B-FILE, FILE "$SYSTEM.TALSYS.TFILES" IS T-FILE. DATA DIVISION. ... PROCEDURE DIVISION. ... CALL "HOME" IN BFILE ... ENTER TAL "SPECIALIST" IN T-FILE ... STOP RUN. END PROGRAM A-FRIEND. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 3 Program Compilation Calling and Called Programs Calling and Called Programs Many languages have declarations that distinguish main programs from subprograms. COBOL does not use the term “subprogram.” Instead, it defines a program as a “calling program” if it contains a CALL or ENTER statement and defines a program as a “called program” if it is the object of a CALL or ENTER statement. A program can be both a calling program and a called program. The distinction is one of usage, not of explicit declaration. In Example 11-1, A-PROGRAM is a calling program and AFRIEND is both a called program and a calling program. If a called COBOL program is to receive parameters, it must have a Linkage Section (see Linkage Section). The statement a COBOL program uses to call another program depends on the language in which the called program was written. Table 11-1. Statements for Calling Programs Language of Called Program Statement for Calling Program HP COBOL CALL HP C ENTER or X/Open CALL HP C++ ENTER or X/Open CALL FORTRAN* ENTER or X/Open CALL Pascal* ENTER or X/Open CALL pTAL ENTER or X/Open CALL TAL* ENTER or X/Open CALL * Native HP COBOL programs cannot call programs written in this language. Called programs are not required to be in the main program’s compilation unit (see Compilation Units). How an HP COBOL Program Calls a Non-COBOL Program Any HP COBOL program can call a non-COBOL program with the ENTER statement. An HP COBOL program that runs in the CRE and was compiled with the PORT directive can also call a non-COBOL program with the X/Open CALL statement. The difference between the ENTER statement and the X/Open CALL statement is that the ENTER statement attempts to coerce the actual parameters into the types of the formal parameters, while the X/Open CALL statement reports an error if the types of the actual and formal parameters do not match. Just as HP COBOL object programs can be read from an object file and included in the target file during the binding phase of COBOL85 compilation or the (optional) linking phase of NMCOBOL compilation, object programs from other languages can also. Note. You cannot put any combination of TNS, TNS/R, or TNS/E object files into a single object file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 4 Program Compilation Compilation Units Appendix B, Data Type Correspondence, shows the correspondence between HP COBOL data items and those of the other languages with which an HP COBOL program can interact. HP COBOL index names are entirely internal to their own program; they cannot be written, read, or passed as parameters. Index data items in HP COBOL correspond to 32-bit integers. In Example 11-2, a TNS HP COBOL program calls a FORTRAN program to get the base-10 logarithm of a value. Example 11-2. TNS HP COBOL Program Calling FORTRAN Program COBOL main program fragment: 01 FTN-PARAMETERS. * DOUBLEWORDS, SCALED UP BY 1000 03 LOGARG PICTURE S9(8) COMP. 03 LOGANS PICTURE S9(8) COMP. 01 UNSCALED PICTURE 9(5)v9(3). ... MOVE 123.45 TO UNSCALED MULTIPLY UNSCALED BY 1000 GIVING LOGARG ENTER FORTRAN "LOGTEN" OF MATHS USING LOGARG GIVING LOGANS DIVIDE LOGANS BY 1000 GIVING UNSCALED FORTRAN subprogram fragment: C C INTEGER*4 FUNCTION LOGTEN ( IA ) INTEGER*4 IA DOUBLE PRECISION DA SCALE BACK DOWN DA = DBLE (IA) / 1000 GET DOUBLE PRECISION LOG, RESCALE, CONVERT TO INT LOGTEN = INT4 ( DLOG10 (DA) * 1000.D0 ) RETURN Compilation Units The source file that is input to the compiler is also called a compilation unit. A compilation unit contains one or more “separately compiled programs.”A separately compiled program is a program whose source text can be submitted to the compiler independently of any other source text. Each such program can include nested programs, and any program can call other separately compiled programs. Submitting a sequence of separately compiled programs to the compiler as a compilation unit (in a single compilation step) is called “stacked compilation.” The end of each separately compiled program is ordinarily marked by an END PROGRAM statement, although it can be marked with an ENDUNIT compiler directive with equivalent effect. The last (or only) program in a compilation unit does not require an END PROGRAM statement or an ENDUNIT directive. Separately compiled programs in a compilation unit can be in any order. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 5 Program Compilation Compilation Units If there are compilation errors in some, but not all, programs in a compilation unit, the COBOL85 compiler produces object programs for the programs in which there were no errors, but the NMCOBOL compiler produces no object file. Example 11-3 shows a compilation unit in which a main program and two called programs are included in the input file, contained in file CSOURCE. The command to compile the compilation unit in Example 11-3 with the COBOL85 compiler is: COBOL85 /IN CSOURCE/ COBJECT The command to compile the compilation unit in Example 11-3 with the NMCOBOL compiler is: NMCOBOL /IN CSOURCE/ COBJECT COBJECT is called the target file. It contains the object programs that the compiler produces. Figure 11-2 illustrates the case for the COBOL85 compiler when no source file in CSOURCE has compilation errors. Example 11-3. Compilation Unit (page 1 of 2) IDENTIFICATION DIVISION. PROGRAM-ID. CPGM1. * CALLED PROGRAM 1. ... DATA DIVISION. ... LINKAGE SECTION. 01 LS-NAMES. 03 LS-A-NAME PICTURE X(30). 03 LS-B-NAME PICTURE X(30). ... END PROGRAM CPGM1. IDENTIFICATION DIVISION. PROGRAM-ID. CALLER. * THE MAIN PROGRAM FOR THIS COMPILATION. ... DATA DIVISION. ... WORKING-STORAGE SECTION. 01 WS-PARTS. 03 WS-FIRST-PART PICTURE X(30). 03 WS-SECOND-PART PICTURE X(30). 01 WS-PRODUCER. 03 WS-PRODUCER-NAME PICTURE X(60). 03 WS-PRODUCER-ADDRESS PICTURE X(60). PROCEDURE DIVISION. CALL "CPGM1" USING WS-PARTS CALL "CPGM2" USING WS-PARTS WS-PRODUCER ... END PROGRAM CALLER. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 6 Program Compilation Compilation Units Example 11-3. Compilation Unit (page 2 of 2) IDENTIFICATION DIVISION. PROGRAM-ID. CPGM2. * CALLED ... DATA DIVISION. ... LINKAGE SECTION. 01 LS-SUBASSY. 03 LS-SUBASSY-1 PICTURE 03 LS-SUBASSY-2 PICTURE 01 LS-MFGR. 03 LS-MFGR-NAME PICTURE 03 LS-MFGR-ADDR PICTURE ... PROGRAM 2. X(30). X(30). X(60). X(60). Figure 11-2. TNS Compilation Unit, Listing File, and Object File SYMSERV CSOURCE CPGM1 CALLER CPGM2 Copy Library COBOL85 Listing File COBJECT BINSERV CPGM1 CALLER CPGM2 VST517.vsd Called programs are not required to be in the main program’s compilation unit. They can reside in their own files and be compiled to produce separate object files. Such object files need not be loadfiles. They can exist solely as resources for binding or linking (see Object File Creation). Example 11-4 calls program units that are in a separate file, C-ARCHIVE. When the main program is compiled, the two called programs are included in the resulting target file. Figure 11-3 shows the compilation of the program containing this fragment, assuming that COBJECT is the object file produced by the compilation shown in Example 11-3. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 7 Program Compilation Compilation Units Example 11-4. Calling Programs That Are in a Separate File PROGRAM-ID. CALLER. ... SPECIAL-NAMES. FILE "$MYVOL.MYSUB.COBJECT" IS C-ARCHIVE. ... CALL "CPGM1" IN C-ARCHIVE ... CALL "CPGM2" IN C-ARCHIVE Figure 11-3. TNS Compilation With Object-File Inclusion SYMSERV CSOURCE Source File COBOL85 BINSERV Listing File Target File CPGM1 Copy Library CALLER CPGM2 COBJECT Object file (input) CPGM1 CPGM2 VST518.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 8 Program Compilation Compilation Details Compilation Details • • • • • Processes Involved in Compilation Temporary File Placement CALL and ENTER Statement Processing: Overview CALL and ENTER Statement Processing: Detailed Explanation #RECEIVE Blocks Processes Involved in Compilation The processes involved in compilation differ for the COBOL85 and NMCOBOL compilers. Topics: • • COBOL85 Compiler NMCOBOL Compiler HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 9 Program Compilation Processes Involved in Compilation COBOL85 Compiler The COBOL85 compiler consists of one process, COBOL85. Two other processes, SYMSERV and BINSERV, are present throughout the compilation. SYMSERV collects symbol table information, puts it into structures in a temporary file, and gives the temporary file to BINSERV. BINSERV writes the information from the temporary file into the object file. BINSERV also performs binding. The symbol table information in the object file can be used later by the symbolic debuggers. Figure 11-4. COBOL85 Compilation of Single Program Unit SYMSERV Source Files COBOL85 Copy Libraries BINSERV Listing File Target File VST519.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -10 Program Compilation Temporary File Placement NMCOBOL Compiler The NMCOBOL compiler consists of a driver process, NMCOBOL, and a sequence of subordinate processes. For a successful compilation, the NMCOBOL compiler driver calls COBOLFE, UGEN, and AS1 in turn, using temporary files to pass information between them. If you specify the RUNNABLE or SEARCH directive when creating a non-PIC loadfile, the NMCOBOL compiler also calls the nld utility. If you specify the RUNNABLE or SEARCH directive when creating a PIC loadfile (CALL-SHARED) or a DLL library (SHARED), the NMCOBOL compiler also calls the ld utility. The symbol table information in the object file can be used later by the symbolic debuggers. Figure 11-5. NMCOBOL Compilation of Single Program Unit (Non-PIC) Source Files COBOLFE NMCOBOL nld UGEN AS1 Loadfile Copy Libraries Linkfile Listing File VST727.vsd Temporary File Placement The COBOL85 and NMCOBOL compilers and their supporting processes create and use temporary files. Default temporary file placement differs slightly for the two compilers. Topics: • • • COBOL85 Compiler NMCOBOL Compiler Specifying a Volume for Temporary Files HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -11 Program Compilation CALL and ENTER Statement Processing: Overview COBOL85 Compiler By default, the COBOL85 compiler creates its temporary files on the current default volume. The BINSERV and SYMSERV processes create their temporary files on the volume where the target file is located, unless that volume is on another node. If the volume is on another node, the BINSERV and SYMSERV processes create their temporary files on the current default volume of the node on which they execute. For example, suppose you are executing on \MYSYS and your default volume is $CURR. If you execute the command: COBOL85 /IN MYSRC, OUT $S.#MYLST/ \ALIEN.$FAR.XX.MYOBJ the BINSERV and SYMSERV processes use $CURR for any temporary files, instead of using volume $FAR on system \ALIEN. NMCOBOL Compiler By default, the NMCOBOL compiler creates its temporary files on the current default volume. If called by the NMCOBOL compiler, the processes COBOLFE, UGEN, and AS1 and the linker create their temporary files on the current default volume. Specifying a Volume for Temporary Files The PARAM SWAPVOL command specifies the volume on which the compiler and its processes will create temporary files (if possible). It does not determine where the operating system creates the compiler’s own swap file. For details, see PARAM SWAPVOL. The RUN option SWAP specifies one volume for both the temporary files that the compiler and its processes will create and for the compiler’s own swap file. For more information on SWAP and other RUN options, see the TACL Reference Manual. CALL and ENTER Statement Processing: Overview Any TNS HP COBOL program can call TNS HP COBOL programs with CALL statements. Any TNS/R HP COBOL program can call TNS/R HP COBOL programs with CALL statements. Any HP COBOL program can call non-COBOL programs with ENTER statements. A HP COBOL program that runs in the CRE and was compiled with the PORT directive can also call non-COBOL programs with X/Open CALL statements. In the CALL statement, the called program must be a COBOL program. It can be part of the same compilation unit as the calling program, or it can be an external reference to a COBOL program outside the compilation unit (but in the same object file). All ENTER statements cause external references, because they call programs compiled from source languages other than COBOL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -12 Program Compilation CALL and ENTER Statement Processing: Overview To generate the proper code to call a separately compiled program, the compiler needs a description of the parameter list of that program. Each CALL or ENTER statement can include qualification that specifies where the compiler must find the program. Although the compiler must search for unqualified programs, qualification significantly restricts the activity of the compiler. Topics: • • Qualified References How the Compiler Resolves Unqualified References Qualified References Each CALL or ENTER statement can include a file-mnemonic that identifies the object file where BINSERV or the linker must look for the called program, resolving the external reference and including the called program’s object code in the target file. You must associate this file-mnemonic with the object file’s file-system file name in the SPECIAL-NAMES paragraph in the Environment Division that governs the calling program. (Either the calling program is not nested, and contains an Environment Division; or the calling program is nested, and its outermost containing program contains an Environment Division.) If the compiler does not find the program in the specified object file, it reports an error and creates no code or data blocks for the program unit. Example 11-1 contains three examples of qualified references. How the Compiler Resolves Unqualified References When a program name is not qualified and the program it names is not in the compilation unit (such as the call to A-FRIEND in Example 11-1) the compiler resolves the reference in one of these ways: • • If you provided one or more search lists, the compiler examines those files in sequence for program names that correspond to the external references. If you did not provide search lists, or if the compiler did not find the necessary external references on them: ° The COBOL85 compiler examines COBOLEXT for resolution of TAL external references and does not resolve FORTRAN external references at all. ° The NMCOBOL compiler examines NMCOBEXT for resolution of external references. You create primary, secondary, and tertiary search lists with the SEARCH, LIBRARY, and CONSULT directives, respectively. (The NMCOBOL compiler does not recognize the LIBRARY directive or have a user library, the secondary search list.) You can also use the predefined SEARCH DEFINEs to specify one or more subvolumes to be searched for unqualified files (see Predefined SEARCH DEFINEs). HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -13 Program Compilation CALL and ENTER Statement Processing: Overview Topics: • • • • • • • Primary Search List Secondary Search List (COBOL85 Compiler Only) Tertiary Search List COBOLEXT File COBOLEX0 and COBOLEX1 Files NMCOBEXT File NMCOBEX0 and NMCOBEX1 Files Primary Search List SEARCH directives define the primary search list, an ordered list of object files. Each SEARCH directive adds one or more files to the primary search list. The compiler adds files to the search list in the order that they appear in the SEARCH directives. When trying to resolve unqualified external references, the compiler searches the files of the primary search list in the order that they appear. If the compiler resolves an external reference from the primary search list, the object program that the compiler finds is bound into the target file. Secondary Search List (COBOL85 Compiler Only) The LIBRARY directive defines the secondary search list, which consists of one file. Whenever the compiler encounters a LIBRARY directive, the object file named there becomes the new secondary search list. If a program is compiled with more than one LIBRARY directive, the one that applies to a specific ENTER statement is the last one the compiler encountered prior to that ENTER statement. If the compiler resolves an external reference from the secondary search list, the object program that the compiler finds is not bound into the target file. Programs resolved from the secondary search list are presumed to be in a user library. Tertiary Search List CONSULT directives define the tertiary search list. Each CONSULT directive adds one or more files to the tertiary search list. The compiler adds files to the search list in the order that they appear in the CONSULT directives. When trying to resolve unqualified external references, the compiler searches the files of the tertiary search list in the order that they appear. If the compiler resolves an external reference from the tertiary search list, the object program that the compiler finds is not bound into the target file. Programs resolved from the tertiary search list do not have to be in the system library. They can be elsewhere and can be bound in later or can be referenced in a run-time library. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -14 Program Compilation CALL and ENTER Statement Processing: Overview COBOLEXT File If you did not provide search lists, or if the compiler did not find the necessary external references on them, it uses the COBOLEXT file to perform parameter validation, but does not import any object code. Programs resolved from COBOLEXT are available to the program at load time. When you install the COBOL85 compiler, the COBOLEXT file is stored on the subvolume $SYSTEM.SYSTEM. If you move the COBOLEXT file to another subvolume, use the CONSULT directive to tell the compiler where to find it. COBOLEX0 and COBOLEX1 Files Each RVU of the COBOL85 compiler includes three files: COBOLEX0, COBOLEX1, and COBOLEXT. These represent the most recent, next most recent, and third most recent RVUs of the Guardian environment, respectively. If you need access to a routine that was added (or to a parameter that was added to an existing routine) in the most recent version of the Guardian environment, include a CONSULT directive specifying COBOLEX0 in your compilation. The compiler then validates all calls of Guardian system routines from COBOLEX0 instead of from COBOLEXT. When you install the COBOL85 compiler, the COBOLEX0 and COBOLEX1 files are stored on the subvolume $SYSTEM.SYSTEM. If you move either file to another subvolume, use the CONSULT directive to tell the compiler where to find it. NMCOBEXT File If you did not provide search lists, or if the compiler did not find the necessary external references on them, in ZCOBSRL, or in ZCRESRL, it uses the NMCOBEXT file to perform parameter validation, but does not import any object code. Programs resolved from NMCOBEXT are available to the program at load time. When you install the NMCOBOL compiler, the NMCOBEXT file is stored on the subvolume $SYSTEM.SYSTEM. If you move the NMCOBEXT file to another subvolume, use the CONSULT directive to tell the compiler where to find it. Note. The preceding paragraph applies only to the NonStop system. For the locations of files on the PC, see NonStop COBOL for TNS/R (ETK). NMCOBEX0 and NMCOBEX1 Files Each RVU of the NMCOBOL compiler includes three files: NMCOBEX0, NMCOBEX1, and NMCOBEXT. These represent the most recent, next most recent, and third most recent RVUs of the Guardian environment, respectively. If you need access to a routine that was added (or to a parameter that was added to an existing routine) in the most recent version of the Guardian environment, include a CONSULT directive specifying NMCOBEX0 in your compilation. The compiler then validates all calls of Guardian system routines from NMCOBEX0 instead of from NMCOBEXT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -15 Program Compilation CALL and ENTER Statement Processing: Detailed Explanation When you install the NMCOBOL compiler, the NMCOBEX1 and NMCOBEXT files are stored on the subvolume $SYSTEM.SYSTEM. If you move either file to another subvolume, use the CONSULT directive to tell the compiler where to find it. Note. The preceding paragraph applies only to the NonStop system. For the locations of files on the PC, see NonStop COBOL for TNS/R (ETK). CALL and ENTER Statement Processing: Detailed Explanation In processing CALL and ENTER statements, the compiler attempts to: 1. Find the called program (see Finding the Called Program) or the entered program (see Finding the Entered Program) 2. Validate the parameters in the calling program against those expected by the called program (see CALL and ENTER) 3. Generate any necessary instructions to present the parameters from the calling program in the form that the called program expects (see Presenting Parameters to the Called Program) 4. Generate any necessary instructions to deliver a returned value (from the GIVING clause of an ENTER statement) in the form that the calling program expects (see Delivering the Returned Value) 5. Bind or link the object code for the called program into the target file or postpone the binding or linking until the first time the loadfile is loaded for execution (see Binding or Linking the Object Code) Finding the Called Program When the compiler reaches the end of a separately compiled program, it identifies all program names that were explicitly referenced by CALL statements in that program. If a CALL statement specified an identifier instead of an explicit name, the compiler cannot validate the parameters and does not try to locate the program for that CALL. You are responsible for the conformance of the parameters. A compilation source text consists of one or more separately compiled HP COBOL programs. Each such program can include nested programs. Suppose separately compiled program S includes program P, which contains the statement CALL A. The compiler follows this procedure: 1. If program P directly contains a program named A, the compiler always chooses that program. In Example 11-5, the compiler issues a warning if a file-mnemonic appears. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -16 Program Compilation CALL and ENTER Statement Processing: Detailed Explanation 2. If program S contains a common program named A, and also contains (directly or indirectly) program P, then if P calls A, the compiler chooses the common program A. In Example 11-6, the compiler issues a warning if a file-mnemonic appears. If common program A contains program P (directly or indirectly), the compiler leaves P’s reference to A unresolved, and Item 4 applies. 3. If neither Item 1 or Item 2 applies, and a previously seen separately compiled program has the name A, the compiler chooses that program. 4. If Item 1, Item 2, and Item 3 do not apply, the compiler conducts a search for program A. If file-mnemonic appears, the compiler tries to find a separately compiled program unit in the file associated with the file-mnemonic. If the compiler cannot find such a program unit, it reports an error and delivers no object code for program S to the target file. If no file-mnemonic appears, the COBOL85 compiler consults the search lists. If the compiler finds no separately compiled program A in the object files of the search lists, the compiler expects a separately compiled program A to appear somewhere within the source text, and also expects all of program A’s parameters to have EXTENDED-STORAGE access mode (the default). If the compiler does find a program unit for A in the search lists, it resolves the reference with the first such program unit in the list. If the compiler discovers a separately compiled program A later in the source text, it replaces its previous resolution with the new one. If the new program A and the original program A have different numbers of parameters, or if their parameters have different access modes, the compiler reports an error and delivers no object code for program A to the target file. 5. When the compiler reaches the end of the source text, it issues a warning if it was unable to resolve any program references. You must supply the missing programs (using BIND or the linker) before you execute the loadfile. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -17 Program Compilation CALL and ENTER Statement Processing: Detailed Explanation Example 11-5. For Step 1 of Finding the Called Program IDENTIFICATION DIVISION. PROGRAM-ID. P. ... PROCEDURE DIVISION. ... CALL A ... ... IDENTIFICATION DIVISION. PROGRAM-ID. A. ... END PROGRAM A. IDENTIFICATION DIVISION. PROGRAM-ID. B. ... END PROGRAM B. END PROGRAM P. Example 11-6. For Step 2 of Finding the Called Program IDENTIFICATION DIVISION. PROGRAM-ID. S. ... PROCEDURE DIVISION. ... IDENTIFICATION DIVISION. PROGRAM-ID. A COMMON. ... END PROGRAM A. IDENTIFICATION DIVISION. PROGRAM-ID. P. ... CALL A ... END PROGRAM P. END PROGRAM S. Finding the Entered Program When it encounters an ENTER or X/Open CALL statement, the compiler follows this procedure: 1. If the compiler has already resolved the reference to the specified routine-name during the current compilation, the compiler resolves the current reference to that program. 2. If the compiler has not yet encountered the routine-name during the current compilation, the compiler conducts a search for the program: a. If file-mnemonic appears, the compiler tries to find a program with the specified name in the file associated with file-mnemonic. If the compiler finds the program, it verifies that language is the language in which the program was written. If the compiler does not find such a program, it reports an error. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -18 Program Compilation CALL and ENTER Statement Processing: Detailed Explanation b. If no file-mnemonic appears: The COBOL85 compiler looks for the program in the current search lists, in this order: 1. Primary search list 2. Secondary search list 3. Tertiary search list If the COBOL85 compiler does not find the program in any of the search lists, and the language is TAL, the compiler searches the COBOLEXT file located on the same volume and subvolume as the compiler. You can also use the predefined SEARCH DEFINEs to specify one or more subvolumes to be searched for unqualified files (see Predefined SEARCH DEFINEs). An unqualified file is one that is not defined with a subvolume or additional qualifiers. The NMCOBOL compiler looks for the program in these files in this order: 1. 2. 3. 4. 5. Primary search list Tertiary search list ZCOBSRL ZCRESRL NMCOBEXT c. If the compiler cannot find the program in any of the places discussed earlier, it reports an error and delivers no object code for the calling program. Note. If routine-name specifies an HP C or HP C++ function whose name includes lowercase letters, the call fails, because the compiler automatically converts all names to uppercase. Table 11-2 through Table 11-4 summarize the preceding information. Table 11-2. Resolution of External References (COBOL85 Compiler With No Search List Defined) (page 1 of 2) External reference found in ... Form1 MNEM Current Source File COBOLEXT Target File Created? CALL “P” IN MNEM Yes Irrelevant Irrelevant Yes No Irrelevant Irrelevant No, error reported 1. Bracketed items are optional. 2. For the COBOL85 compiler, language is HP C, FORTRAN, or Pascal. For the NMCOBOL compiler, language is HP C or TAL. 3. This form must be qualified when no search list is defined and the called routine is not in COBOLEXT or NMCOBEXT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -19 Program Compilation CALL and ENTER Statement Processing: Detailed Explanation Table 11-2. Resolution of External References (COBOL85 Compiler With No Search List Defined) (page 2 of 2) External reference found in ... MNEM Current Source File COBOLEXT Target File Created? Irrelevant Yes Irrelevant Yes Irrelevant No Irrelevant Yes, with unresolved externals; warning issued ENTER language 2 “R” IN MNEM Yes Impossible Irrelevant Yes No Impossible Irrelevant No, error reported ENTER language 2 “R” Irrelevant Impossible Irrelevant No, error reported ENTER [TAL] “R” IN MNEM Yes Impossible Irrelevant Yes No Impossible Irrelevant No, error reported ENTER [TAL] “R” 3 Irrelevant Impossible Yes Yes Irrelevant Impossible No No, error reported Form1 CALL “P” 1. Bracketed items are optional. 2. For the COBOL85 compiler, language is HP C, FORTRAN, or Pascal. For the NMCOBOL compiler, language is HP C or TAL. 3. This form must be qualified when no search list is defined and the called routine is not in COBOLEXT or NMCOBEXT. Table 11-3. Resolution of External References (COBOL85 Compiler With Search List Defined) (page 1 of 2) External reference found in ... Form* Current Source File Primary Search List Secondary Search List Tertiary Search List COBOLEXT Target File Created? CALL “P” IN MNEM Search list not used—CALL is qualified CALL “P” Yes Irrelevant Irrelevant Irrelevant Irrelevant Yes No Yes Irrelevant Irrelevant Irrelevant Yes No No Irrelevant Irrelevant Irrelevant Yes, with unresolved externals; warning issued * Bracketed keywords are optional. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -20 Program Compilation CALL and ENTER Statement Processing: Detailed Explanation Table 11-3. Resolution of External References (COBOL85 Compiler With Search List Defined) (page 2 of 2) External reference found in ... Form* Current Source File Primary Search List Secondary Search List Tertiary Search List COBOLEXT Target File Created? ENTER language “R” IN MNEM Search list not used—ENTER is qualified ENTER [language ] “R” Impossible Yes Irrelevant Irrelevant Irrelevant Yes Impossible No Irrelevant Irrelevant Irrelevant No, error reported ENTER [TAL] “R” IN MNEM Search list not used—ENTER is qualified ENTER [TAL] “R” Impossible Yes Irrelevant Irrelevant Irrelevant Yes Impossible No Yes Irrelevant Irrelevant Yes Impossible No No Yes Irrelevant Yes Impossible No No No Yes Yes Impossible No No No No No, error reported * Bracketed keywords are optional. Table 11-4. Resolution of External References (NMCOBOL Compiler) (page 1 of 2) External reference found in ... Form* Current Source File CALL “P” IN MNEM Search list not used—CALL is qualified CALL “P” Yes Irrelevant Irrelevant Irrelevant Yes No Yes Irrelevant Irrelevant Yes No No Irrelevant Irrelevant Yes, with unresolved externals; warning issued ENTER language “R” IN MNEM Primary Search List Tertiary Search List NMCOBEXT, ZCOBSRL, or ZCRESRL Search list not used—ENTER is qualified * Bracketed keywords are optional. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -21 Target File Created? Program Compilation CALL and ENTER Statement Processing: Detailed Explanation Table 11-4. Resolution of External References (NMCOBOL Compiler) (page 2 of 2) External reference found in ... Current Source File Primary Search List Tertiary Search List NMCOBEXT, ZCOBSRL, or ZCRESRL Target File Created? ENTER [language ] “R” Impossible Yes Irrelevant Irrelevant Yes Impossible No Irrelevant Irrelevant No, error reported ENTER [TAL] “R” IN MNEM Search list not used—ENTER is qualified ENTER [TAL] “R” Impossible Yes Irrelevant Irrelevant Yes Impossible No Yes Irrelevant Yes Impossible No No Yes Yes Impossible No No No No, error reported Form* * Bracketed keywords are optional. Presenting Parameters to the Called Program A formal parameter in the called program can have one of two attributes: value or reference. Depending on the description of the actual parameter in the calling program and the description of the formal parameter in the called program, the compiler generates code to convert the value of the actual parameter to match the description of the formal parameter Parameter Explanation (page 1 of 2) VALUE When a formal parameter in the called routine has the VALUE attribute and is numeric, the compiler generates any code necessary to evaluate the actual parameter, convert the value to the expected representation and scaling, and pass the value to the called program. When a formal parameter has the VALUE attribute but is nonnumeric, the compiler generates code to pass the value to the called program. When an actual parameter in the calling program is a literal or an arithmetic expression, the corresponding formal parameter must have the VALUE attribute. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -22 Program Compilation CALL and ENTER Statement Processing: Detailed Explanation Parameter Explanation (page 2 of 2) REFERENCE When a formal parameter has the REFERENCE attribute, the actual parameter supplies access to an object in the calling program. When an actual parameter is an identifier, the compiler generates code to pass the address of the associated data item to the called program. In this case, the calling program and the called program must agree on the interpretation of the data item value. When an actual parameter is a file name, the compiler generates code to pass the address of the file control block. Use this option only where specified for a program supplied by HP. OMITTED When the parameter in the calling program is specified by the reserved word OMITTED, the compiler generates no code to convert or pass anything. The calling program can use OMITTED only when the called program has the EXTENSIBLE or VARIABLE attribute. The calling program and the called program must agree on which operands can be OMITTED. Delivering the Returned Value When an ENTER statement has a GIVING phrase, the compiler generates code to deliver the value that the program returns to a data item in the calling program. The generated code performs any necessary scaling of the result value, then performs an assignment according to the rules for an elementary move operation. Binding or Linking the Object Code When the compilation source text includes a separately compiled program, and the compiler reports no error against that program, the target file includes the object code for that program. The object code for nested programs is inseparable from the code for their outermost separately compiled program. When a separately compiled HP COBOL program or a non-COBOL program is available in object form, and the compiler locates it using a file-mnemonic or primary search list, the target file includes the object code for that program. When the COBOL85 compiler finds a program in the secondary or tertiary search list, or in the COBOLEXT file on the same volume and subvolume as the compiler, the compiler validates parameters, but does not bind the object code into the target file. When the NMCOBOL compiler finds a program in the ZCOBSRL, ZCRESRL, or NMCOBEXT file, the compiler validates parameters, but does not bind the object code into the target file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -23 Program Compilation #RECEIVE Blocks #RECEIVE Blocks When BINSERV or the linker creates a run unit for the CRE, it compares the #RECEIVE blocks of all the programs and determines which argument values are to be used whenever another HP COBOL object file or a FORTRAN program opens $RECEIVE. Table 11-5. How Final Values of #RECEIVE Arguments Are Chosen #RECEIVE Argument Final Value TABLE OCCURS Maximum value specified by a TABLE OCCURS argument in any #RECEIVE block SYNCDEPTH Maximum value specified by a SYNCDEPTH argument in any #RECEIVE block REPLY CONTAINS Maximum value specified by a REPLY CONTAINS argument in any #RECEIVE block REPORT Logical OR QUEUE DEPTH Maximum value specified by a QUEUE DEPTH argument in any #RECEIVE block* * HP COBOL does not have a QUEUE DEPTH argument, so the value is assumed to be 1. If FORTRAN specifies a larger value, the larger value is used. The first HP COBOL external file or FORTRAN program to open $RECEIVE determines the values of the #RECEIVE arguments. Subsequent opens of $RECEIVE fail if they specify incompatible values. #RECEIVE Argument Subsequent value is incompatible with first value if … TABLE OCCURS subsequent value > first value SYNCDEPTH subsequent value > first value REPLY CONTAINS subsequent value > first value REPORT subsequent value <> first value QUEUE DEPTH first value = 1 and subsequent value <>1 or first value > 1 and subsequent value <= 1 or subsequent value > first value HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -24 Program Compilation Compiler Output If an internal file opens $RECEIVE, the values of the #RECEIVE arguments depend on whether the program that describes the internal file has a RECEIVE-CONTROL paragraph. If so, the #RECEIVE block associated with the program’s RECEIVECONTROL paragraph is used as the internal file’s #RECEIVE block (even in a TNS program whose RECEIVE-CONTROL paragraph is EXTERNAL). If the program does not have a RECEIVE-CONTROL paragraph, the #RECEIVE arguments have these default values: #RECEIVE Argument Default Value TABLE OCCURS 1 SYNCDEPTH 1 REPLY CONTAINS 0 REPORT None QUEUE DEPTH 1 If an external file opens $RECEIVE, its #RECEIVE block is the one associated with the run unit, if one exists; otherwise, the #RECEIVE arguments have the default values. When sharing $RECEIVE, be aware that: • • • If one opener requests system messages and another does not, the one that does not might get them anyway. The ERROR CODE and MESSAGE SOURCE phrases of the RECEIVECONTROL paragraph are always local to the program unit. They apply to all READ and WRITE requests in that program unit, even if $RECEIVE was opened in another program unit. Opening a file that references $RECEIVE uses the #RECEIVE arguments specified by the program that contains the OPEN statement, even if the file is EXTERNAL. If the file is EXTERNAL, the ERROR CODE and MESSAGE SOURCE clauses of the RECEIVE-CONTROL paragraph in other programs are ignored. Compiler Output The output of a compilation can include a listing (to an existing file or spooler) and an object file, but it always includes compilation statistics and a completion code. You can manipulate the object file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -25 Program Compilation Listing Creation Topics: • • • • • Listing Creation Object File Creation Manipulating Object Files Compilation Statistics Completion Codes Listing Creation The listing is added to the end of the listing (OUT) file. The listing file can be either a disk file or nondisk file (see Starting a Compilation). If it is a disk file, it must exist before you start the compilation. To create a listing file, use the command: FUP CREATE disk-file-name, TYPE E, REC 132[, EXT pages] disk-file-name is a disk file name (see the Guardian Procedure Calls Reference Manual). pages is the number of extended segment pages. TYPE E specifies an entry-sequenced file. REC 132 specifies 132-character records (partial lines are space-filled on the right through column 132). EXT pages is necessary only if disk-file-name exceeds the standard number of allocated segments. For more information, see Source Program Listing. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -26 Program Compilation Object File Creation Object File Creation The object file that the compiler produces is either a linkfile or a loadfile. Topics: • • • COBOL85 Compiler NMCOBOL Compiler Binder Object File Builder COBOL85 Compiler The COBOL85 compiler produces a loadfile if the compilation unit contains exactly one main program (see Main Programs). If the compilation unit contains no main program, the COBOL85 compiler produces a linkfile. All object files that the COBOL85 compiler produces can be input to the BIND utility (see Binder Object File Builder). NMCOBOL Compiler The NMCOBOL compiler produces a loadfile if you specify the directive RUNNABLE. If the compilation unit contains no main program, executing the object file causes it to terminate immediately with an error message. The NMCOBOL compiler produces a linkfile by default (if you do not specify the RUNNABLE directive). Linkfiles that the NMCOBOL compiler produces can be input to the nld or ld utility. Loadfiles that the NMCOBOL compiler produces cannot be input to the nld or ld utility. For information: Topic Document nld utility nld Manual ld utility ld Manual Binder Object File Builder This topic applies only to TNS programs. For similar information on native object files, see the nld Manual. The Binder object file builder is an HP product that lets you create, examine, and combine object files. Binder operates as either of two processes: • • BIND is an independent, interactive, command-driven binding utility program. BINSERV is the Binder server that compilers use to create object files. Object files are composed of code blocks and data blocks. A block is the smallest unit on which Binder operates. Using BINSERV, the COBOL85 compiler translates each program unit into one code block and several data blocks. Each code block and each data block is marked as having been compiled from HP COBOL source. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -27 Program Compilation Manipulating Object Files An object program is the portion of an object file produced from one program unit. An object file contains one or more object programs. Within the object file, each object program maintains its identity, but is discernible only as a family of code blocks and data blocks. Any object file produced by either BIND or BINSERV can serve as object-file input either for BIND during an interactive session or for BINSERV during a COBOL85 compilation. This means that, using BINSERV, the COBOL85 compiler can include object programs from object files created by previous COBOL compilations. To distinguish between the object files that are input to BIND or BINSERV and the final output object file, the final output object file is called the target file. By including object programs from object files in a target file, you can construct collections of blocks in object files that are then used as program libraries. Because the term “library” as applied to object files has a particular meaning for NonStop systems, this manual uses the terms “object file” and “target file” to refer to such collections of object programs. An HP COBOL program unit can also contain ENTER statements that call HP C, HP C++ FORTRAN, Pascal, and TAL routines. BINSERV fetches these from object files created by the HP C, HP C++, FORTRAN, Pascal, and TAL compilers (which also use BINSERV as a Binder server process). Note. In the non-CRE environment, if any object program in an object file is a COBOL program, the main program of that object file must also be a COBOL program. Also, if any object program in an object file was compiled by the COBOL85 compiler, the main program of that object file must also have been compiled by the COBOL85 compiler. In the CRE, if any HP COBOL object program in an object file was compiled with ENV COMMON or ENV LIBRARY, you must compile all HP COBOL object programs in that object file with ENV COMMON or ENV LIBRARY. For more information on Binder, see the Binder Manual. Manipulating Object Files You can use a TNS HP COBOL, TNS HP C, TNS HP C++, FORTRAN, Pascal or TAL object file as input to the BIND utility to create a new target file. Using BIND, you can add, delete, or replace code blocks and data blocks compiled from HP C, HP C++, FORTRAN, Pascal, or TAL source files. For details, see the Binder Manual. You can use a TNS/R HP COBOL, TNS/R HP C, TNS/R HP C++, or pTAL object file as input to the linker to create a new target file. Using the linker, you can add code blocks and data blocks compiled from TNS/R HP COBOL, TNS/R HP C, TNS/R HP C++, or pTAL source files. For details, see the nld Manual or ld Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -28 Program Compilation Compilation Statistics Compilation Statistics Statistics are printed at the end of every compilation: 1. Binder or linker statistics (if an object file was produced) 2. Compiler statistics Topics: • • • Binder Statistics COBOL85 Compiler Statistics NMCOBOL Compiler and Linker Statistics Binder Statistics Example 11-7. Binder Statistics Binder - OBJECT FILE Binder - T9621D05 - (12DEC91) Copyright Tandem Computers Incorporated 1982-1992 Object file \KIT.$VOL1.PROJ3.UPDATE TIMESTAMP 1992-01-16 15:50:34 2 Code pages 6 Primary data words 50 Secondary data words 64 Data pages 0 Resident code pages 0 Extended data pages 56 Top of stack location in words 1 Code segment 0 Binder Warnings 0 Binder Errors SYSTEM \KIT In Table 11-6, all numeric values are in decimal notation. Table 11-6. Meaning of Binder Statistics (page 1 of 2) Statistic Meaning Object file Complete disk file name of the target file created from the compilation Timestamp Date and time of creation of the object file 1. If you request an alphabetic load map listing, the code size appears after the load map for each code segment. The total code size shown for each segment includes the XEP table size. For information about how to use alphabetic load maps, see Load Maps. 2. A TNS word is 2 bytes (16 bits). HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -29 Program Compilation Compilation Statistics Table 11-6. Meaning of Binder Statistics (page 2 of 2) Statistic Meaning Code pages1 Total number of words 2 used for all Procedure Division code in the loadfile, including TAL and FORTRAN routines The code size is itemized regarding procedure entry-point (PEP) table size, procedure code size, the gap at the 32K-word boundary (see COMPACT and NOCOMPACT), and external entry-point (XEP) table size. For each unresolved external reference, Binder reserves code space for one XEP table entry. The total code size shown excludes the XEP table size. Primary data words Number of fixed global storage words used by the loadfile Secondary data words Number of words of secondary global storage used for all Data Division data in the loadfile Data pages Minimum number of virtual memory data pages to be reserved when the program is run Resident code pages Number of pages of resident code Extended data pages Number of pages of extended data area to be used when the program is run Top of stack location in words Location of the top of the stack Code segment(s) Number of code segments a loadfile includes Code area size Number of virtual memory code pages to be reserved when the program is run Binder warnings Number of warning messages Binder issued Binder errors Number of error messages Binder issued 1. If you request an alphabetic load map listing, the code size appears after the load map for each code segment. The total code size shown for each segment includes the XEP table size. For information about how to use alphabetic load maps, see Load Maps. 2. A TNS word is 2 bytes (16 bits). COBOL85 Compiler Statistics Example 11-8. COBOL85 Compiler Statistics COBOL85 - T9257D00 - (12 DEC 91) The object file is executable on an HP System Number of compiler errors = 0 Number of compiler warnings = 0 Maximum symbol table size = 139578 bytes Elapsed time - 00:00:21 HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -30 Program Compilation Compilation Statistics Table 11-7. Meaning of COBOL85 Statistics Messages Message Meaning No object file produced. One of: • • Every separately compiled program in the compilation either contained errors or was subject to the SYNTAX directive. At least one separately compiled program in the compilation contained one or more errors whose nature creates doubt as to the proper disposition of any other source programs in the compilation (for example, errors associated with CALL or CANCEL statements). The object file has no main program. No successfully compiled source program in the compilation qualified as the main program. The object file is executable on an HP system. The object file is executable on an HP system. In Table 11-8, all numeric values are in decimal notation. Table 11-8. Meaning of COBOL85 Statistics Statistic Meaning Number of compiler errors Number of error messages the compiler issued Number of compiler warnings Number of warning messages compiler issued Maximum symbol table size Number of bytes that the compiler needed for its symbol table (rough estimate) For information on how to increase the size available for the symbol table, see PARAM SYMBOL-BLOCKS. Last message on page nn Location of last error or warning message, if there were any If there are other such messages, each includes information on where to find its predecessor. Elapsed Time Amount of real time, to the nearest second, that the compilation took NMCOBOL Compiler and Linker Statistics Example 11-9, NMCOBOL Compiler Statistics, on page 11-32 is the result of a compilation that did not specify the RUNNABLE directive. Example 11-10, NMCOBOL Compiler and Linker Statistics, on page 11-32 is the result of a compilation that specified the RUNNABLE directive. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -31 Program Compilation Compilation Statistics Example 11-9. NMCOBOL Compiler Statistics COBOL - T8107D46 - (27 JUL 01) No failures detected. No errors detected. No warnings reported. No remarks issued. Maximum symbol table size = 6160 bytes Object file: opt2o Compiler driver: \SVLDEV.$SYSTEM.SYSTEM.NMCOBOL COBOL SRL: \SVLDEV.$SYSTEM.SYS00.ZCOBSRL CRE SRL: \SVLDEV.$SYSTEM.SYS00.ZCRESRL NMCOBEXT: \SVLDEV.$SYSTEM.SYSTEM.NMCOBEXT Compiler statistics phase CPU seconds elapsed time file name COBOLFE 0.1 00:00:04 \SVLDEV.$SYSTEM.SYSTEM.COBOLFE UGEN 0.1 00:00:01 \SVLDEV.$SYSTEM.SYSTEM.UGEN AS1 0.1 00:00:01 \SVLDEV.$SYSTEM.SYSTEM.AS1 total 0.3 00:00:07 All processes executed in CPU 03 (NSR-P) Swap volume: \SVLDEV.$SYSTEM Example 11-10. NMCOBOL Compiler and Linker Statistics COBOL - T8107D46 - (27 JUL 01) No failures detected. No errors detected. No warnings reported. No remarks issued. Maximum symbol table size = 6160 bytes NLD - NATIVE MODE LINKER - T6017D44 - 03JUL01 Copyright Compaq Computer Corporation 2000 NLD's command line was: \svldev.$system.system.nld -o opt2o opt2o \SVLDEV.$SYSTEM.SYS00.ZCOBSRL \SVLDEV.$SYSTEM.SYS00.ZCRESRL NLD reported 0 errors. NLD reported 0 warnings. NLD reported 0 informational messages. NLD created this type of object file: \SVLDEV.$COBOL.PTRCOBT.opt2o (ELF, executable) NLD Timestamp: Elapsed Time: 21NOV2003 14:34:32 00:00:01 Object file: opt2o Compiler driver: \SVLDEV.$SYSTEM.SYSTEM.NMCOBOL COBOL SRL: \SVLDEV.$SYSTEM.SYS00.ZCOBSRL CRE SRL: \SVLDEV.$SYSTEM.SYS00.ZCRESRL NMCOBEXT: \SVLDEV.$SYSTEM.SYSTEM.NMCOBEXT Compiler statistics phase CPU seconds elapsed time file name COBOLFE 0.1 00:00:04 \SVLDEV.$SYSTEM.SYSTEM.COBOLFE UGEN 0.1 00:00:01 \SVLDEV.$SYSTEM.SYSTEM.UGEN AS1 0.1 00:00:01 \SVLDEV.$SYSTEM.SYSTEM.AS1 NLD 0.0 00:00:01 \SVLDEV.$SYSTEM.SYSTEM.NLD total 0.3 00:00:07 All processes executed in CPU 03 (NSR-P) Swap volume: \SVLDEV.$SYSTEM HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -32 Program Compilation Completion Codes Completion Codes The compiler reports an appropriate completion code when it terminates execution. An HP COBOL program can set its own completion code at termination by calling either the COBOL85^COMPLETION routine or COBOL_COMPLETION_ routine. Table 11-9. Completion Codes Code Termination Explanation 0 Normal No diagnostic messages were issued. The object file is complete and valid (unless a SYNTAX directive suppressed its creation). 1 Normal At least one compiler or Binder warning occurred. The object file is complete and presumed to be valid (unless a SYNTAX directive suppressed its creation). 2 Normal At least one compiler or Binder error occurred. No object file was created. 3 Abnormal The compiler exhausted one of its internal resources (such as symbol table space) or it was refused some external service (such as access to a file) before it completed its task. No object file was created. 5 Abnormal During internal consistency checking, the compiler discovered a logic error, or else one of the compiler’s server processes reported a failure and was terminated abnormally. No object file was created. 8 Normal At least one compiler or Binder warning occurred. The name specified for the target (object) file could not be used, so another name was chosen. This name is reported in the summary. The object file is complete and presumed to be valid. Running the Compiler This topic explains how to run the compiler, including: • • • • PARAM Commands Predefined SEARCH DEFINEs Starting a Compilation Terminating a Compilation HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -33 Program Compilation PARAM Commands PARAM Commands If you want to use a PARAM command, you must enter it before you give the command to run the compiler. When the compiler terminates execution, it reports an appropriate completion code. Note. PARAM commands for files in a user library are ignored. Table 11-10. PARAM Commands Accepted by Compiler Command Description PARAM SAMECPU* Directs the Guardian operating system to run the COBOL85 compiler and the BINSERV and SYMSERV processes in the same processor. PARAM SWAPVOL Specifies the volume on which the COBOL85 or NMCOBOL compiler and its processes will create temporary files. PARAM SYMBOL-BLOCKS Specifies the number of 256 KB blocks that the compiler needs for its symbol dictionary and, for the COBOL85 compiler, the number of 2 KB blocks the compiler needs for a local label table. The number of lines allowed for each SQL/MP statement is 500 times the number specified by PARAM SYMBOLBLOCKS. * COBOL85 compiler only PARAM SAMECPU The PARAM SAMECPU command causes the COBOL85, BINSERV, and SYMSERV processes to run in the same processor, which improves interprocess communication. This command does not affect the NMCOBOL compiler, whose subordinate processes always execute in the same processor as the compiler does. PARAM SAMECPU dummy-value VST417.vsd dummy-value is a nonzero value. It does not specify the processor in which the processes are to run; the CPU run option controls that. Ordinarily, the COBOL85 and BINSERV processes run in one processor and the SYMSERV process runs in the processor having the next higher number (modulo the number of processors in the system); for example: PARAM SAMECPU 3 HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -34 Program Compilation PARAM Commands PARAM SWAPVOL The PARAM SWAPVOL command specifies the volume on which the compiler and its processes will create temporary files (if possible). It does not determine where the operating system creates the compiler’s own swap file—the Kernel-Managed Swap Facility (KMSF) does that. For more information, see the Kernel-Managed Swap Facility (KMSF) Manual. PARAM SWAPVOL $ ns volume VST418.vsd $volume is a dollar sign ($) immediately followed by one to seven alphanumeric characters. The first alphanumeric character must be alphabetic. The $volume is the name of the volume on which the temporary files are to be created. The $volume must exist on the system on which the compiler resides. If the compiler cannot create its first temporary file on the specified volume, compilation proceeds with temporary files created as though no PARAM SWAPVOL command were active. PARAM SYMBOL-BLOCKS The PARAM SYMBOL-BLOCKS command specifies how much space the compiler allocates for its symbol dictionary, embedded SQL/MP statements, and for the COBOL85 compiler, its local label table. The PARAM SYMBOL-BLOCKS command specifies how much space the compiler allocates for its symbol dictionary, local label table, and embedded SQL/MP or SQL/MX statements. PARAM SYMBOL-BLOCKS count VST419.vsd count is an integer in the range 1 through 14 (for the COBOL85 compiler) or 1 through 25 (for the NMCOBOL compiler), which affects space allocation. The default value of count is 2 for the COBOL85 compiler and 3 for the NMCOBOL compiler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -35 Program Compilation Predefined SEARCH DEFINEs Table 11-11. How the PARAM SYMBOL-BLOCKS Command Affects Space Allocation Space Allocated for Item Item When PARAM SYMBOL-BLOCKS command is specified ... Symbol dictionary count 256-KB blocks Two 256-KB blocks for the COBOL85 compiler, three 256-KB blocks for the NMCOBOL compiler Local label table (COBOL85 compiler only) count 2-KB blocks Two 2-KB blocks Embedded SQL/MP statements count times 500 lines times number of embedded SQL/MP statements, plus extra space for REPLACE statements 500 lines of SQL/MP text per statement Default If the default value for count produces a failure in compilation, increase it by one. If that still is not enough, increase it by one more, and so on. Be aware that high count values cause the compilation to take longer to start and to use more disk space. If the summary listing at the end of a compilation indicates that the maximum symbol table size is less than 256 KB, you might be able to reduce the system resources required for later compilations by specifying PARAM SYMBOL-BLOCKS 1. For the COBOL85 compiler, if you allow count to default to 2, your program can have a maximum of approximately 1000 procedure names (paragraph names and section names). Changing count changes this limit. Predefined SEARCH DEFINEs The compiler recognizes two predefined DEFINEs with CLASS attribute SEARCH: • • =_SOURCE_SEARCH =_OBJECT_SEARCH These allow you to specify one or more subvolumes for the compiler to search for unqualified source text files and object files, respectively. (“Unqualified” means that the file name does not contain a volume and subvolume.) If you use these predefined DEFINEs, you do not need to specify DEFINEs in the compiler command or in the source text. To add a predefined SEARCH DEFINE, use the ADD DEFINE command. For example: ADD DEFINE =_SOURCE_SEARCH, CLASS SEARCH, SUBVOL0 (=_DEFAULTS,$VOL1.SUB2,$VOL1.SUB3) In this example, the compiler is to search the default subvolume first, then $VOL1.SUB2, and finally $VOL1.SUB3. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -36 Program Compilation Predefined SEARCH DEFINEs =_SOURCE_SEARCH =_SOURCE_SEARCH tells the compiler where to search for unqualified source text files specified by: • • • COPY statements SOURCE directives The copy-library parameter of the compilation command The =_SOURCE_SEARCH DEFINE does not affect compiler searches in these cases: • • When the source text file name is qualified When the program uses the default COPY library, COPYLIB, for COPY text =_OBJECT_SEARCH =_OBJECT_SEARCH tells the compiler where to search for unqualified object files specified by: • • • • • • SPECIAL-NAMES paragraph CALL statements ENTER statements CONSULT directives LIBRARY directives SEARCH directives The =_OBJECT_SEARCH DEFINE does not affect: • • The compiler search when the object file name is qualified The file COBOLEXT (for the COBOL85 compiler) or NMCOBEXT (for the NMCOBOL compiler), which is assumed to be on the same subvolume as the compiler HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -37 Program Compilation Starting a Compilation Starting a Compilation This section applies to the Guardian environment. To compile an HP COBOL program in the OSS environment, see Section 19, Using HP COBOL in the OSS Environment. To run the COBOL85 compiler, use this compiler command: COBOL85 / IN / source-file , OUT list-file , other-option target-name , ( obj-1 , copy-library ; compiler-directive obj-n ) VST256.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -38 Program Compilation Starting a Compilation To run the NMCOBOL compiler, use this compiler command: NMCOBOL / IN source-file / , OUT list-file , other-option target-name , copy-library ; compiler-directive VST728.vsd source-file file-name-1 define-name VST257.vsd is a file containing HP COBOL statements, comment lines, and compiler directives. It must be a disk file, terminal, magnetic tape unit, or process. The compiler reads source-file as 132-byte records. The default is the current command interpreter IN file (usually the home terminal). For the NMCOBOL compiler, source-file must be an EDIT file. file-name-1 is a disk file name (if source-file is a disk file) or nondisk file name (if source-file is a terminal, magnetic tape unit, or process). For syntax, see the Guardian Procedure Calls Reference Manual. define-name is the name of a DEFINE established in the current run-time environment. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -39 Program Compilation Starting a Compilation list-file file-name-2 define-name VST259.vsd is the destination to which the compiler directs its output. It must be a disk file, terminal, magnetic tape unit, process, line printer, or spooler collector (possibly qualified with a location name). It must already exist and meet the criteria in Listing Creation. If list-file is unstructured, each record is 132 characters (partial lines are space-filled on the right). For the COBOL85 compiler, if OUT is present but list-file is omitted, no listing is produced. If both OUT and list-file are omitted, the listing is directed to the command interpreter OUT file (usually the home terminal). Note. The NMCOBOL compiler listing has a significantly different format from the COBOL85 compiler listing. The primary differences are: • • • Every diagnostic message appears with the source line that caused it. Mnemonic code, if requested, immediately follows the source code from which it was generated. There is no cross-reference listing. file-name-2 is a disk file name (if list-file is a disk file) or nondisk file name (if listfile is a terminal, magnetic tape unit, process, line printer, or spooler collector). For syntax, see the Guardian Procedure Calls Reference Manual. define-name is the name of a DEFINE established in the current run-time environment. other-option is any other command interpreter RUN option (see the description of the RUN command in the TACL Reference Manual). HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -40 Program Compilation Starting a Compilation target-name file-name-4 define-name VST261.vsd is the name of a disk file on which the single target object file is to be produced. This name is used only if all of these are true: • • • The compiler is instructed to produce a target file. This means that the SYNTAX directive is not specified. The compilation and binding are successful. The source file contains only one main program. If it contains more than one, you must specify an object file for each of them (target-name-1 through target-name-n ). The default target-name is: \default-system.$default-volume.default.subvolume.RUNUNIT file-name-3 is a disk or nondisk file name. For syntax, see the Guardian Procedure Calls Reference Manual. define-name is the name of a DEFINE established in the current run-time environment. obj-1 ... obj-n file-name-4 define-name VST261.vsd is a list of names of disk files on which the multiple target object files are to be produced. Each has the same syntax as target-name. These restrictions apply: • • • You must specify at least as many object file names as there are main programs delivered to the compiler. You can specify more, but not fewer. If you specify more, unused ones are ignored. The source-file must be an EDIT file. The list-file cannot be a magnetic tape file. list-file is opened and closed for each separately compiled program. If list-file is a spooler, one job exists for the compiler command and one for each separately compiled program in the source-file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -41 Program Compilation • • • • Starting a Compilation Each directive that applies to more than one separately compiled program in the source-file (for example, ICODE or NOBLANK) must be specified as a compiler-directive in the compiler command. Each separately compiled program in the source-file must end with an END PROGRAM statement or an ENDUNIT compiler directive. In the source-file, compiler directives must be contained in separately compiled programs. They cannot appear before, between, or after them. A COPY or SOURCE statement cannot bring in the beginning or end of a separately compiled program. file-name-3 is a disk or nondisk file name. For syntax, see the Guardian Procedure Calls Reference Manual. The default file-id of file-name-3 is COPYLIB. define-name is the name of a DEFINE established in the current run-time environment. copy-library file-name-4 define-name VST261.vsd is the name of a COPY library, a disk file in EDIT format, which is to be the default COPY library (for any COPY statement in the source program that does not specify a library from which to copy). file-name-4 is a disk file name. For syntax, see the Guardian Procedure Calls Reference Manual. The default file-id of file-name-3 is COPYLIB. define-name is the name of a DEFINE established in the current run-time environment. compiler-directive is any directive described in Compiler Directives. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -42 Program Compilation Starting a Compilation Usage Considerations: • Compiler on D-Series System and Other Files on C-Series System If the COBOL85 compiler is running on a D-series system and any other file that the program uses (such as the source-file, a COPY or SOURCE library, a search or consult file, the OUT file, the home terminal, or the target file) is on a C-series system, then compiling with the HIGHPIN directive causes a compilation error. • COBOL85 Compiler’s Construction of Target File The COBOL85 compiler (through BINSERV) constructs the target file in a temporary file of its own creation. If the compilation is successful, BINSERV purges any existing copy of the named file and then renames the temporary file with the chosen name. If the old copy was in use when BINSERV tried this, that old copy is renamed, and the temporary file is renamed with the chosen name. If a file exists with the same name as target-name (or RUNUNIT, if applicable), the compilation tries to purge the old file. If it cannot purge the old file, its behavior depends on whether the purge fails because the old object file is then executing (Guardian file-system error 12). ° If the old object is not executing, the compilation tries to rename the temporary file OBJECT. If that renaming operation fails (because there already is a file named OBJECT), the compilation creates a special name of the form ZZBInnnn, where nnnn is a random number. ° If the old object is executing, the compilation renames the old object file to the special name of the form ZZBInnnn and renames the temporary file with the value of target-name. Examples of Commands That Run the Compilers Each of these commands initiates compilation of the program contained in MYSRC (on the default system, volume, and subvolume), directing the listing to $SPOOL (a spooler collector): COBOL85 /IN MYSRC,OUT $SPOOL,PRI 140/MYPROG;ICODE;LMAP * NMCOBOL /IN MYSRC,OUT $SPOOL,PRI 140/MYPROG;INNERLIST The compiler is to run at a priority of 140. The name of the target file, if the compilation succeeds, is to be MYPROG on the default system, volume, and subvolume. Two directives specify that a listing of the mnemonic version of the generated code and a complete set of load-map listings are to be produced. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -43 Program Compilation Terminating a Compilation The next command initiates compilation of the program contained in file COBOLPRG on system \MM, volume $DEV, subvolume PYRL and directs that the listing output be discarded: COBOL85 /IN \MM.$DEV.PYRL.COBOLPRG,OUT/; SETTOG 3 NMCOBOL /IN \MM.$DEV.PYRL.COBOLPRG,OUT/; SETTOG 3 If the compilation succeeds, the loadfile is to be named RUNUNIT. The directive sets a compilation toggle that presumably governs the inclusion or exclusion of certain portions of the source text. Terminating a Compilation There are two ways to terminate a compilation before normal completion: • • Press Break and type STOP. Press Break and type: STATUS *, TERM Find the processor (cpu ) and process number (process ) for the compiler. Type: STOP cpu,process With either method, the supporting processes stop when the compiler stops. Note. If you expect to have multiple compilations active at one time, give each COBOL85 or NMCOBOL process a different name with the command interpreter NAME parameter. Then you can stop the named compilation process of your choice using the second method. For possible values of the system completion code upon the termination of a compilation, see Completion Codes. Compiler Directives Compiler directives are used to specify the source format, to control listing features, to control selective compilation of portions of the source code, and to request compilation options. Topics: • • • Where Compiler Directives Are Allowed Categories of Compiler Directives One for each compiler directive, listed alphabetically, beginning with ANSI HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -44 Program Compilation Where Compiler Directives Are Allowed Where Compiler Directives Are Allowed In general, one or more directives can be entered in the directive field of the TACL command to run the compiler (see Starting a Compilation) or can be included in the source text on lines beginning with a question mark (?) in the indicator area. Restrictions on these general rules are: • • • • Each of the directives ENDUNIT, IF, IFNOT, and ENDIF must be either on a directive line of its own or be the last of a sequence of directives. The SECTION directive must always be on a line of its own. The NMCOBOL compiler accepts the SQL directive on the compiler command line, but not in the source program. Some directives are recognized by only one compiler (COBOL85 or NMCOBOL). For details, see the topics on individual directives. Directives in the source text override directives on the command line. The general form of compiler directives is: On the compiler command line: directive ; , directive VST263.vsd In the program source text: ? directive ; , directive VST264.vsd ? is a source text format indicator (like the asterisk and the slash) and is not part of the compiler directive. The question mark must be in the indicator area (column 1 for Tandem format and column 1 or 7 for ANSI format). HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -45 Program Compilation Where Compiler Directives Are Allowed directive is one of the directives listed in this section. With these exceptions, compiler directive lines can appear at any point in the source text, including those portions that a COPY statement retrieves from a source library file. • Compiler directive lines cannot occur between the elements of a multiline COPY statement. The syntax of the COPY statement, without the REPLACING phrase, is: COPY OF text-name . library-name IN VST265.vsd If, for example, the word COPY is on one source line and text-name is on a subsequent source line, no compiler directive lines can occur on any intervening source line. • • • These directives have restrictions on their location within the source text: ° ° ° ° ° ° ° ° ° ° ° COMPILE ENV FLOAT LD MAIN NLD NONSTOP OPTIMIZE SYMBOLS SYNTAX UL The COLUMNS directive can appear in a COPY library, but only once, before the first SECTION directive. The SQL directive cannot appear in a source program that is to be compiled with the NMCOBOL compiler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -46 Program Compilation Categories of Compiler Directives Categories of Compiler Directives Compiler directives fall into these categories: • • • • • • • Table 11-12, Source Text Manipulation Directives, on page 11-47 Table 11-13, Input Format Control Directives, on page 11-47 Table 11-14, Listing Control Directives, on page 11-48 Table 11-15, Code-Generation Control Directives, on page 11-49 Table 11-16, Resolution and Binding Control Directives, on page 11-51 Table 11-17, Miscellaneous Control Directives, on page 11-51 Table 11-18, ENDUNIT Directive, on page 11-52 Table 11-12. Source Text Manipulation Directives Directive(s) Default Action Marks beginning of portion of text in an EDIT file, which compiler reads in response to COPY statements and SOURCE directives SECTION SHOWFILE and NOSHOWFILE NOSHOWFILE Switches identification of source file in compiler listing on or off SOURCE* Reads an entire EDIT file, or one or more sections of an EDIT file SETTOG* Turns toggles on RESETTOG* Turns toggles off IF and IFNOT* Enables or suppresses compilation of subsequent lines if a specified toggle has been set; disables it otherwise ENDIF* Marks end of toggle block * Must be the last directive on its line. Table 11-13. Input Format Control Directives Directive Default Action Specifies logical length of source lines when TANDEM directive is present COLUMNS TANDEM TANDEM Specifies Tandem source format ANSI TANDEM Specifies ANSI source format HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -47 Program Compilation Categories of Compiler Directives Table 11-14. Listing Control Directives Directive(s) Default Action CODE and NOCODE1 NOCODE Enables or suppresses octal code listing CROSSREF and NOCROSSREF1 NOCROSSREF Enables or suppresses cross-reference listing of identifiers DIAGNOSE-74 and NODIAGNOSE-74 NODIAGNOSE-74 Enables or suppresses warnings about statements that might behave differently for HP COBOL and COBOL 74 DIAGNOSE-85 and NODIAGNOSE-852 NODIAGNOSE-85 Enables or suppresses warnings about source constructs that might behave differently for COBOL85 compiler and NMCOBOL compiler DIAGNOSEALL and NODIAGNOSEALL NODIAGNOSEALL Enables or suppresses warnings for multiple references to undefined identifiers (instead of the first one only) FIPS and NOFIPS NOFIPS Enables or suppresses identification of statements as required by the Federal Information Processing Standard (FIPS) FMAP2 Enables listing of source file map with fully qualified name and timestamp for IN file and every SOURCE and COPY file HEADING Specifies page heading text. IICODE and NOICODE1 NOICODE Enables or suppresses mnemonic code listing after source program listing INNERLIST and NOINNERLIST2 NOINNERLIST Enables or suppresses mnemonic code listing after each source program statement Specifies lines per page LINES LIST and NOLIST NOLIST Enables or suppresses compiler listing LMAP and NOLMAP1 LMAP Enables or suppresses load map of object file MAP and NOMAP NOMAP Enables or suppresses symbol map SHOWCOPY and NOSHOWCOPY2 SHOWCOPY Enables or suppresses listing of COPY statements as comments Enables or suppresses flags on extensions or obsolete elements SUBSET SUPPRESS and NOSUPPRESS NOSUPPRESS Suppresses or enables all but leader, diagnostics, and trailer text in compiler listing WARN and NOWARN WARN Enables or suppresses warnings 1. The NMCOBOL compiler ignores and issues warnings for these directives. 2. The COBOL85 compiler reports errors for these directives. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -48 Program Compilation Categories of Compiler Directives Table 11-15. Code-Generation Control Directives (page 1 of 2) Directive(s) Default Action BLANK and NOBLANK2 BLANK for COBOL85 compiler, NOBLANK for NMCOBOL compiler Enables or suppresses default initialization of data-items whose declarations lack VALUE clauses CALL-SHARED3 NON-SHARED Generates shared code [positionindependent code (PIC)] (see also SHARED) CANCEL and NOCANCEL CANCEL Controls whether code is generated to initialize data for a program that does not have the INITIAL attribute Controls the level of run-time checking included in the loadfile CHECK COMPACT and NOCOMPACT1 COMPACT Enables or suppresses code compaction by procedure relocation COMPILE COMPILE Generates object code (compare to SYNTAX) FLOAT and NOFLOAT1 FLOAT Generates code for either floating-point or decimal arithmetic INSPECT and NOINSPECT INSPECT Selects the debugger to be used if the program is initiated with RUND or if the DEBUG command is issued against it LARGEDATA2 Allocates specified data items in extended memory without requiring that their definitions be moved to the Extended-Storage Section (for COBOL85 compiler) or large data areas (for NMCOBOL compiler) LESS-CODE1 Controls generation of object code that initializes the Extended-Storage Section NON-SHARED NON-SHARED Generates nonshared code (nonPIC) (compare to CALL-SHARED and SHARED) 1. The NMCOBOL compiler ignores and issues warnings for these directives. 2. The COBOL85 and NMCOBOL compilers handle these directives differently. 3. The COBOL85 compiler reports an error for this directive. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -49 Program Compilation Categories of Compiler Directives Table 11-15. Code-Generation Control Directives (page 2 of 2) Directive(s) Default OPTIMIZE2 Action Specifies the level of object code optimization the compiler must provide PORT and NOPORT NOPORT RUNNABLE Causes BINARY/COMPUTATIONAL items to be byte-aligned and allows the CALL statement to behave as it does in X/Open and XPG4 Causes the NMCOBOL compiler to produce a loadfile SAVEABEND and NOSAVEABEND NOSAVEABEND Specifies that if the program terminates abnormally, its state is saved for future examination with the selected debugger SHARED NON-SHARED Generates shared code (PIC) for a DLL (see also CALL-SHARED) SYMBOLS and NOSYMBOLS NOSYMBOLS Controls whether a symbol table is included in the target file SYNTAX COMPILE Suppresses generation of object code TRAP2 and NOTRAP21 TRAP2 Suppresses all arithmetic overflow trapping TRAP2-74 and NOTRAP2-741 TRAP2-74 Suppresses arithmetic overflow trapping in called COBOL 74 programs only UL3 Specifies that the resulting object code will be in a user library 1. The NMCOBOL compiler ignores and issues warnings for these directives. 2. The COBOL85 and NMCOBOL compilers handle these directives differently. 3. The COBOL85 compiler reports an error for this directive. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -50 Program Compilation Categories of Compiler Directives Table 11-16. Resolution and Binding Control Directives Directive(s) Default Action CONSULT and NOCONSULT2 NOCONSULT1 Specifies a list of object files from which the compilation can resolve unqualified external references, but not bind in the specified routines LD3 Passes one or more linker options to the ld utility LIBRARY1 Specifies a user library file from which the compilation can resolve unqualified external references, but not bind in the specified routines NLD Passes one or more linker options to the nld utility SEARCH and NOSEARCH2 NOSEARCH1 Specifies a list of object files from which the compilation can resolve unqualified external references and bind or link in the specified routines 1. The NMCOBOL compiler ignores and issues a warning for this directive. 2. The COBOL85 and NMCOBOL compilers handle the CONSULT and SEARCH directives differently. 3. The COBOL85 compiler does not accept this directive. Table 11-17. Miscellaneous Control Directives (page 1 of 2) Directive(s) Default Action ENV2 Selects the environment in which the program runs ERRORFILE Specifies a file that is to contain information about any compilation errors or warnings (it can be used with the FIXERRS TACL macro) ERRORS Specifies maximum number of errors allowed HEAP3 Specifies heap space size in the CRE in the Guardian environment HIGHPIN 3 Sets the HIGHPIN flag in a D-series object file, allowing it to run at a high PIN (a process identification number greater than 255) 1. These directives are not available in the OSS environment. 2. The NMCOBOL compiler accepts this directive with the COMMON option (the default for this compiler), reports an error for the OLD option, and issues a warning for the LIBRARY option. 3. The NMCOBOL compiler ignores and issues warnings for these directives. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -51 Program Compilation Categories of Compiler Directives Table 11-17. Miscellaneous Control Directives (page 2 of 2) Directive(s) Default Action HIGHREQUESTERS3 Allows the program to run as a server that communicates with requesters running at high PINs (greater than 255) MAIN Specifies the main program in an input stream NONSTOP1 Specifies program is to run as a process pair PERFORM-TRACE Provides additional information if run-time error 148 occurs. RUNNAMED Specifies that the run unit is to be run as a named process SAVE1 Specifies which initialization message information is saved SQL and NOSQL NOSQL3 Tells the compiler to expect SQL/MP statements in the compilation unit SQLMEM3 Tells the compiler whether to declare SQL/MP data structures in the WorkingStorage Section (user data segment) or the Extended-Storage Section (extended data segment) SUBTYPE1 Specifies that the program runs as a process with the designated subtype number 1. These directives are not available in the OSS environment. 2. The NMCOBOL compiler accepts this directive with the COMMON option (the default for this compiler), reports an error for the OLD option, and issues a warning for the LIBRARY option. 3. The NMCOBOL compiler ignores and issues warnings for these directives. Table 11-18. ENDUNIT Directive Directive Action ENDUNIT Marks the end of the Procedure Division in a source file that contains multiple, separately compiled COBOL programs.* * This directive must be the last or the only directive on its line. If any other directive appears on the line after it, the compiler reports an error and ignores the additional directives. Note. In the list of directives, “Default:” identifies the default for the compiler directive itself, not for its optional parameter(s). This default applies if a program does not contain the compiler directive at all. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -52 Program Compilation ANSI ANSI ANSI TANDEM VST266.vsd ANSI specifies that subsequent source text is in ANSI reference format, which is described in Section 16, ANSI Reference Format. TANDEM specifies that subsequent source text is in Tandem reference format, which is described in Reference Format for Source Program Lines. Default: TANDEM Placement: Anywhere Scope: ANSI or TANDEM within a section of text obtained from a copy library or source library is effective only for the length of that text section. When the compiler reverts to the source file where it found the COPY verb or SOURCE directive, the previously active reference format applies. Dependencies: None References: TANDEM HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -53 Program Compilation BLANK and NOBLANK BLANK and NOBLANK BLANK NOBLANK VST267.vsd BLANK adds an implicit VALUE SPACES clause to the description of: • • Every data item in the Working-Storage Section and Extended-Storage Section, except those to which an explicit VALUE clause or an EXTERNAL clause applies Every data item in the File Section, except those to which an EXTERNAL clause applies BLANK increases the size of the object file and can increase execution time. NOBLANK prevents the addition of implicit VALUE SPACES clauses. Default: BLANK for the COBOL85 compiler NOBLANK for the NMCOBOL compiler Placement: Anywhere Scope: The last BLANK or NOBLANK in the program is applies. Dependencies: None Program units compiled with BLANK (or for which BLANK is the default) include code that performs implicit and explicit initializations. Program units compiled with NOBLANK (or for which NOBLANK is the default) do not provide this automatic initialization, and any data item without a VALUE clause has an undefined initial value. NOBLANK is recommended for initial programs and programs that declare very large data items that do not have initial values assigned, because it saves significant amounts of compilation time, object program storage space on disk, and run-time initialization time. If you must initialize very large data items to spaces, use VALUE clauses, INITIALIZE statements, or MOVE statements of the form MOVE SPACES TO X VALUE clauses are recommended. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -54 Program Compilation CALL-SHARED CALL-SHARED Note. The COBOL85 compiler does not recognize this directive. CALL-SHARED NON-SHARED SHARED VST802.vsd CALL-SHARED generates shared code (PIC). NON-SHARED generates nonshared code (non-PIC). SHARED generates shared code (PIC) for a DLL. Note. You cannot link PIC and non-PIC object files into a single object file. Default: NON-SHARED Placement: Anywhere Scope: The last CALL-SHARED, NON-SHARED, or SHARED in the compilation unit applies to the entire compilation unit. Dependencies: References: • • • • • • If RUNNABLE is active, CALL-SHARED uses the linker to create a PIC executable object file; otherwise, CALL-SHARED creates a PIC linkfile. Do not use with UL. NON-SHARED SHARED RUNNABLE UL HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -55 Program Compilation CANCEL and NOCANCEL CANCEL and NOCANCEL CANCEL NOCANCEL VST383.vsd CANCEL generates code that initializes the program the first time the program is called after being canceled by a CANCEL statement. NOCANCEL prevents the generation of code that initializes the program the first time the program is called after being canceled by a CANCEL statement. Default: CANCEL Placement: Anywhere Scope: Applies to the program that contains it. CANCEL and NOCANCEL do not apply to initial programs, which are initialized every time they are called. Dependencies: None If a program is not an initial program and is never referenced by a CANCEL statement, specify NOCANCEL to reduce the size of the program’s object code. Do not specify NOCANCEL for a program that is referenced by a CANCEL statement. If you do, the program might not execute in the manner expected. CHECK CHECK controls the level of run-time checking that a program performs. CHECK check-level VST268.vsd check-level is an integer in the range 0 through 15. For the meanings of the different values of check-level, see Table 11-19. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -56 Program Compilation CHECK Default: CHECK 1 Placement: Anywhere Scope: In each separately compiled program, the last CHECK in the program unit determines the check level for the code block being produced. Dependencies: None Table 11-19. CHECK Levels check-level What is Checked Comments 0 Nothing CHECK 0 results in the fastest execution time. 1 (default) Nothing CHECK 1 might have a different meaning in future versions of HP COBOL. For the fastest execution (and no subscript checking) in current and future versions of HP COBOL, specify CHECK 0. 2 Validity of subscripts and indexes* 3 Validity of subscripts, indexes, and reference modifiers* Specifies the maximum level of checking that HP COBOL currently provides. 4-15 Validity of subscripts, indexes, and reference modifiers* 4-15 might have different meanings in future versions of HP COBOL. For the maximum level of checking that HP COBOL currently provides, specify CHECK 3. For maximal checking, specify CHECK 15 (which could increase the program’s run-time overhead in future versions of HP COBOL if additional checking levels are implemented). * The compiler generates extra code in order to check the validity of these items. At run time, if the subscript or reference modifier used in a statement is out of range, an error is reported, and the execution terminates. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -57 Program Compilation CODE and NOCODE CODE and NOCODE Note. The NMCOBOL compiler issues warnings for these directives. CODE NOCODE VST269.vsd CODE lists an octal image of the compiled code following successful compilation of a program unit. The octal image appears after the symbol table listing produced by MAP (if any) and before the mnemonic code produced by ICODE (if any). NOCODE suppresses the octal image of the compiled code. Default: NOCODE Placement: Anywhere Scope: In each separately compiled program, the last CODE or NOCODE in the program unit applies to the entire program unit. Dependencies: CODE works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -58 Program Compilation COLUMNS COLUMNS COLUMNS causes the compiler to ignore any text beyond a certain column in subsequent input records. COLUMNS applies only to text being read under Tandem reference format. Text being read under ANSI reference format ignores any text beyond column 72. COLUMNS length VST270.vsd length is an integer whose value is at least 12. Any value greater than 132 is considered to equal 132. Default: COLUMNS 132 • Placement: • • On a directive line, COLUMNS must begin with a question mark (?) in column 1, regardless of any active ANSI. In a COPY library or a source library, COLUMNS must be the only directive on its line and must precede all SECTION directives in that library. The COBOL85 compiler accepts at most one COLUMNS for each source file (that is, one for the primary source file and one for each COPY library or source library called by the primary source file). Scope: When the compiler shifts from reading the primary source file to reading a COPY library (in compliance with a COPY statement) or a source library (in compliance with a SOURCE directive), it saves the current (default or specified) logical length for source lines. That length applies to all source lines in the COPY library or source library, unless a COLUMNS directive occurs in the COPY library file (as mentioned in the preceding item). In this case, the compiler reverts to the saved logical length when it resumes reading text from the primary source file. Dependencies: COLUMNS works only if TANDEM is active. References: • • • ANSI SOURCE TANDEM HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -59 Program Compilation COMPACT and NOCOMPACT COMPACT and NOCOMPACT Note. The NMCOBOL compiler, which does not use BINSERV, issues warnings for these directives. COMPACT NOCOMPACT VST271.vsd COMPACT causes BINSERV to attempt to compact the code space of the target file. NOCOMPACT prevents BINSERV from compacting the code space of the target file. Default: COMPACT Placement: Anywhere Scope: The last COMPACT or NOCOMPACT in the compilation unit applies. Dependencies: None Compacting the target file also decreases the space required by the executing program. Memory consists of a data area and a code area. COMPACT affects only the code area. The object code HP compilers produce is composed of blocks. Code-space blocks (code blocks and read-only arrays) can never span from one code segment to another, so they can never exceed a size of 128 KB. Object code for an HP COBOL routine can straddle a 64 KB boundary only when a block exceeds 64 KB. A code-space block can be as large as 126,998 bytes, leaving 1002 bytes for the procedure entry point (PEP) table and the external entry point (XEP) table. Object code for routines written in other languages cannot straddle the 64 KB boundary in a 128 KB code segment. If you specify NOCOMPACT, BINSERV allocates code-space blocks strictly in the order in which they are presented by the compiler. This can leave gaps between the 64 KB boundary and the last code-space block below it, and between the 128 KB boundary and the last code-space block below it. If you specify only COMPACT, or omit both COMPACT and NOCOMPACT, BINSERV checks each succeeding code-space block to determine whether it will fit into either current gap. When a code-space block that fits in a gap is found, BINSERV allocates it in the gap, thereby compressing both the target file and the object program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -60 Program Compilation COMPILE Suppose the compiler presents these code-space blocks to BINSERV in this order: Program A Program B Program C Program D Program E 20 KB 24 KB 32 KB 8 KB 10 KB Because no block exceeds 64 KB, none can span the 64 KB boundary. When they are bound with NOCOMPACT active, they occupy 116 KB. Each nonspace character below represents 2 KB: AAAAAAAAAABBBBBBBBBBBB---------CCCCCCCCCCCCCCCCDDDDEEEEE-^10 ^22 ^32 ^48 ^52 ^58 When the blocks are bound with COMPACT active, they fit into 48K words: AAAAAAAAAABBBBBBBBBBBBDDDDEEEEE-CCCCCCCCCCCCCCCC^10 ^22 ^26 ^32 ^48 COMPILE COMPILE SYNTAX VST272.vsd COMPILE compiles the program unit and includes its code and data blocks in the target file being created. SYNTAX checks the syntax of the source text. No target file is produced. Default: COMPILE Placement: Outside the boundaries of a separately compiled program; that is, not between the Identification Division header of a separately compiled program and its end, which is marked by one of: • • • The corresponding END PROGRAM statement ENDUNIT The end of the source file Scope: The last COMPILE or SYNTAX in the compilation unit applies to the entire compilation unit. Dependencies: None References: ENDUNIT HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -61 Program Compilation CONSULT and NOCONSULT CONSULT and NOCONSULT Note. The NMCOBOL compiler ignores and issues a warning for the NOCONSULT directive. CONSULT object-name-list ( object-name-list ) NOCONSULT VST273.vsd CONSULT adds the files that object-name-list specifies to the tertiary search list. (See Tertiary Search List.) object-name-list object-name , object-name VST274.vsd can be continued onto subsequent lines, but the left parenthesis must appear on the same directive line as the keyword CONSULT. Each continuation line for a CONSULT directive must have a question-mark (?) in the indicator area. If a CONSULT directive spans multiple lines, they must be consecutive (no blank lines, comment lines, or program text lines can intervene). object-name is the name of an object file. It can be either a file-system file name or (in the Guardian environment) a DEFINE name. If the file-system file name is not fully qualified with system, volume, and subvolume names, the compiler uses the current default system, volume, and subvolume names to complete the qualification. If object-name is in the OSS environment, it is an OSS pathname. For the NMCOBOL compiler, object-name must specify either: • • A linkfile An archive file HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -62 Program Compilation CROSSREF and NOCROSSREF When object-name is an archive file, the entire archive file is generally not linked into the target object file. Only those member files are linked that contain procedures named either in the statement CALL or in the statement ENTER in the COBOL program being compiled. Whenever a procedure is needed from a member file, the entire member file is linked. If a native HP COBOL program references object-name either in the statement CALL or in the statement ENTER, object-name must have been compiled with the SYMBOLS directive (see SYMBOLS and NOSYMBOLS). NOCONSULT clears the tertiary search list for the COBOL85 compiler, but is ignored by the NMCOBOL compiler. Default: NOCONSULT Placement: Anywhere Dependencies: None If more than one CONSULT is present, the object names are appended to the list in the order they are read; however, if any object name specified is already in the list, it retains its current position in the list. CROSSREF and NOCROSSREF Note. The NMCOBOL compiler issues warnings for these directives and does not produce a cross-reference listing. If you need one, use the noft utility with the XREFPROC flag (see the noft Manual). CROSSREF and NOCROSSREF determine the classes of symbols included in the cross-reference listing. For TNS HP COBOL programs, the CROSSREF directive duplicates some of the capabilities provided by the CROSSREF utility program. The CROSSREF utility is recommended over the CROSSREF directive because it is more efficient and more flexible, enabling you to include or exclude specific identifiers rather than only identifier classes. For information on the CROSSREF utility, see the CROSSREF Manual. CROSSREF class-list NOCROSSREF VST275.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -63 Program Compilation CROSSREF and NOCROSSREF CROSSREF without a class-list sets the class list to all classes except LITERALS and UNREFS and triggers the collection and reporting of cross-reference information for all classes currently in the class list (see the list under class ). class-list class , ONLY class INCLUDE EXCLUDE VST276.vsd specifies the classes to be cross-referenced. ONLY sets the class list to only the specified classes and triggers the collection of information on all classes, but reports information for only the specified classes. INCLUDE adds the specified classes to the current class list and triggers the collection of information on all classes. EXCLUDE removes the specified classes from the current class list and triggers collection of information on all classes. class is one of the reserved words in the left column of this table: Class COBOL Identifiers Selected (page 1 of 2) ALL All classes CONDITIONS * Condition-names DATANAMES (or VARIABLES) * Data-names (FILLER not included) FILES * (COBOL) file names FUNCTIONS INDEXES * * Index-names LITERALS MNEMONICS Routine-names of functions (routines that return a value) Literals (numeric and nonnumeric) * File-mnemonics HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -64 Program Compilation CROSSREF and NOCROSSREF Class COBOL Identifiers Selected (page 2 of 2) PROCNAMES (or LABELS) * Procedure-names (paragraph-names, sectionnames) PROGRAMS * Program-names, routine-names UNREFS Items defined but not referenced (technically, not a class but a generalized request for all such items) The classes marked with an asterisk in the preceding table are, by default, selected for inclusion, but reporting of cross-reference information about them is suspended until a CROSSREF directive is encountered. NOCROSSREF switches collection off but leaves the class list as it is. A subsequent CROSSREF directive can switch collection back on without respecifying the list. Default: NOCROSSREF Placement: Anywhere Scope: CROSSREF applies to all separately compiled program units, regardless of nesting; that is, all programs within a nest appear in the same crossreference listing. You need not repeat CROSSREF for each program unit in a compilation unit; the class list active at the end of one program unit applies to the next program unit until explicitly altered by NOCROSSREF. Dependencies: CROSSREF works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS Here are some examples of CROSSREF directives in use: • • • • CROSSREF by itself as the only cross-referencing directive applied to a program unit causes the collection of cross-reference information about all identifiers and the reporting of information about those identifiers in the default class list. CROSSREF at the beginning of a program unit, followed by CROSSREF INCLUDE LITERALS at the beginning of the Procedure Division, causes crossreference information about all classes to be collected and causes reporting of all the default classes plus literals for the entire program (not just for the Procedure Division). CROSSREF EXCLUDE MNEMONICS starts (or continues) collecting crossreference information for all classes, but removes the MNEMONIC class from the current class list and establishes reporting of the classes in the revised class list. CROSSREF PROCNAMES removes all classes from the current class list, installs PROCNAMES as the only class, and starts the collection of information for all classes and the reporting of only PROCNAMES. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -65 Program Compilation • DIAGNOSE-74 and NODIAGNOSE-74 CROSSREF at the beginning of a program unit, followed by NOCROSSREF at the beginning of a SECTION, followed by CROSSREF after the end of the SECTION, collects cross-reference information for all of the program unit; it does not suppress the collection or reporting of data in the delimited section. If LIST is active, any cross-reference information collected during the compilation of a given program unit is sent to the output file before subsequent program units in the compilation unit are compiled. The COBOL85 compiler cannot create “global” cross-reference listings because each COBOL program unit is completely self-contained. To obtain a “global” cross-reference listing of an entire compilation unit containing multiple program units, use the CROSSREF utility. For an example of a COBOL cross-reference listing produced by the CROSSREF utility and information on how to use CROSSREF, see Section 24, Issues Related to Binding and Linking. DIAGNOSE-74 and NODIAGNOSE-74 DIAGNOSE-74 NODIAGNOSE-74 VST277.vsd DIAGNOSE-74 causes the compiler to issue warnings when it encounters source constructs that could cause the program to produce different results than it would if it were compiled with the HP COBOL 74 compiler. NODIAGNOSE-74 prevents the compiler from issuing warnings when it encounters source constructs that could cause the program to produce different results than it would if it were compiled with the HP COBOL 74 compiler. Default: NODIAGNOSE-74 Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None The warning messages issued begin with: Logic may differ from COBOL 74 - HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -66 Program Compilation DIAGNOSE-74 and NODIAGNOSE-74 The possible suffixes, explained in Usage Considerations:, are: • • • • • • • • • Size of index data item Implied value of Figurative Constant Precision of division operation Action when program not found Search algorithm Size of receiving operand Identification of statement operand Assignment order of PERFORM operands Alphanumeric sender Usage Considerations: • Size of Index Data Item A data item within a record description has an explicit USAGE INDEX clause. Indexes occupied two bytes in COBOL 74, but occupy four bytes in HP COBOL. You must convert any files that include records in which index data items occur. • Implied Value of Figurative Constant A MOVE statement attempts to assign a value of ALL literal to a numeric or numeric-edited item, or a relation condition involves such a value. You must change the literal to deliver the expected value. If X has a picture of 99.9, COBOL 74 handled MOVE ALL "6" TO X as meaning MOVE 6 TO X HP COBOL handles the same MOVE as meaning MOVE 66.0 TO X • Precision of Division Operation The division operator (/) occurs in an arithmetic expression. In COBOL 74, a division could discard high-level digits without producing a diagnostic. In HP COBOL, a fatal arithmetic overflow can occur. • Action When Program Not Found The OVERFLOW clause is present in a CALL statement. HP COBOL accepts EXCEPTION and NOT EXCEPTION in the CALL statement. You must replace the OVERFLOW clauses in CALL statements with EXCEPTION clauses. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -67 Program Compilation • DIAGNOSE-74 and NODIAGNOSE-74 Search Algorithm The SEARCH ALL statement in COBOL 74 performed a linear search. In HP COBOL, it performs a binary search. You must verify that the table being searched is properly organized (strictly ascending or descending order) so that a binary search is feasible. • Size of Receiving Operand The logic of COBOL 74 and HP COBOL differ in some cases when a value is being assigned to a data structure that contains an item described with an OCCURS DEPENDING phrase. One instance is that of an UNSTRING statement assigning a value through an INTO phrase that does not include a DELIMITER phrase, where the DEPENDING item is within the receiving data structure. COBOL 74 uses the computed size of the receiving item, but HP COBOL uses the maximum size. Another, more general case is when a MOVE, UNSTRING, or some other valuedelivering statement stores a value into a data structure that contains an item described with an OCCURS DEPENDING clause, where the DEPENDING item is not part of the receiving (group) item. COBOL 74 used the maximum size of the receiving item in performing the storage operation in all cases but the one mentioned in the previous paragraph. HP COBOL uses the computed size in all cases where the DEPENDING item is not part of the receiving item. You must check that the value-assigning statement will do what you want it to do. • Identification of Statement Operand In COBOL 74, STRING and UNSTRING statements deferred some subscript evaluations until just before the subscripted item was used. HP COBOL evaluates all subscripts once at the beginning of the statement’s execution. You must check that the STRING and UNSTRING statements do what you want them to do. • Assignment Order of PERFORM Operands In COBOL 74, when a PERFORM VARYING statement controlled multiple loops by using the AFTER phrase, the inner loop base was set before the outer loop index was incremented (or decremented). In HP COBOL, these steps are reversed. When the inner loop logic uses the value of the outer loop’s index, the behavior is different. For example, the statement: PERFORM p1 VARYING x FROM 1 BY 1 UNTIL x = 5 AFTER y FROM x BY 1 UNTIL y = 5. Under COBOL 74 rules, the preceding statement performs these steps in this order: 1. Sets x to 1, sets y to 1 2. Runs y from 1 through 4 HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -68 Program Compilation 3. 4. 5. 6. 7. 8. 9. DIAGNOSE-74 and NODIAGNOSE-74 Sets y to the value of x (still 1), sets x to 2 Runs y from 1 through 4 Sets y to the value of x (now 2), sets x to 3 Runs y from 2 through 4 Sets y to the value of x (now 3), sets x to 4 Runs y from 3 through 4 Terminates In HP COBOL, the same statement performs these steps in this order: 1. 2. 3. 4. 5. 6. 7. 8. 9. Sets x to 1, sets y to 1 Runs y from 1 through 4 Sets x to 2, sets y to the value of x (now 2) Runs y from 2 through 4 Sets x to 3, sets y to the value of x (now 3) Runs y from 3 through 4 Sets x to 4, sets y to the value of x (now 4) Runs y with the value 4 Terminates You must revise the logic of any PERFORM VARYING containing an AFTER phrase that is controlled by the index of the outer loop. The simplest maneuver is probably to separate the PERFORM into two separate PERFORM statements, because you cannot use an arithmetic expression in the FROM phrase. • Alphanumeric Sender When left-justified numbers with trailing spaces are moved from an alphanumeric data item to a numeric data item described as USAGE DISPLAY or to a numeric edited data item, the result differs between COBOL 74 and HP COBOL. For example, given these descriptions: 01 ITEM-A 01 ITEM-B PIC X(5) VALUE "05 PIC 9(5). ". The statement MOVE ITEM-A TO ITEM-B results in "00005" in ITEM-B for COBOL 74 and "05 " in ITEM-B for HP COBOL. If you cannot avoid moving left-justified numbers with trailing spaces between these data types, use an UNSTRING statement with a DELIMITED BY SPACES phrase rather than a MOVE statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -69 Program Compilation DIAGNOSE-85 and NODIAGNOSE-85 DIAGNOSE-85 and NODIAGNOSE-85 Note. The COBOL85 compiler does not recognize these directives. DIAGNOSE-85 NODIAGNOSE-85 VST719.vsd DIAGNOSE-85 causes the NMCOBOL compiler to issue warnings when it encounters source constructs that could cause the program to produce different results than it would if it were compiled with the COBOL85 compiler. NODIAGNOSE-85 prevents the NMCOBOL compiler from issuing warnings when it encounters source constructs that could cause the program to produce different results than it would if it were compiled with the COBOL85 compiler. Default: NODIAGNOSE-85 Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -70 Program Compilation DIAGNOSEALL and NODIAGNOSEALL DIAGNOSEALL and NODIAGNOSEALL DIAGNOSEALL NODIAGNOSEALL VST470.vsd DIAGNOSEALL causes the compiler to issue a warning each time it encounters an undefined identifier, even if it already issued a warning for a previous use of that identifier. NODIAGNOSEALL causes the compiler to issue a warning the first time it encounters an undefined identifier, but not if it already issued a warning for a previous use of that identifier. Default: NODIAGNOSEALL Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None ENDIF ENDIF terminates the effect of a preceding IF or IFNOT directive. ENDIF toggle-number VST278.vsd toggle-number is the toggle-number specified in a preceding IF or IFNOT directive. Default: None Placement: Must be either on a directive line of its own or be the last of a sequence of directives. Dependencies: Requires a preceding IF or IFNOT directive with the same togglenumber References: IF and IFNOT HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -71 Program Compilation ENDUNIT ENDUNIT ENDUNIT signals the end of a program unit. Each independent HP COBOL program must end with either an ENDUNIT directive or an END PROGRAM statement; otherwise, programs appear to be nested but lacking their required END PROGRAM statement. ENDUNIT VST279.vsd Default: The compiler detects the end of a Procedure Division by encountering either an END PROGRAM statement or the end of the file. Placement: Must be either on a directive line of its own or be the last of a sequence of directives. Scope: Applies to program unit Dependencies: None ENV Note. This directive is useful only for the COBOL85 compiler. The NMCOBOL compiler accepts this directive with the COMMON option (the default for this compiler), reports an error for the OLD option, and issues a warning for the LIBRARY option. ENV COMMON LIBRARY OLD VST280.vsd COMMON LIBRARY OLD See Table 11-20. Default: ENV OLD Placement: Must appear before any source code lines Scope: Applies to all programs in its source file Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -72 Program Compilation ENV Table 11-20. Effects of ENV Directive Options COBOL85 Compiler ENV Option Guardian Environment OSS Environment NMCOBOL Compiler COMMON Selects CRE Selects CRE (required) Accepted but unnecessary (CRE is the default) LIBRARY Selects CRE and allows program to be put in a user library. Program must satisfy the criteria in Library Programs Not accepted Ignored, warning issued * OLD Selects non-CRE environment Not accepted Not accepted * To build a user library, use UL. Topics: • • Library Programs ENV and Compatible Programs Library Programs Note. This topic applies only to the COBOL85 compiler. If you are using the non-CRE or OSS environment, you cannot put an HP COBOL routine in the user library (because you cannot compile it with the ENV LIBRARY directive). If you are using the CRE, you can compile an HP COBOL program with the ENV LIBRARY directive and put it into a user library if the program satisfies these criteria: • • • • • • • • • It is not a main program. It is an initial program (its PROGRAM-ID paragraph specifies INITIAL). It is a separately compiled program (it is not embedded in another program). It does not contain any other programs. It does not specify the GLOBAL phrase on any level-01 record descriptions. It does not reference any external data items or external files. It does not have an Extended-Storage Section. It does not have a PROGRAM COLLATING SEQUENCE clause. It does not contain SQL/MP statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -73 Program Compilation ENV If a program does not meet the preceding criteria and you try to compile it with the ENV LIBRARY directive, the compiler reports an error. If you compile a program with the ENV LIBRARY directive: • • ASSIGN and PARAM commands for the files in the program are ignored. The compiler does not create data blocks or references to data blocks for the program. Instead, the operating environment creates these at run time. The program requires more overhead when called and might execute slightly more slowly. ENV and Compatible Programs Two programs are compatible if one can call the other. A program can call another program if both programs run in the CRE or if both programs run in language-specific environments that allow them to call each other. Table 11-21. ENV Directive and TNS Program Compatibility TNS program compiled with ... Is compatible with TNS programs compiled with ... ENV COMMON ENV COMMON ENV LIBRARY ENV LIBRARY ENV COMMON ENV LIBRARY ENV OLD ENV OLD No ENV directive No ENV directive ENV OLD No ENV directive HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -74 Program Compilation ERRORFILE ERRORFILE ERRORFILE specifies an error-logging file that is to contain information about any compilation errors or warnings. The error-logging file is not an EDIT file. You can use it only with the FIXERRS Macro. ERRORFILE file-name define-name VST281.vsd file-name is the name of the error-logging file. It must be a disk file name. define-name is the name of a MAP DEFINE that refers to a disk file. The compiler uses this file as the error-logging file. Default: None Placement: Either on the compiler command line or in the source file before the Identification Division. Scope: Applies to the compilation unit Dependencies: None If the specified file does not already exist, the compiler creates an entry-sequenced file using the specified file name and the file code 106. If the specified file is an existing error file identified by file code 106, the compiler replaces the contents of the existing file with the new error file. If the specified file is an existing file but is not an error file, the compiler terminates compilation and displays the message ERRORFILE not created The error file contains one record for each error or warning message that the compiler found during compilation. Each error record contains this information: • The fully qualified, local file name of the file in which the compiler found the error or warning If you specified a DEFINE name for the name of the source file, the name of the file to which the DEFINE evaluated appears in this entry. • • • The EDIT line number in which the error or warning occurred The column number in the line where the compiler detected the error or warning The error or warning message text HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -75 Program Compilation ERRORS ERRORS ERRORS sets the maximum number of severe errors allowed during compilation. If this limit is exceeded, the compilation terminates. ERRORS error-limit VST282.vsd error-limit is an integer in the range 0 through 32767. Default: ERRORS 100 Placement: Anywhere Scope: Applies to the compilation unit Dependencies: None FIPS and NOFIPS FIPS and NOFIPS determine whether the compiler identifies language elements as required by the Federal Information Processing Standard (FIPS). FIPS flag-option-list ( flag-option-list ) NOFIPS VST468.vsd FIPS identifies the language elements specified by flag-option-list. NOFIPS prevents identification of language elements which violate the FIPS. flag-option-list flag-option , flag-option VST469.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -76 Program Compilation FIPS and NOFIPS flag-option Value Elements Identified OBSOLETE Obsolete language elements ABOVEMIN Language elements above the minimum subset ABOVEINTER Language elements above the intermediate subset LEVEL1COM * Communication language elements ABOVELEVEL1COM * Communication language elements above level 1 of communication LEVEL1DEB Debug language elements ABOVELEVEL1DEB * Debug language elements above level 1 of Debug REPORTWRITER * Report Writer language elements LEVEL1SEG Segmentation language elements ABOVELEVEL1SEG Segmentation language elements above level 1 of segmentation NONSTANDARDEXT Nonstandard extensions to HP COBOL * This option does not affect compilation because the compiler does not support this module. If you use this option, the compiler issues a warning and ignores the option. Default: NOFIPS Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -77 Program Compilation FLOAT and NOFLOAT FLOAT and NOFLOAT Note. The NMCOBOL compiler ignores this directive and issues a warning. FLOAT NOFLOAT VST818.vsd FLOAT allows the compiler to use floating-point arithmetic for certain complex expressions. NOFLOAT prevents the compiler from using floating-point arithmetic for certain complex expressions. Default: FLOAT Placement: Outside the boundaries of any program Scope: Applies to all subsequent programs Dependencies: None FMAP Note. The COBOL85 compiler does not recognize this directive. FMAP causes the NMCOBOL compiler to produce a source file map, which shows the fully qualified name and timestamp of the IN file and each file specified by a SOURCE directive or COPY statement. FMAP VST731.vsd Default: The NMCOBOL compiler does not produce a source file map. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: NOLIST and SUPPRESS do not suppress the source file map that FMAP produces. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -78 Program Compilation HEADING HEADING HEADING replaces or sets to spaces the heading portion of the standard top-of-page line that appears on each page of the compilation listing. HEADING " character-string " VST283.vsd character-string is a string of one or more ASCII characters. If a quotation mark character is part of the string, it must be represented as two contiguous quotation marks. The string is used in all subsequent top-of-page lines. If character-string is omitted, the heading portion of the top-of-page lines is set to all spaces. Default: Standard top-of-page line Placement: Anywhere Scope: Applies until another HEADING overrides it Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -79 Program Compilation HEAP HEAP Note. The NMCOBOL compiler ignores this directive and issues a warning. HEAP specifies heap space size in the CRE. HEAP is useful only in the Guardian environment and only if the program calls HP C functions that allocate heap space. HEAP size VST738.vsd size is an integer in the range 2048 through 2,147,483,684 that represents the number of bytes to allocate for the CRE user heap. Default: Guardian environment: the heap is nonexistent by default. PC and OSS environments: the heap is large by default and cannot be made larger. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: Program must run in the CRE HIGHPIN Note. The NMCOBOL compiler ignores this directive and issues a warning. A native HP COBOL program always runs at a high PIN. HIGHPIN sets the HIGHPIN flag in an object file so that the object file can run at a high PIN. HIGHPIN VST284.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -80 Program Compilation HIGHPIN Default: TNS program runs with a low PIN (less than or equal to 255). Placement: Any of: • • • Anywhere in the source program (but it is good practice to put it before the first program in a compilation unit) On the compiler command line In a stand-alone Binder session Scope: Applies to the program in which or before which it appears and to all subsequent programs in the compilation unit Dependencies: Program must be compiled with ENV COMMON. References: ENV For your object file to run at a high PIN, these conditions must be met: • • • • • Your object file and user library, if any, have the HIGHPIN flag set. Your object file runs in the CRE (see ENV). Your processor is configured for more than 256 process control blocks (PCBs). High PINs are available on your processor. The TACL HIGHPIN built-in variable or the HIGHPIN run-time parameter is set. If the above conditions are met, your object file can create another process to run at high PIN by calling the CLU_PROCESS_CREATE_ procedure. This sequence of examples shows how to run an object file at high PIN from the TACL prompt. The examples show how to check your processor configuration and high-PIN availability, set the HIGHPIN flag, and override the TACL HIGHPIN setting if it is off. Examples: 1. To check the number of PCBs configured in your processor and to see if high PINs are available, run the Peek product. For example, if you want to run your object file on processor 1: PEEK / CPU 1 / This display excerpt shows example values for the information you need to check: PCB ... CURRENT USAGE 127: 48 # CONFIGURED ... 255: 244 The processor is configured for high PINs if the sum of the two values displayed for PCBs under “# CONFIGURED” is 256 or greater. In this example, the processor is configured for high PINs, because 255 + 244 = 499. The processor has high PINs available if the right-hand value under “CURRENT USAGE” is less than the right-hand value under “# CONFIGURED.” In this example, the processor has high PINs available, because 48 is less than 244. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -81 Program Compilation HIGHPIN 2. You can set the HIGHPIN flag of an object file during compilation by including the HIGHPIN directive in the compilation command: COBOL85 /IN cobsrc,OUT $s.#coblst,NOWAIT/ cobobj; HIGHPIN 3. Alternatively, you can set the HIGHPIN flag of an object file after compilation by typing this Binder command: BIND CHANGE HIGHPIN ON IN cobobj 4. Before you run the object file, you can check the current setting of the TACL HIGHPIN built-in variable by typing: #HIGHPIN 5. If #HIGHPIN returns a NO value, you can set the HIGHPIN run-time parameter (and run your object file at a high PIN): RUN cobobj / HIGHPIN ON / 6. If #HIGHPIN returns a YES value, you can simply run your object file at a high PIN: RUN cobobj HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -82 Program Compilation HIGHREQUESTERS HIGHREQUESTERS Note. The NMCOBOL compiler ignores this directive and issues a warning. A native HP COBOL program always runs at a high PIN. HIGHREQUESTERS allows the program to run as a server that communicates with requesters running at high PINs (process identification numbers greater than 255). HIGHREQUESTERS VST285.vsd Default: Program cannot run as a server that accepts requesters running with high PINs (greater than 255). Placement: Any of: • • • Anywhere in the source program (but it is good practice to put it in the main program, because that is the only program it affects—that is, Binder assumes that a run unit can accept high PIN requesters only if HIGHREQUESTERS is specified for the main program in the run unit) On the compiler command line In a stand-alone Binder session Scope: Applies to the main program in which or before which it appears in the compilation unit Dependencies: Program must be compiled with ENV COMMON and HIGHPIN. References: • • ENV HIGHPIN IICODE and NOICODE Note. The NMCOBOL compiler ignores these directives and issues warnings. For the NMCOBOL compiler, use INNERLIST and NOINNERLIST instead. ICODE NOICODE VST286.vsd ICODE lists an mnemonic image of the compiled code following successful compilation of a program unit. The mnemonic listing appears after the symbol table listing produced by MAP (if any) and after the octal image produced by CODE (if any). HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -83 Program Compilation IF and IFNOT NOICODE suppresses the mnemonic image of the compiled code. Default: NOICODE Placement: Anywhere Scope: Last ICODE or NOICODE applies to program unit. Dependencies: ICODE works only if LIST is active and SUPPRESS is not. References: • • • • LIST and NOLIST SUPPRESS and NOSUPPRESS MAP and NOMAP CODE and NOCODE IF and IFNOT IF toggle-number IFNOT VST287.vsd IF enables compilation of subsequent source text if the toggle with toggle-number is set; disables it otherwise. IFNOT suppresses compilation of subsequent source text if the toggle with togglenumber is set; enables it otherwise. toggle-number is an integer in the range 1 through 15. Default: None Placement: Must be either on a directive line of its own or be the last of a sequence of directives Dependencies: Requires a preceding IF or IFNOT directive with the same togglenumber References: IF and IFNOT The toggles are turned on and off by use of the SETTOG and RESETTOG directives. If no SETTOG directive has been issued, a toggle is off. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -84 Program Compilation IF and IFNOT COPY and REPLACE statements are not affected by this directive; they are still processed and expanded. In contrast, a SOURCE directive is ignored when it is part of the ignored text. If a given toggle is not set, any directives between an IF for that toggle and its subsequent ENDIF are parsed but are not acted upon; if a given toggle is set, any directives between an IFNOT for that toggle and its subsequent ENDIF are parsed but are not acted upon. Example 11-11. IF Directive ?IF 1 ADD A B C GIVING D ?ENDIF 1 ?IFNOT 1 COMPUTE D = A + B + C ?ENDIF 1 In Example 11-11, if toggle 1 is turned on, the ADD statement is compiled; if toggle 1 is turned off, the COMPUTE statement is compiled. Note. The IFNOT directive does not behave like an ELSE clause of the IF directive. Each IF and each IFNOT must have its own ENDIF directive. Example 11-12. Nested IF and IFNOT Directive Scopes IF and IFNOT scopes can be nested. Given this program fragment: 01 MASTER-RECORD. 03 HEADER PICTURE X(30). ?IF 1 03 ACCOUNT-ID PICTURE X(50). ?IF 2 03 ACCOUNT-ID-REDEF REDEFINES ACCOUNT-ID. 05 ACCOUNT-GROUP PICTURE X(20). 05 ACCOUNT-CLASS PICTURE X(10). 05 ACCOUNT-NUMBER PICTURE X(20). ?ENDIF 2 03 TRAILER PICTURE X(100). ?ENDIF 1 HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -85 Program Compilation IF and IFNOT The compiler sees this, depending on the setting of toggles 1 and 2: Toggles On Source Lines Compiled None 01 MASTER-RECORD. 03 HEADER PICTURE X(30). 01 MASTER-RECORD. 03 HEADER 03 ACCOUNT-ID 03 TRAILER PICTURE X(30). PICTURE X(50). PICTURE X(100). 01 MASTER-RECORD. 03 HEADER PICTURE X(30). 1 only 2 only 1 and 2 01 MASTER-RECORD. 03 HEADER PICTURE X(30). 03 ACCOUNT-ID PICTURE X(50). 03 ACCOUNT-ID-REDEF REDEFINES ACCOUNT-ID. 05 ACCOUNT-GROUP PICTURE X(20). 05 ACCOUNT-CLASS PICTURE X(10). 05 ACCOUNT-NUMBER PICTURE X(20). 03 TRAILER PICTURE X(100). Lines whose compilation IF or IFNOT suppresses still appear in the compiler listing. To keep them from appearing, use NOLIST and LIST directives as the code fragments in Example 11-13 show. Example 11-13. Omitting Uncompiled Lines from Compiler Listing ?IF n ?NOLIST ?ENDIF n ?IFNOT n * Lines compiled if toggle n is not set go here ?ENDIF n ?IF n ?LIST ?ENDIF n ?IFNOT n ?NOLIST ?ENDIF n ?IF n * Lines compiled if toggle n is set go here ?ENDIF n ?IFNOT n ?LIST ?ENDIF n HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -86 Program Compilation INNERLIST and NOINNERLIST INNERLIST and NOINNERLIST Note. The COBOL85 compiler does not recognize these directives. For the COBOL85 compiler, use IICODE and NOICODE instead. INNERLIST NOINNERLIST VST724.vsd INNERLIST lists, immediately after each source statement, the generated machine instructions in mnemonic form. NOINNERLIST suppresses the listing of generated machine instructions. Default: NOINNERLIST Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: INNERLIST works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -87 Program Compilation INSPECT and NOINSPECT INSPECT and NOINSPECT INSPECT NOINSPECT VST288.vsd INSPECT turns on the Inspect attribute for the debugging tool for the compilation unit. NOINSPECT turns off the Inspect attribute for the debugging tool for the compilation unit. The Inspect attribute partially determines the debugger for the compilation unit. For more information, see Debugger Selection. Default: INSPECT Placement: Anywhere Scope: The last INSPECT or NOINSPECT in the compilation unit applies to the compilation unit. Dependencies: NOINSPECT and SAVEABEND override each other (whichever is last is active). References: SAVEABEND and NOSAVEABEND LARGEDATA Note. This directive is useful only in the CRE. LARGEDATA determines where individual data items are located in memory—in the user data space or the user extended space (for the COBOL85 compiler) or in the small data area or large data area (for the NMCOBOL compiler). Access to data items in the user data space is faster than access to data items in the user extended space, but the user data space is limited to approximately 50K characters. Similarly, access to data items in the small data area is faster than access to data items in the large data area, but the small data area is limited to approximately 32,768 characters. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -88 Program Compilation LARGEDATA LARGEDATA item ( ) item , item VST725.vsd item is one of: • • • • An unsigned integer constant between 0 and 32767 A filename A level-01 data name A level-77 data name If LARGEDATA is specified without item, the COBOL85 compiler uses the value 256 and the NMCOBOL compiler uses the value 64. If the LARGEDATA directive is not specified, the COBOL85 compiler uses LARGEDATA 0 and the NMCOBOL compiler uses LARGEDATA 64. If item is a constant: • • • If item is zero, the COBOL85 compiler allocates space for data items whose definitions are not in the Extended-Storage Section in user data space unless the item is directly or indirectly specified by name in a LARGEDATA directive. An item is indirectly specified if it is a file record area and the filename is specified in a LARGEDATA directive (it is as if the LARGEDATA directive were never specified with a constant). The NMCOBOL compiler allocates all such data items in the small data area. If item is less than the default, the compiler uses the default instead. If item is greater than or equal to the default, the COBOL85 compiler allocates space for data items and record areas that are at least item bytes in the user extended area, and the NMCOBOL compiler allocates space for them in the large data area. If a file description entry is followed by more than one record description entry and the length of any record description entry other than the first is greater than or equal to item, allocation depends on the first record or on the filename. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -89 Program Compilation LARGEDATA If item is a data name, the COBOL85 compiler allocates space for it in the user extended area; the NMCOBOL compiler allocates space for it in the large data area. If the data name is a file record area, the same thing occurs only if all of these conditions are true: • • • The data name is that of the first record area for the file. The filename is specified in a SAME RECORD AREA clause. The filename is the first one in the file section of all of the names specified in the clause. If the data name is a file record area and not all of the preceding are true, the compiler ignores the LARGEDATA directive. If item is a filename, the associated record area is allocated in the user extended space unless both: • • The filename is specified in a SAME RECORD AREA clause. A file description entry for another file in the SAME RECORD AREA clause has been processed already and a LARGEDATA directive does not apply to it. Default: None Placement: Anywhere Scope: If LARGEDATA specifies constants, or has no item, and precedes the PROCEDURE DIVISION header in the program that contains it, then it applies to the program that contains it and to subsequent programs. If LARGEDATA specifies constants, or has no item, and follows the PROCEDURE DIVISION header in the program that contains it, then it applies only to subsequent programs. Dependencies: Program must be compiled with ENV COMMON or ENV LIBRARY. References: ENV You can compile a program with more than one LARGEDATA directive. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -90 Program Compilation LD LD Note. The COBOL85 compiler does not accept this directive. LD ( option ) VST111.vsd option is an ld option to be passed to the ld utility. For information about ld options, see the ld Manual. Default: None Placement: In the command line Scope: Applies to the compilation unit Dependencies: None LESS-CODE Note. The compiler ignores this directive and issues a warning. LESS-CODE determines whether the program generates code that initializes the Working-Storage Section or Extended-Storage Section or uses a system call to initialize the Extended-Storage Section. Using a system call reduces the size of the program’s object code, but takes a significantly longer time to execute because it must perform a read operation. Use LESS-CODE only for a program that is rarely called. LESS-CODE bits-to-set VST384.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -91 Program Compilation LESS-CODE bits-to-set is an integer in the range 0 through 7, which is interpreted: Value of bits-to-set Decimal Binary Result 0 000 Compiler generates code to initialize all areas. 1 001 Compiler generates code to initialize all areas except the Extended-Storage Section in: • • Main programs Other programs that are not initial programs and have NOCANCEL directives active Size of object file increases significantly, amount of code generated decreases significantly, and execution time decreases slightly. 2 010 Compiler generates code to initialize all areas except the Extended-Storage Section in: • Programs that are not main programs and are either initial programs or do not have NOCANCEL directives active Size of object file decreases significantly and amount of code generated decreases significantly. Execution time increases under either of these conditions: • • The program is an initial program and is called more than once The program is not an initial program and is cancelled several times Execution time decreases under either of these conditions: • The program is an initial program and is only called once The program is not an initial program and is never cancelled 3 011 Same as 1 and 2 combined 4 100 Compiler generates code to initialize all areas except the Working-Storage Section in: • • Main programs Programs that are not main programs and are either initial programs or do not have NOCANCEL directives active Size of object file can increase by a maximum of 65,536 bytes for each program to which the conditions apply. Amount of code generated and execution time can decrease. 5 101 Same as 1 and 4 combined 6 110 Same as 2 and 4 combined 7 111 Same as 1, 2, and 3 combined HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -92 Program Compilation LIBRARY Default: None Placement: The compiler accepts it anywhere, but to be effective, it must be before the main program. Scope: Applies to the compilation unit Dependencies: None LIBRARY Note. The NMCOBOL compiler ignores this directive and issues a warning. To specify a user library, see Specifying a User Library. LIBRARY specifies the name of a TNS user library for resolving unqualified external references. LIBRARY file-name VST289.vsd file-name is a name that designates an object file. It cannot be a DEFINE name or a file name on another system. If file-name is not qualified with volume and subvolume names, the compiler uses the current default volume and subvolume names to complete the qualification. Default: None Placement: Anywhere, but the COBOL85 compiler and the Binder do not propagate LIBRARY from called to calling programs; therefore, calling programs cannot reference library objects in called programs unless you use one of these methods: • • • Use a separate bind step on the final object with a SET LIBRARY file-name command. Use the LIB parameter on the RUN command. Specify the LIBRARY directive on the main compilation. Scope: The last LIBRARY applies to the loadfile produced by the compilation. Dependencies: None Specification of the LIBRARY directive affects the way in which the compilation resolves unqualified references in ENTER statements. The user library is searched after the primary search list, and prior to the tertiary search list. See How the Compiler Resolves Unqualified References. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -93 Program Compilation LINES LINES LINES determines the number of lines to be listed on each page of the output file. Whenever the next line of a listing would cause a page to exceed the specified line count, the compiler ejects the page and begins a new listing page. It prints the standard page heading at the top of the new page, followed by two blank lines, and then the next line of the listing. LINES lines-per-page VST290.vsd lines-per-page is an integer in the range 10 through 32767. Default: LINES 60 Placement: Anywhere Scope: Applies until another LINES overrides it Dependencies: LINES works only if paging applies to the compilation list device. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -94 Program Compilation LIST and NOLIST LIST and NOLIST LIST NOLIST VST291.vsd LIST lists each source image in the output file. NOLIST suppresses the listing of each source image in the output file. Default: LIST Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: SUPPRESS overrides LIST (and therefore CODE, CROSSREF, ICODE, LMAP, MAP, SHOWCOPY, and SQL). NOLIST suppresses INNERLIST. References: • • • • • • • • • SUPPRESS and NOSUPPRESS CODE and NOCODE CROSSREF and NOCROSSREF IICODE and NOICODE INNERLIST and NOINNERLIST LMAP and NOLMAP MAP and NOMAP SHARED SQL and NOSQL HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -95 Program Compilation LMAP and NOLMAP LMAP and NOLMAP Note. The NMCOBOL compiler, which does not use BINSERV, ignores these directives and issues warnings. LMAP lm-option-list ( lm-option-list ) * NOLMAP lm-option-list ( lm-option-list ) VST292.vsd LMAP requests from BINSERV the load maps specified by lm-option-list. NOLMAP suppresses the load maps specified by lm-option-list. lm-option-list lm-option , lm-option VST293.vsd whether enclosed in parentheses or not, lm-option list cannot be continued onto subsequent lines. lm-option Value Load Map Requested (by LMAP) or Suppressed (by NOLMAP) ALPHA Programs and subprograms sorted by procedure-name LOC Programs and subprograms sorted by starting address XREF Cross-reference listing of entry-point and data-block names HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -96 Program Compilation LMAP and NOLMAP * requests all load maps. The possible combinations of LMAP and NOLMAP and their effects are: Directive Specified Effect None LMAP ALPHA LMAP without lm-option-list LMAP ALPHA LMAP with lm-option-list LMAP lm-option-list NOLMAP without lm-option-list NOLMAP ALPHA, LOC, XREF NOLMAP with lm-option-list If they were on, the load maps that lm-option-list specifies are turned off Default: LMAP ALPHA Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: LMAP works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -97 Program Compilation MAIN MAIN MAIN identifies the main program unit. MAIN program-name VST294.vsd program-name is the program-name (specified in the PROGRAM-ID paragraph) of the program that is the main entry point of the target file being produced by the compilation. Default: Every program unit that does not have a Linkage Section is compiled as a main program. If more than one program unit of a compilation unit qualifies as a main program, the compiler reports this as an error, compiles the first qualifying program unit as the main program, and produces multiple object files. Placement: Before the Identification Division header of the first program unit in the compilation unit. Scope: Applies to the program that contains it Dependencies: None When MAIN appears, only the program unit indicated (the one beginning with a PROGRAM-ID paragraph that specifies the same program-name) is compiled as a main program. All other program units in the compilation unit are compiled as called programs, whether or not they include a Linkage Section. If no PROGRAM-ID paragraph in the compilation unit specifies the same programname as that specified in MAIN, the compiler reports that the resulting target file has no main program. It is therefore not executable. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -98 Program Compilation MAP and NOMAP MAP and NOMAP MAP NOMAP VST295.vsd MAP lists a symbol table listing, which appears after the source program listing for the program unit (see Symbol Table Listing). NOMAP suppresses the symbol table listing. Default: NOMAP Placement: Anywhere Scope: The last MAP or NOMAP applies. Dependencies: MAP works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS NLD NLD ( option ) VST082.vsd option is an nld option to be passed to the nld utility. For information about nld options, see the nld Manual. Default: None Placement: In the command line Scope: Applies to the compilation unit Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 11 -99 Program Compilation NONSTOP NONSTOP Note. • • Do not use this directive in the OSS environment. Before RVU D46.00 and G06.00, software product revision T8107AAT (run-time library T8108AAR), the NMCOBOL compiler ignores this directive and issues a warning. NONSTOP causes the compiler to accept the STARTBACKUP verb. The STARTBACKUP and CHECKPOINT verbs enable you to run a program as a process pair. NONSTOP VST296.vsd Default: The program cannot run as a process pair (even if it contains a PARAM NONSTOP ON command). Placement: Must appear before the Identification Division of the first program unit in the source text. Scope: Applies to the program unit Dependencies: PARAM NONSTOP OFF command overrides NONSTOP. References: PARAM Command When a program is compiled without this directive, a PARAM NONSTOP command is not enough to make the program run as a process pair. If NONSTOP is absent, the compiler reports an error if it finds a STARTBACKUP verb. Note. Section 32, Fault-Tolerant Processes, explains how to use the HP fault-tolerant facility. It is your responsibility to design the program to make use of the CHECKPOINT and STARTBACKUP statements to operate in a fault-tolerant manner. The presence of the NONSTOP directive and CHECKPOINT and STARTBACKUP statements do not guarantee fault tolerance. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 100 Program Compilation NON-SHARED NON-SHARED Note. The COBOL85 compiler does not recognize this directive. NON-SHARED CALL-SHARED SHARED VST803.vsd CALL-SHARED generates shared code (PIC). NON-SHARED generates nonshared code (non-PIC). SHARED generates shared code (PIC) for a DLL. Note. You cannot link PIC and non-PIC object files into a single object file. Default: NON-SHARED Placement: Anywhere Scope: The last NON-SHARED, CALL-SHARED, or SHARED in the compilation unit applies to the entire compilation unit. Dependencies: If RUNNABLE is active, NON-SHARED creates a non-PIC executable object file; otherwise, NON-SHARED creates a non-PIC nonexecutable object file. References: • • • CALL-SHARED SHARED RUNNABLE HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 101 Program Compilation OPTIMIZE OPTIMIZE OPTIMIZE specifies the extent to which the compiler attempts to optimize the code it emits. OPTIMIZE level VST297.vsd level is 0, 1, or 2. Optimization level has only a small effect on compilation speed. The effect of each level is: Effect Level COBOL85 Compiler NMCOBOL Compiler 0 Code is not optimized. Provided in case other optimization levels cause errors. Supports symbolic debugging; data is always in memory. Code is not optimized. Provided in case other optimization levels cause errors. Supports symbolic debugging; data is always in memory. 1 (default) Code is optimized within statements, but not across statement boundaries. Appropriate for application programs still being developed and tested. Supports symbolic debugging; data is not always in memory. Code is optimized within statements and across statement boundaries. The resulting code is more efficient than that produced by lower levels of optimization. Supports symbolic debugging; data is not always in memory. 2 Code is optimized within statements and across statement boundaries, and the resulting code is more efficient than code produced by lower levels. Uses level 1 instead. Note. For TNS HP COBOL programs, code generated under OPTIMIZE 2 is more difficult to debug than code generated under OPTIMIZE 0 or OPTIMIZE 1. For NMCOBOL programs, code generated under OPTIMIZE 1 is more difficult to debug than code generated under OPTIMIZE 0. Optimization under OPTIMIZE 2 obscures statement boundaries. Before you attempt to use a symbolic debugger to debug a program, do either: • • For a TNS HP COBOL program, be certain that the program was compiled with OPTIMIZE 1; for an NMCOBOL program, be certain that the program was compiled with OPTIMIZE 0. Use the output generated by the CODE, ICODE, or INNERLIST directive to be certain of statement boundaries. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 102 Program Compilation PERFORM-TRACE Default: OPTIMIZE 1 Placement: Outside the boundary of a separately compiled program Scope: The optimization level active at the beginning of a separately compiled program determines the level of optimization for that program and any programs it contains. Dependencies: None PERFORM-TRACE PERFORM-TRACE gives additional information if run-time error 148, “PERFORM nesting too deep,” occurs. PERFORM-TRACE VST800.vsd If the program was compiled with the PERFORM-TRACE directive and run-time error 148 occurs, this additional information is given: Line numbers of PERFORMs from latest to earliest Line Number File Number llllll.lll nnn ... The file number nnn is the number of the source file. The source-file specified in the compilation command has file number 001. A file number is shown for each file referenced by the directive SOURCE or a COPY Statement. To see the file numbers, compile the program with SHOWFILE directive (see SHOWFILE and NOSHOWFILE). Default: The compiler does not provide additional information if run-time error 148 occurs. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 103 Program Compilation PORT and NOPORT PORT and NOPORT PORT and NOPORT determine: • • How BINARY/COMPUTATIONAL data items are aligned Whether the CALL statement in a program running in the CRE behaves as defined in X/Open and XPG4 specification. PORT 1 2 3 NOPORT VST600.vsd PORT aligns BINARY/COMPUTATIONAL data items on byte boundaries (unless they are described with the SYNCHRONIZED clause, which aligns them on 2-byte boundaries). PORT also allows the CALL statement in a program running in the CRE to behave as it does in X/Open and XPG4; that is, to call non-COBOL routines, pass parameters by value, and return the values of functions. 1 • • • Allows CALL to call programs other than COBOL programs Prevents the compiler from issuing a warning when the Linkage Section does not having a matching item in the PROCEDURE DIVISION header Causes the external variable RETURN-CODE to be automatically defined 2 prevents binary items from being aligned on word boundaries. 3 does what both PORT 1 and PORT 2 do. PORT 3 is equivalent to PORT. NOPORT aligns BINARY/COMPUTATIONAL data items according to standard alignment rules and prevents the CALL statement in a program running in the CRE from calling non-COBOL routines, passing parameters by value, and returning the values of functions. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 104 Program Compilation PORT and NOPORT Default: NOPORT Placement: Anywhere Scope: Applies to the compilation unit Dependencies: None Usage Considerations: • NATIVE-n Data Items and Pointers The PORT directive does not affect the alignment of NATIVE-n data items or pointers. • Run-Time Performance The PORT directive can severely impact n HP COBOL program’s run-time performance. • Passing Parameters to Programs Not Compiled With PORT If a program compiled with the PORT directive calls and passes parameters to a program not compiled with the PORT directive (or compiled with the NOPORT directive), serious problems can arise from differences in the way BINARY/COMPUTATIONAL data items are aligned in the two programs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 105 Program Compilation RESETTOG RESETTOG RESETTOG turns off all specified toggles, which are used by the IF directive. RESETTOG toggle-number-list VST298.vsd toggle-number-list toggle-number , toggle-number VST299.vsd toggle-number is an integer in the range 1 through 15. If toggle-number is omitted, all toggles are turned off. Default: None Placement: Must be either on a directive line of its own or be the last of a sequence of directives Scope: Applies until SETTOG overrides it Dependencies: SETTOG overrides it. References: SETTOG HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 106 Program Compilation RUNNABLE RUNNABLE Note. The COBOL85 compiler does not recognize this directive. RUNNABLE causes the NMCOBOL compiler to use the linker to produce a loadfile if there are no compilation errors. RUNNABLE VST729.vsd Default: The NMCOBOL compiler does not use the linker to produce a loadfile if there are no compilation errors. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: SYNTAX overrides RUNNABLE. You must specify RUNNABLE to use RUNNAMED, SAVEABEND, NOSAVEABEND, or SUBTYPE in the NMCOBOL compiler. Without CALL-SHARED or SHARED, RUNNABLE uses the linker to produce a non-PIC loadfile. With CALL-SHARED, RUNNABLE uses the linker to produce a PIC loadfile. With SHARED, RUNNABLE uses the linker to produce a PIC library file (DLL). References: • • • • • • SYNTAX RUNNAMED SAVEABEND and NOSAVEABEND SUBTYPE CALL-SHARED SHARED If you run the NMCOBOL compiler without the directive RUNNABLE or SYNTAX and no compilation errors occur, you can produce a loadfile by running the nld utility separately (see the nld Manual). If you do so, you must specify that the COBOL85 shared run-time library (ZCOBSRL) and CRE shared run-time library (ZCRESRL) reside on the subvolume $SYSTEM.SYSnn. If you run the NMCOBOL compiler with the CALL-SHARED or SHARED directive, and without the directive RUNNABLE or SYNTAX, and no compilation errors occur, you can produce a loadfile by running the ld utility separately (see the ld Manual). HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 107 Program Compilation RUNNAMED RUNNAMED RUNNAMED specifies that the run unit is to be run as a named process. RUNNAMED VST300.vsd Default: None Placement: Any of: • • • Anywhere in a source program In a stand-alone Binder session In a linker session (specify -change) Scope: Applies to the program in which or before which it appears, to all subsequent programs in the compilation unit, and to all target files Dependencies: For the NMCOBOL compiler, RUNNAMED is appropriate only if the program was compiled with RUNNABLE (because a linkfile is not a run unit). References: RUNNABLE If your program is not compiled with the RUNNAMED directive and you run the program with the command RUN ru the process has no process name. If your program is compiled with the RUNNAMED directive or you run the program with the command RUN ru/NAME/ the operating environment gives it a timestamp name. The RUNNAMED directive causes the operating environment to give the process a timestamp name without your having to include “/NAME/” in the RUN command. Naming the process allows any requester that uses this run unit as a server to use the old method of process handling. The old method of process handling does not work for processes that run with a high PIN. You can specify RUNNAMED for any run unit, regardless of its environment. It need not run in the CRE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 108 Program Compilation SAVE SAVE Note. Do not use this directive in the OSS environment. SAVE directive specifies which initialization messages are stored for possible program manipulation. SAVE save-option-list ( ) save-option-list VST301.vsd save-option-list save-option , save-option VST302.vsd save-option-list cannot be continued onto subsequent lines, even if it is enclosed in parentheses. save-option PARAM STARTUP ASSIGNS ALL count VST303.vsd PARAM specifies that the PARAM message is to be saved. STARTUP specifies that the startup message is to be saved. ASSIGNS specifies that all ASSIGN messages are to be saved. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 109 Program Compilation SAVE count is an unsigned integer in the range 1 through 100, an estimate of the number of messages to be saved. The default is 19. The compiler uses count to estimate process data-space requirements for the saved ASSIGN messages. In the non-CRE environment, the saved ASSIGN messages are in the data block #HIGHBUF. (See Code and Data Blocks). In the CRE, the saved ASSIGN messages are in the data block #CRE_HEAP. If there is not enough space for all the ASSIGN messages held by the command interpreter, the program terminates with a run-time error message. ALL specifies that all messages are to be saved. Default: The compiler does not save initialization messages. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: None Whenever an HP COBOL program begins execution, its creator sends it a series of initialization messages: • • • A startup message (always) One PARAM message (if any parameters are active) An ASSIGN message for each assignment active In the non-CRE environment, space is reserved for 19 ASSIGN messages. If your program will have more than 19 assignments active at one time, include a MEM option in the RUN or RUND Command. Allow approximately one page of memory for every 19 ASSIGN messages. You cannot directly manipulate saved messages as COBOL data items, but you can use utility routines to retrieve and modify their contents (see Saved Message Utility (SMU) Overview). All combinations of SAVE options are legal, as are multiple SAVE directives. Redundant options are ignored, except that the last-seen count overrides any previous ones. The directive SAVE ALL 17, ASSIGNS 10 is equivalent to SAVE ALL, ASSIGNS 10 HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 110 Program Compilation SAVEABEND and NOSAVEABEND SAVEABEND and NOSAVEABEND SAVEABEND NOSAVEABEND VST304.vsd SAVEABEND generates a saveabend file if the process terminates abnormally. Sets the Inspect attribute. NOSAVEABEND does not generate a saveabend file if the process terminates abnormally. Default: NOSAVEABEND Placement: Anywhere Scope: The last SAVEABEND or NOSAVEABEND in the compilation unit applies to the entire compilation unit. Dependencies: SAVEABEND and NOINSPECT override each other (whichever is last is active). For the NMCOBOL compiler, SAVEABEND and NOSAVEABEND are appropriate only if the program was compiled with RUNNABLE. References: • • INSPECT and NOINSPECT RUNNABLE HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 111 Program Compilation SEARCH and NOSEARCH SEARCH and NOSEARCH Note. The NMCOBOL compiler ignores the NOSEARCH directive and issues a warning. SEARCH object-name-list ( object-name-list ) NOSEARCH VST305.vsd SEARCH adds the files that object-name-list specifies to the primary search list. (See Primary Search List.) NOSEARCH clears the primary search list for the COBOL85 compiler, but is ignored by the NMCOBOL compiler. object-name-list object-name , object-name VST306.vsd can be continued onto subsequent lines, but the left parenthesis must appear on the same directive line as the keyword SEARCH. Each continuation line for a SEARCH directive must have a question-mark (?) in the indicator area. If a SEARCH directive spans multiple lines, they must be consecutive (no blank lines, comment lines, or program text lines can intervene). HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 112 Program Compilation SEARCH and NOSEARCH object-name is a name that designates an TNS/R object file—either a file-system file name or (in the Guardian environment) a DEFINE name. In the OSS environment, object-name must be an OSS pathname. If the file-system file name is not fully qualified with system, volume, and subvolume names, the compiler uses the current default system, volume, and subvolume names or those specified by an =_OBJECT_SEARCH DEFINE (see =_OBJECT_SEARCH). For the COBOL85 compiler, BINSERV binds only the object code for programs that the program it is compiling actually calls, not necessarily the entire file designated by object-name. For the NMCOBOL compiler, the linker links the entire file designated by object-name. For the NMCOBOL compiler, object-name must designate either a linkfile or an archive file. When an archive file is searched, the entire archive file is generally not linked into the target object file. Only those member files are linked that contain procedures named in CALL or ENTER statements in the COBOL program being compiled. Whenever a procedure is needed from a member file, the entire member file is linked. If a native HP COBOL program references the object in a CALL or ENTER statement, the object must have been compiled with symbols. Default: NOSEARCH Placement: Anywhere Scope: Applies to the compilation unit Dependencies: None References: • • RUNNABLE CONSULT and NOCONSULT If more than one SEARCH directive appears, the file names are appended to the list in the order read. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 113 Program Compilation SECTION SECTION SECTION identifies a section of text to be copied from either a COPY library by a COPY statement or from a source library by a SOURCE directive. SECTION text-name , TANDEM ANSI VST307.vsd text-name is a COBOL word (see COBOL Words). TANDEM specifies that subsequent source text is in Tandem reference format, which is described in Reference Format for Source Program Lines. ANSI specifies that subsequent source text is in ANSI reference format, which is described in Section 16, ANSI Reference Format. Default: None Placement: Must be on a directive line of its own. If it appears in the text of the compilation source file (the IN file), it is ignored. Scope: Applies only to the section of text that it specifies Dependencies: None If you do not specify TANDEM or ANSI in the SECTION directive, the compiler assumes that the format of the library text is the same as the current source-text format. Although you can override this by inserting a compiler directive as the first line following the SECTION directive, the input format control directive (ANSI or TANDEM) of the SECTION directive is usually more convenient for this purpose. In either case, selecting Tandem or ANSI format as an option has an effect only for the duration of the fetching of that portion of library text. Upon completion of the fetching operation, the compiler reverts to the previous format. (See COPY Statement and SOURCE). If two or more SECTION directives in a text library contain the same text-name, the text following the first one in the library (the one on the edit line that has the lowest line number) is the text fetched by a COPY statement or SOURCE directive. If any SECTION directive in a text library contains a text-name that is not a legal COBOL word, the first time the compiler attempts to fetch any member from the library, the compiler reports an error, even if the offending text-name is not the one sought. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 114 Program Compilation SETTOG SETTOG SETTOG turns on all specified toggles, which the IF directive uses. SETTOG toggle-number-list VST308.vsd toggle-number-list toggle-number , toggle-number VST299.vsd If toggle-number-list is omitted, all toggles are turned on. toggle-number is an integer in the range 1 through 15. Default: None Placement: Must either be on a directive line of its own or be the last of a sequence of directives. Scope: Applies until RESETTOG overrides it Dependencies: None References: RESETTOG SETTOG or RESETTOG on the command line does not override any such directives within the source stream. Command line directives are the exact equivalent of a directive in the source stream immediately before the first line of the source. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 115 Program Compilation SHARED SHARED Note. The COBOL85 compiler does not recognize this directive. SHARED CALL-SHARED NON-SHARED VST804.vsd SHARED generates shared code (PIC) for a DLL. CALL-SHARED generates shared code (PIC). NON-SHARED generates nonshared code (non-PIC). Note. You cannot link PIC and non-PIC object files into a single object file. Default: NON-SHARED Placement: Anywhere Scope: The last SHARED, CALL-SHARED, or NON-SHARED in the compilation unit applies to the entire compilation unit. Dependencies: References: • • • • • • If RUNNABLE is active, SHARED uses the linker to create a PIC library file (DLL); otherwise, SHARED creates a PIC linkfile. Do not use with CALL-SHARED, NON-SHARED, or UL. CALL-SHARED NON-SHARED RUNNABLE UL HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 116 Program Compilation SHOWCOPY and NOSHOWCOPY If you put an HP COBOL program in a DLL, you must export the program name when you build the DLL; otherwise, other programs cannot call the HP COBOL program. To export the HP COBOL program name, use one of these ld commands: Environment ld Commands Guardian ld (-export program-name ) or ld (-export_all) OSS or PC -Wld="-export program-name " or -Wld="-export_all" SHOWCOPY and NOSHOWCOPY SHOWCOPY NOSHOWCOPY VST310.vsd SHOWCOPY displays COPY statements as comments in the listing before the copied text. NOSHOWCOPY suppresses the display of COPY statements. Default: SHOWCOPY Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: SHOWCOPY works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 117 Program Compilation SHOWFILE and NOSHOWFILE SHOWFILE and NOSHOWFILE SHOWFILE NOSHOWFILE VST311.vsd SHOWFILE displays the identity of the file from which source text is being read under the control of the SOURCE directive. NOSHOWFILE suppresses the display of the identity of the file from which source text is being read under the control of the SOURCE directive. Default: NOSHOWFILE Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None SHOWFILE applies only to source file transitions due to the effect of SOURCE directives. The compiler does not generate lines to report transitions caused by COPY statements. Whenever the compiler begins reading a different source file in response to a SOURCE directive and whenever it resumes reading from the prior source file after a SOURCE directive’s effect terminates, it inserts a line of this format into the listing: Source file: [n] file-name yyyy-mm-dd hh:mm:ss n is the file ordinal assigned by the compiler to the source file. Every time the compiler encounters a SOURCE directive, it increments the value of n by 1. file-name is the fully qualified source file name. yyyy-mm-dd is the date when the source file was last modified. hh:mm:ss is the time when the source file was last modified. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 118 Program Compilation SOURCE SOURCE SOURCE causes the compiler to begin accepting source text from a different EDIT file. The compiler can read either the entire file or one or more sections of the file (demarcated by SECTION directives). You can also use the predefined SEARCH DEFINEs to specify one or more subvolumes to be searched for unqualified files (see Predefined SEARCH DEFINEs). SOURCE edit-file-name ( section-name-list ) VST312.vsd edit-file-name is a file-system file name that identifies an accessible EDIT file. If any of the system, volume, or subvolume components are omitted, the compiler supplies the missing ones from its process defaults. edit-file-name can be the name of a DEFINE of the class MAP. section-name-list section-name , section-name VST313.vsd section-name-list can be continued onto subsequent lines, provided that the edit-file-name and the left parenthesis appear on the same directive line as the keyword SOURCE. Each continuation line for a SOURCE directive must have a question-mark (?) in the indicator area. If a SOURCE directive spans multiple lines, they must be consecutive (no blank lines, comment lines, or program text lines can intervene). The default for section-name-list is the entire file. section-name is the name of a section in an EDIT file (a text-name in the directive SECTION). Default: None Placement: Must be the last directive on its line. Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 119 Program Compilation SOURCE When the compiler encounters a SOURCE directive, it suspends reading of the current source file and begins reading lines from the specified file. If no section-name list appears, the compiler incorporates the entire file into its stream of source text lines. If a section-name list does appear, the compiler incorporates text from the designated sections only, in the order in which the sections appear within the specified file (not in the order of the list). When the compiler reaches the end of the file specified in the SOURCE directive, or has copied all specified sections, it resumes reading from the prior source file. Usage Considerations: • Effect on Compilation Output Listing If a SHOWFILE directive is active, when the compilation encounters an input line containing a SOURCE directive, (assuming that the LIST and NOSUPPRESS directives are active) the compiler lists the directive line, then a line showing the fully qualified name of the new source file and the date and time it was last modified. When no SHOWFILE directive is active (the default condition), the directive line containing the SOURCE directive appears in the output, but the additional line does not. The text from the section summoned by the SOURCE directive is listed, subject only to the LIST and SUPPRESS directives. • Nesting of SOURCE Directives The text introduced by a SOURCE directive can include one or more SOURCE directives. The compiler processes nested SOURCE directives when it encounters them. The maximum nesting depth is three; that is, at most three source files can be open at any given time as a consequence of SOURCE directives (source files open in response to COPY statements are not counted in this respect). • Relationship Between SOURCE Directive and COPY Statement The effect of the SOURCE directive is neither a subset nor a superset of the effect of the COPY statement; they are completely independent. The SOURCE directive does not provide a REPLACING capability. The text that a COPY statement delivers can include one or more SOURCE directives. The text that a SOURCE directive delivers can include one or more COPY statements. A COPY statement is not permitted to deliver a SOURCE directive that delivers another COPY statement, because this would create the effect of nested COPY statements. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 120 Program Compilation SOURCE A SOURCE directive cannot appear anywhere in the text of a COPY statement (between the word COPY and its terminating period in the input stream) or a REPLACE statement (between the word REPLACE and its terminating period in the input stream); however, the compiler detects and reports its appearance within pseudo-text only if that pseudo-text is introduced into the source as the result of expanding the COPY statement or by the editing effects of the REPLACE statement. • SOURCE Directive Behavior in IF/IFNOT/ENDIF Sequences The compiler ignores a SOURCE directive specified within conditional text (within the scope of an IF or IFNOT directive) if the controlling condition is false. • Interaction of SOURCE and COLUMNS Directives When a COLUMNS directive applies to the line or lines containing a SOURCE directive, the same logical line length attribute is the default for the lines introduced in response to that directive; however, a COLUMNS directive appearing within the designated file overrides the default. In this circumstance, the compiler honors the “inner” logical line length for the remainder of the text imported by the SOURCE directive, after which the “outer” logical line length becomes active again. • Effect of ANSI and TANDEM Format Specifying Directives The source text format (ANSI or Tandem) which applies to the line or lines containing a SOURCE directive is the default for the lines introduced in response to that directive; however, ANSI or TANDEM directives appearing within lines read from the file (or ANSI or TANDEM options specified in SECTION directives) take effect when encountered. These then apply to subsequent lines until they are overridden, the end of the source file is reached, or the end of a selected section is reached (which causes the compiler to revert to the default source format before it resumes reading the next selected section). In all cases the “outer” source format attribute becomes active again after processing of the SOURCE directive completes. • Diagnostic Messages and SOURCE Directives If the compiler cannot at least minimally process a SOURCE directive (because the edit-file-name specified is invalid, or the file cannot be accessed, or the file is not an EDIT file, and so forth), the compilation terminates. If the compiler is unable to access a section specified in the SOURCE directive (because the section-name is invalid or the section is not in the file) the compiler issues a diagnostic message, but does not terminate the compilation. • Format of a Source Library A source library has the same format as a COPY library; in fact, the only difference between a source library and a COPY library is context—a source library is referenced by a SOURCE directive and a COPY library is referenced by a COPY statement. For the syntax of a source library, see Library Format. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 121 Program Compilation SQL and NOSQL During program compilation, the compiler identifies a section by locating the SECTION directive whose text-name matches the section-name specified in the SOURCE directive. SQL and NOSQL Note. The NMCOBOL compiler ignores the NOSQL directive and issues a warning. SQL sql-option-list ( sql-option-list ) NOSQL VST315.vsd SQL tells the compiler to expect SQL/MP statements in the compilation unit. NOSQL tells the COBOL85 compiler not to expect SQL/MP statements in the compilation unit. This is the default. The NMCOBOL compiler ignores it. sql-option-list sql-option , sql-option VST316.vsd tells the compiler how much memory to allocate to the SQL/MP compiler interface and what SQL/MP information to print to the listing file. sql-option RELEASE1 RELEASE2 PAGES num-pages SQLMAP WHENEVERLIST VST317.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 122 Program Compilation SQL and NOSQL RELEASE1 is for the COBOL85 compiler only, and causes it to accept only SQL/MP Release1 features; however, the resulting object file can be executed with SQL/MP Release 1, Release 2, or 300 (or later).. RELEASE2 causes the compiler to accept only SQL/MP Release 2 features; however, the resulting object file can be executed with SQL/MP Release 2 or 300 (or later). If you do not specify RELEASE1 or RELEASE2, the COBOL85 compiler selects SQL/MP Release 2 and the NMCOBOL selects the latest SQL/MP product version (300 or later). PAGES allocates num-pages of memory to the SQL compiler interface for processing SQL/MP statements. Each page is 2048 bytes. num-pages has a minimum (and default) value of 560 and the maximum value of 1000. If you allocate too few pages, an error results. SQLMAP includes information about SQL/MP statements in the listing file so that they can be matched with MEASURE output. MEASURE output identifies each SQL/MP statement by its Run-Time Data Unit (RTDU) name and SLT index. An RTDU is an internal SQL/MP data structure residing in the code file. An SLT index maps a single SQL/MP statement to a table in the RTDU. By default, the SQLMAP option is off. WHENEVERLIST lists the WHENEVER options that are active for each embedded SQL/MP statement printed to the listing file. WHENEVER options are a feature of SQL/MP. For information on them, see the SQL/MP Reference Manual or the SQL/MX Programming Manual for C and COBOL. By default, the WHENEVERLIST option is off. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 123 Program Compilation SQLMEM Default: None. If the program contains SQL/MP statements, the SQL directive is required; otherwise, it is unnecessary. Placement: The COBOL85 compiler accepts SQL and NOSQL in either the source code (before the first Identification Division in the program) or the compiler command line; the NMCOBOL compiler accepts them only in the compiler command line. Scope: Applies to the compilation unit Dependencies: SQL works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS SQLMEM Note. The NMCOBOL compiler ignores this directive and issues a warning. The concept of extended memory does not exist for TNS/R processes. SQLMEM USER EXT VST318.vsd USER declares SQL/MP data structures in the Working-Storage Section (user data segment). This option is not recommended, because SQL/MP data structures can exhaust the Working-Storage Section. EXT declares SQL/MP data structures in the Extended-Storage Section (extended data segment), which is created for every HP COBOL program at run time whether it declares one or not. This option is recommended. Default: SQLMEM EXT Placement: The first SQLMEM in a program must be preceded by SQL. Subsequent SQLMEMs can appear anywhere in the program. Scope: Applies to all SQL/MP statements between it and the next SQLMEM Dependencies: SQLMEM is allowed only in programs that also contain SQL. References: SQL and NOSQL HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 124 Program Compilation SUBSET SUBSET SUBSET causes the compiler to report in the output listing any source statement that contains syntax that is obsolete or does not conform to the restrictions of a specified subset. SUBSET parameter-list ( parameter-list ) VST319.vsd parameter-list parameter , parameter VST320.vsd You cannot continue parameter-list onto subsequent lines, even if you enclose it in parentheses. parameter HIGH EXTENDED DEB1 SEG1 SEG2 OBSOLETE VST321.vsd HIGH reports syntax not defined in the High subset of ISO/ANSI COBOL (NUC 2, SEQ 2, REL 2, INX 2, IPC 2, STM 2), with respect to the required functional modules. EXTENDED accepts all defined syntax without comment (HP extensions plus those of HIGH), with respect to the required functional modules. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 125 Program Compilation SUBSET DEB1 accepts all syntax defined in level 1 of the Debug module without comment. If DEB1 is not specified, the compiler reports syntax defined in level 1 of the Debug functional module (DEB 1). Syntax defined in level 2 of the Debug module causes the compiler to report an error, because HP COBOL does not support level 2 of this module. SEG1 accepts all syntax defined in level 1 of the Segmentation module (SEG 1) without comment, but reports syntax defined in level 2 (SEG 2). If SEG1 is not specified, the compiler reports syntax defined in the Segmentation functional module. Although HP COBOL does not support the Segmentation functional module, syntax that has no semantic effect is not diagnosed. This behavior simplifies the conversion of existing programs to HP COBOL. SEG2 accepts all syntax defined in the Segmentation module without comment. If SEG2 is not specified, the compiler reports syntax defined in level 2 of the Segmentation functional module. OBSOLETE accepts all obsolete syntax without comment unless it fails to conform to the specified subset; in that case, the compiler reports nonconformance rather than obsolescence. If OBSOLETE is not specified, the compiler reports syntax classified as obsolete, regardless of whether it conforms to the specified subset in other respects. The specified parameters can appear in any order. If two or more parameters are mutually incompatible, the last one overrides the others (redundancy is permitted). If neither HIGH nor EXTENDED is specified, EXTENDED is assumed by default. Default: None Placement: Must appear before the first COBOL source program (that is, before the first Identification Division header). Scope: The last valid SUBSET in the program applies. Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 126 Program Compilation SUBSET Usage Considerations: • Invalid SUBSET Directives If a SUBSET directive appears in an invalid context, the compiler issues an appropriate message and, after analyzing the directive, ignores it and cancels the effect of any previously accepted SUBSET directive (since an error has occurred). Upon the occurrence of any error, the compiler cancels any active SUBSET directive and discards any messages not yet issued. • Messages After the compiler has processed a separately compiled program that contains unauthorized syntax (but no actual errors), it displays the message *** The preceding program does not conform to the specified subset *** and then describes each nonconforming element. Each reported instance of nonconformance or obsolescence identifies the context of the syntax, describes its location in the source text, and characterizes the syntax as “obsolete” or “nonconforming.” If an instance is both obsolete and nonconforming, only “obsolete” is reported. A message has either of these forms: context on line nnnnn at column xx contains obsolete syntax Syntax on line nnnnn at column xx is defined in level context on line nnnnn at column xx contains nonconforming syntax Syntax on line nnnnn at column xx is defined in level context is a header (such as “Data Division header”), statement (such as “ADD statement”), clause (such as “LINAGE clause”), or the general phrase “Source text.” nnnnn is a five-digit line number. xx is a two-digit column number. level is HIGH, EXTENDED, DEB1, SEG1, or SEG2, as appropriate. Syntax on line nnnnn at column xx is defined in level includes the location phrases only if they differ from the information in the first line. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 127 Program Compilation SUBTYPE The messages generated in accordance with the SUBSET directive are issued as a block after each separately compiled program. To report ... Use the directive ... Obsolete syntax SUBSET EXTENDED, DEB1, SEG2 Syntax unlikely to be portable SUBSET HIGH, DEB1, SEG2, OBSOLETE SUBTYPE Note. Do not use this directive in the OSS environment. SUBTYPE causes the main program created by the current compilation to execute as a process of a specified subtype. SUBTYPE subtype-number VST323.vsd subtype-number is an integer in the range 0 through 63. You can define the meaning and behavior of process subtypes 48 through 63. HP defines the meaning and behavior of process subtypes 1 through 47 (see the Guardian Programmer’s Guide). Default: SUBTYPE 0 Placement: Anywhere Scope: The last SUBTYPE in the program applies. Dependencies: For the NMCOBOL compiler, SUBTYPE works only with RUNNABLE. References: RUNNABLE The compiler installs the value of subtype-number in the object file header. When the object file executes as a named process, it is assigned the process subtype specified by the value of subtype-number. Any user can create a named process that has a subtype in this range. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 128 Program Compilation SUPPRESS and NOSUPPRESS SUPPRESS and NOSUPPRESS SUPPRESS NOSUPPRESS VST324.vsd SUPPRESS overrides the LIST directive, suppressing all compiler listing output except the compiler leader text, diagnostic messages, and the compiler trailer text. NOSUPPRESS overrides the SUPPRESS directive. Default: NOSUPPRESS Placement: Accepted anywhere, but to suppress the compiler listing without altering the source text, put SUPPRESS on the command line Scope: Applies until its opposite overrides it Dependencies: SUPPRESS overrides LIST (and therefore, it also overrides CODE, CROSSREF, ICODE, LMAP, MAP, SHOWCOPY, and SQL). References: • • • • • • • • LIST and NOLIST CODE and NOCODE CROSSREF and NOCROSSREF IICODE and NOICODE LMAP and NOLMAP MAP and NOMAP SHOWCOPY and NOSHOWCOPY SQL and NOSQL HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 129 Program Compilation SYMBOLS and NOSYMBOLS SYMBOLS and NOSYMBOLS SYMBOLS NOSYMBOLS VST325.vsd SYMBOLS includes a symbol table in the object file used by a symbolic debugger. NOSYMBOLS excludes the symbol table from the object file used by a symbolic debugger. Default: NOSYMBOLS Placement: Accepted anywhere, but to affect a program other than the first program in a compilation unit, SYMBOLS must follow either an ENDUNIT directive or an END PROGRAM statement, which signals the end of the preceding program’s Procedure Division. If you want a symbol table for a given separately compiled program, put SYMBOLS before its Identification Division header. If the compiler encounters a subsequent SYMBOLS or NOSYMBOLS directive within the text of that separately compiled program, it issues a warning and ignores that directive. Scope: Applies until its opposite overrides it Dependencies: SYMBOLS does not work when SYNTAX is active. References: • • ENDUNIT SYNTAX You can include or exclude the symbol table from the object file on a program-unit-byprogram-unit basis. If the SYMBOLS directive is active, the compiler does not perform certain object code optimizations, so the object program might execute slightly more slowly and be slightly larger in size. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 130 Program Compilation SYNTAX SYNTAX SYNTAX COMPILE VST326.vsd SYNTAX checks the syntax of the source text. No target file is produced. COMPILE compiles the program unit and included its code and data blocks in the target file being created. Default: COMPILE Placement: Outside the boundaries of a separately compiled program; that is, not between the Identification Division header of a separately compiled program and its end, which is marked by one of: • • • The corresponding END PROGRAM statement ENDUNIT The end of the source file Scope: The last COMPILE or SYNTAX in the compilation unit applies to the entire compilation unit. Dependencies: SYNTAX overrides RUNNABLE. References: • • ENDUNIT RUNNABLE HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 131 Program Compilation TANDEM TANDEM TANDEM ANSI VST327.vsd TANDEM specifies that subsequent source text is in Tandem reference format, which is described in Reference Format for Source Program Lines. ANSI specifies that subsequent source text is in ANSI reference format, which is described in Section 16, ANSI Reference Format. Default: TANDEM Placement: Anywhere Scope: TANDEM or ANSI within a section of text obtained from a copy library or source library is effective only for the length of that text section. When the compiler reverts to the source file where it found the COPY verb or SOURCE directive, the previously active reference format applies. Dependencies: None References: ANSI TRAP2 and NOTRAP2 Note. The NMCOBOL compiler, which has traps set by default, ignores these directives and issues warnings. Use the NOTRAP2 directive only during the process of conversion from COBOL 74 to HP COBOL. It is provided to enable programs that do not include SIZE ERROR phrases to be compiled and executed in HP COBOL without investing programmer time in analyzing the potential for overflow problems. The availability of this directive might be discontinued. TRAP2 NOTRAP2 VST328.vsd TRAP2 specifies that the compiler expects the operating environment to trap arithmetic overflow (trap 2). (By default, the COBOL85 compiler expects this and the HP COBOL 74 compiler does not.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 132 Program Compilation TRAP2 and NOTRAP2 NOTRAP2 specifies that the compiler does not expect the operating environment to trap arithmetic overflow in the current program. If the current program was called from an environment in which trapping was enabled, however, programs that the current program calls will have trapping enabled (unless overridden by the NOTRAP2-74 directive). Default: TRAP2 Placement: Anywhere Scope: The last TRAP2 or NOTRAP2 before the END PROGRAM statement for the outermost program applies to the entire separately compiled program (the outermost program of a compilation and any programs contained within it). Dependencies: NOTRAP2-74 overrides TRAP2. References: TRAP2-74 and NOTRAP2-74 In object code produced by the HP COBOL 74 compiler, if a size error condition occurs in an arithmetic operation for which no SIZE ERROR phrase is present, the computation produces an undefined result (unpredictable value). In object code produced by the COBOL85 compiler, if a size error condition occurs in an arithmetic operation that is not within a statement that has a SIZE ERROR phrase, the program suspends execution with a trap 2 (arithmetic overflow) condition. In the CRE, if the command PARAM INSPECT ON is active, the process enters the selected debugger (see Debugger Selection); if PARAM INSPECT OFF is active, it does not. In the non-CRE environment, the process enters the selected debugger unless the program calls the COBOL85^ARMTRAP routine. Trapping behavior is governed by the trap-enable bit in the environment register of each process. The process uses this bit to direct the hardware whether or not to trap arithmetic overflows. The initialization routines of HP COBOL (executed by the main program when the process is starting up) request the trapping; those of a COBOL 74 main program suppress the trapping. When there are no TRAP2 or TRAP2-74 directives present, nothing in the generated code or the run-time routines changes the trap-enable bit. When an HP COBOL program is compiled with the NOTRAP2 directive active, the compiler generates code at the beginning of each HP COBOL program (including nested programs) to record the value of the trap-enable bit, and to clear that bit if it was set. Furthermore, it localizes the trap suppression to just the current routine. Before each CALL or ENTER that the program executes, if the recorded setting is “use trapping,” the compiler generates code to set the bit before executing the call and to clear the bit again when control returns to the current program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 133 Program Compilation TRAP2-74 and NOTRAP2-74 If you compile the main program with the COBOL85 compiler, and include the NOTRAP2 directive, the compiler does not activate the arithmetic overflow trapping mechanism. This then approximates the behavior of COBOL 74, although any undefined results could have values that are different from those a COBOL 74 program would produce. An example of this behavior is a counter that the program increments by 1 until the value of the counter exceeds its maximum value, and rolls over to zero. TRAP2-74 and NOTRAP2-74 Note. The NMCOBOL compiler, which cannot call COBOL 74 programs, ignores these directives and issues warnings. Use the NOTRAP2-74 directive only during the process of conversion from COBOL 74 to HP COBOL. It is provided to enable programs that do not include SIZE ERROR phrases to be compiled and executed in HP COBOL without investing programmer time in analyzing the potential for overflow problems. The availability of this directive might be discontinued. TRAP2-74 NOTRAP2-74 VST329.vsd TRAP2-74 overrides the NOTRAP2-74 directive. NOTRAP2-74 specifies that if the current HP COBOL program traps arithmetic overflow, then the HP COBOL code must suspend arithmetic overflow trapping before calling a COBOL 74 program and restore trapping upon return from the COBOL 74 program. Default: TRAP2-74 Placement: Anywhere Scope: The last TRAP2-74 or NOTRAP2-74 before the END PROGRAM statement for the outermost program applies to the entire separately compiled program (the outermost program of a compilation and any programs contained within it). Dependencies: NOTRAP2-74 overrides TRAP2. References: TRAP2 and NOTRAP2 In object code produced by the HP COBOL 74 compiler, if a size error condition occurs in an arithmetic computation for which no SIZE ERROR phrase is present, the computation produces an undefined result (unpredictable value). HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 134 Program Compilation UL In object code produced by the COBOL85 compiler, if a size error condition occurs in an arithmetic computation for which no SIZE ERROR phrase is present, the program suspends execution and enters the selected debugger with a trap 2 (arithmetic overflow) condition. When a set of separately compiled COBOL programs constitute a run unit, if any of the programs is the product of compilation by the COBOL85 compiler, the main program must be a product of the COBOL85 compiler. Also, although an HP COBOL program can call a COBOL 74 program, a COBOL 74 program cannot call an HP COBOL program. During conversion from COBOL 74 to HP COBOL, it can occur that the main program has been converted to HP COBOL, but some of the subprograms are in COBOL 74. When that is the case, if an arithmetic overflow occurs in the COBOL 74 code, the program drops into the debugger. If the program is working correctly, this is obviously an awkward situation. If you compile the main program with the COBOL85 compiler, and include the NOTRAP2 directive, the compiler does not activate the arithmetic overflow trapping mechanism. This then approximates the behavior of COBOL 74, although the undefined result might have a different value. If you want the HP COBOL program to have overflow trapping, but you want the COBOL 74 programs it calls not to have the trapping, include the NOTRAP2-74 directive in the COBOL85 compilation. UL Note. The COBOL85 compiler does not recognize this directive. UL directive tells the NMCOBOL compiler that the resulting object code will be in a native library. The NMCOBOL compiler does not put any data in the small data area, and it tells the linker to export the entry point names of all separately compiled programs in the compilation unit. UL VST735.vsd Default: None Placement: Before the first IDENTIFICATION DIVISION header of the first program in the compilation unit Scope: Applies to the compilation unit Dependencies: • References: • • • If RUNNABLE is active, UL uses the linker to create a PIC library file (DLL); otherwise, UL creates a PIC linkfile. Do not use with CALL-SHARED, NON-SHARED, or SHARED. CALL-SHARED SHARED HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 135 Program Compilation WARN and NOWARN For instructions on building and specifying native user libraries, see User Library. WARN and NOWARN WARN NOWARN VST330.vsd WARN reports compilation and Binder warnings in the listing. NOWARN suppresses compilation and Binder warnings in the listing. Default: WARN Placement: Anywhere Scope: Applies to the compilation unit Dependencies: If LIST is not enabled, the last line of source text processed is also listed to provide a point of reference for each warning message. References: LIST and NOLIST HP COBOL Manual for TNS and TNS/R Programs —522555-006 11- 136 12 Program Execution This section applies to the Guardian environment. If you are executing HP COBOL programs in the OSS environment, see Running HP COBOL Programs. Topics: • • • • • TACL commands related to program execution: ° ° ° ° ° RUN or RUND Command ASSIGN Command PARAM Command CLEAR Command DEFINEs Initial State Status of Internal Entities During Program Execution Status of External Entities During Program Execution Called Program Termination For detailed information about the TACL commands, see the TACL Reference Manual. For more information about running COBOL programs in the Guardian environment, see Section 25, Executing and Debugging HP COBOL Programs. When a system executes a loadfile, the running program is called a process. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12- 1 Program Execution RUN or RUND Command RUN or RUND Command Both the RUN and RUND commands run a loadfile as a process. The RUND command calls the selected debugger (see Debugger Selection)before beginning execution. RUN program-file RUND / run-option-list / program-parameter-list VST331.vsd RUN runs the program without the debugger. RUND runs the program with the debugger. program-file is the name of the loadfile to run. program-file can be represented as a filesystem file name or (in the Guardian environment) a DEFINE name. run-option-list run-option , run-option VST332.vsd run-option IN OUT accept-device display-device VST333.vsd is an option of the RUN command, described in the TACL Reference Manual. For COBOL programs, two of the run options, IN and OUT, have special significance: HP COBOL Manual for TNS and TNS/R Programs —522555-006 12- 2 Program Execution RUN or RUND Command accept-device has a value that designates a terminal or a process and can be a filesystem file name or (in the Guardian environment) a DEFINE name. accept-device specifies the device from which an unqualified ACCEPT statement retrieves input. If you omit this option, unqualified ACCEPT statements retrieve input from the home terminal (unless PARAM EXECUTION-LOG specifies a different device). display-device can be a file-system file name or (in the Guardian environment) a DEFINE name. Its value designates a terminal, line printer, process, existing entrysequenced disk file, or operator console to which unqualified DISPLAY statements are to deliver output. If you omit display-device, unqualified DISPLAY statements deliver output to the home terminal (unless PARAM EXECUTION-LOG specifies a different device). program-parameter-list program-parameter , program-parameter VST806.vsd program-parameter is a parameter of the program that is to be run. Example 12-1. RUN Commands RUN PROG1 RUN RUNUNIT /IN $TERM1/ RUN MYPROG /OUT =CHECKS-PRINTER/ Usage Considerations: • Effect of Commands on Run-Time Environment Certain run-time commands establish an environment in which the running process operates. For example, the ASSIGN command stores logical file assignments, the PARAM command stores string values and associates them with parameter names, the CLEAR command clears assignments and parameter values, and a group of commands handle DEFINEs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12- 3 Program Execution ASSIGN Command When a process begins executing, it obtains the current ASSIGN and PARAM values from the Guardian environment, and can act on the information they contain. See ASSIGN Command and PARAM Command. For additional information on TACL run-time commands, see the TACL Reference Manual or the Guardian User’s Guide. If no run-time commands are specified, the file-control entries in the program are used to associate the COBOL file names with file-system file names, and all external switches but one are set to OFF. The only exception is the NONSTOP parameter, which defaults to ON if the program was compiled with the NONSTOP directive in the Guardian environment. • When Commands Take Effect Commands take effect when encountered and can be overridden by subsequent commands. Keywords, file names, and numbers cannot be continued from one line to the next. • COMMENT Run-Time Command A COMMENT run-time command is available to include documentation in the TACL command stream. ASSIGN Command This section applies to programs that were not compiled with the ENV LIBRARY or UL directive. Programs compiled with the ENV LIBRARY or UL directive ignore ASSIGN commands. Note. ASSIGN commands for files in a user library are ignored. The ASSIGN command creates an ASSIGN message in your current run-time environment. A process can use the information in an ASSIGN message to override the file-system file name, or other attributes, of a file specified in the source program. This command is fully discussed in the TACL Reference Manual. When a process begins to execute, it can request its ASSIGN messages and use their contents to modify the information it possesses about its files before opening them. During the initialization of any process compiled from a COBOL source, the run-time routines automatically handle any ASSIGN messages made available by the Guardian environment. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12- 4 Program Execution ASSIGN Command This partial syntax diagram of the ASSIGN command describes features of greatest interest to the COBOL programmer: ASSIGN cobol-file-name program-name . * , system-file , characteristic VST334.vsd program-name is the program-name in the PROGRAM-ID paragraph in the Identification Division, for which the file assignment is to take effect. This is distinct from the name of the loadfile. Do not specify program-name for an external file. * means that the file assignment applies to all programs in the loadfile. In the nonCRE environment, you must specify * for an external file. In the CRE, you must not specify * for an external file. If neither program-name nor * is present, then cobol-file-name must be unique among all programs in the loadfile. cobol-file-name is the COBOL file name in a SELECT clause, also called the fd-name. system-file name #IN #OUT #TERM #TEMP $RECEIVE VST335.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 12- 5 Program Execution ASSIGN Command name is a spooler location or the name of a disk file, disk volume, tape device, DEFINE, process, or terminal. #IN #OUT #TERM #TEMP $RECEIVE are explained in the usage considerations. They must be uppercase. When only system-file is present, and all other clauses are omitted, the current file for cobol-file-name is assigned. characteristic EXT size-list CODE file-code EXCLUSIVE SHARED PROTECTED INPUT OUTPUT I-O REC record-size BLOCK block-size VST336.vsd size-list pri-extent-size ( ) pri-extent-size , sec-extent-size VST337.vsd specifies the extent size for disk file creation. Extent sizes are specified as a number of file pages to be allocated for one extent of the file. A file page is 2048 bytes of storage. pri-extent-size is an unsigned integer specifying the primary extent size. If EXT is omitted, pri-extent-size defaults to 4. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12- 6 Program Execution ASSIGN Command sec-extent-size is an unsigned integer specifying the secondary extent size. If EXT is omitted, sec-extent-size defaults to 20. If sec-extent-size is omitted, the secondary extent size defaults to the primary extent size. file-code is 101 (for an EDIT file) or an unsigned integer in the range 0 through 99 or in the range 1000 through 32767, which specifies a file code for disk file creation. If the CODE clause is omitted, a file-code of 0 is used. EXCLUSIVE SHARED PROTECTED specify an exclusion mode for disk file reading or writing. This can override an implied exclusion mode, but not an explicit exclusion mode specification in the OPEN statement. I-O INPUT OUTPUT specify an access mode for the disk file; however, the run-time routines ignore the value. The COBOL OPEN statement controls the access mode entirely. record-size is an integer accepted by TACL as specifying record length, but the run-time routines ignore the value. The record declaration in the COBOL program controls the record size entirely. block-size is an integer accepted by TACL as specifying block size. In the non-CRE environment, the run-time routines ignore the value and the BLOCK CONTAINS clause in the COBOL program controls the block size entirely. In the CRE, block-size determines the block size. Note. To see what ASSIGN commands are currently in force, enter just ASSIGN followed by a carriage return. Usage Considerations: • Places for ASSIGN Commands You can give ASSIGN commands individually at the TACL prompt before you enter the RUN command, or you can place the ASSIGN commands in an EDIT-format file and use the OBEY command to execute all the commands in the file. You could also include the RUN command in the OBEY command file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12- 7 Program Execution • ASSIGN Command Special COBOL Names for Operating System Files See Operating system file names and Special names for operating system files. Example 12-2. #TEMP 17>ASSIGN temp-file,#TEMP 18>RUN program ... * File created on run-time default volume OPEN I-O temp-file ... * File purged CLOSE temp-file ... * New empty file created OPEN I-O temp-file ... * File automatically closed and purged STOP RUN. ... • Interaction Between ASSIGN Command and OPEN Statement The interaction between the exclusion-specification of the ASSIGN command and the exclusion-mode of the OPEN statement is: ° If an exclusion-mode is given in the OPEN statement, that value is used regardless of any ASSIGN command settings. ° If the OPEN statement has no exclusion-mode but the ASSIGN command for the file does give an exclusion-specification, the ASSIGN command value is used. ° If neither the exclusion-mode of the OPEN statement nor the exclusionspecification of the ASSIGN command is present, the COBOL default mode is active (see OPEN). The temporary file in Example 12-3 is purged when it is closed. Example 12-3. ASSIGN Command With Special COBOL Names (page 1 of 2) 11>ASSIGN REPORT-OUT, $TERM4 12>RUN MYPROG 13>ASSIGN IN-MASTER,$DATA.ZZ.INFILE 14>RUN MYPROG1 15> 16>ASSIGN INPUT-FILE, #IN 17> == FD INPUT-FILE is the == file named in the == IN option. 18> 19>ASSIGN WORK-FILE, #TEMP 20> == FD WORK-FILE is to be == a temporary disk file == on the default volume. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12- 8 Program Execution PARAM Command Example 12-3. ASSIGN Command With Special COBOL Names (page 2 of 2) 21> 22>ASSIGN OUTPUT-FILE, #OUT 23> == FD OUTPUT-FILE is the == file named in the == OUT option. 24>ASSIGN RECEIVE-FILE, $RECEIVE 25> 26> 27> == Run the loadfile, == designating NEWINP as == the IN file (thus 28>RUN PROG3 /IN NEWINP,OUT NEWOUT/ == equating it with the 29> == fd-name INPUT-FILE) 30> == and NEWOUT as the OUT 31> == file (thus equating it 32> == with the fd-name 33> == OUTPUT-FILE). PARAM Command The PARAM command creates a PARAM message in your current environment. Note. PARAM commands for files in a user library are ignored. When a process compiled by the compiler begins to execute, the run-time routines automatically request the PARAM message and use its contents to set the options defined for HP COBOL. Application code within the program can also use the SMU procedures to copy the PARAM message into the Working-Storage area and examine it for additional parameters that apply to the program. Further, the program can manipulate the saved parameters and cause them to be passed to any processes it initiates using the CREATEPROCESS or CLU_PROCESS_CREATE_ routine. PARAM name-value-pair , name-value-pair VST338.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 12- 9 Program Execution PARAM Command name-value-pair is one of the name-value pairs recognized by the run-time routines, or a userdefined parameter name and value: SWITCH-nn ON DEBUG OFF NONSTOP INSPECT WAITED-IO EXECUTION-LOG system-file-name define-name * TAPE-DIALOGUE ON OFF PRINTER-CONTROL parameter-name cobol-file-name parameter-value VST339.vsd SWITCH-nn sets (ON) or clears (OFF) the specified switch. In the Guardian environment, the value of nn can be a one-digit integer between 1 and 9 or a two-digit integer between 01 and 15. In the OSS environment, the value of nn can be a one-digit integer between 1 and 9 or a two-digit integer between 10 and 15. (For an explanation of these switches, see SPECIAL-NAMES Paragraph. In the absence of a PARAM SWITCH-nn ON command, SWITCH-nn is off. DEBUG is used only if the program was compiled with the DEBUGGING clause and contains USE DEBUGGING sections. When set to ON, the program executes debug code (declaratives). In the absence of a PARAM DEBUG ON command, the debugging declaratives are not executed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -10 Program Execution PARAM Command NONSTOP controls whether or not a process runs as a process pair, provided that the NONSTOP directive was included in the compilation of the program. For information on using process pairs, see Section 32. If the program was compiled with the NONSTOP directive, the process runs as a process pair unless you use the PARAM NONSTOP OFF command. If this switch is set OFF, no checkpointing or backup creation occurs, and PROGRAM-STATUS is always set to “0000.” INSPECT determines what the run unit does after reporting fatal errors. If INSPECT is OFF, the run unit calls ABEND. If INSPECT is ON, the run unit calls the selected debugger (see Debugger Selection). WAITED-IO when set to ON, causes the HP COBOL program to do all its input-output in wait mode (allowing you to use AWAITIO with -1). The program cannot execute an OPEN statement that specifies TIME LIMITS or references $RECEIVE. Attempts to do so cause the program to terminate abnormally with a run-time error message. Note. WAITED-IO works only in the non-CRE environment. The CRE ignores it. EXECUTION-LOG specifies the destination of messages issued by the HP COBOL run-time library routines, which are: • • Diagnostic messages DISPLAY messages that do not specify a mnemonic-name when the default OUT device is the home terminal The default EXECUTION-LOG is the home terminal. system-file-name is the name of the file to which run-time messages are directed. It must be an existing entry-sequenced (TYPE E) file (that is, a file-system file name). If system-file-name does not begin with a dollar sign ($), backward slash (\), or number sign (#), then it must be enclosed in quotation marks unless it forms a COBOL word. For more information about operating system file names, see the Guardian Procedure Calls Reference Manual. define-name is the name of a DEFINE associated with the file to which run-time messages are directed. It is not enclosed in quotation marks. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -11 Program Execution PARAM Command * specifies that all run-time messages are to be discarded. TAPE-DIALOGUE applies only to the non-CRE environment, in which it sets (ON) or clears (OFF) the tape dialogue. If the tape dialogue is cleared, the tape assigned in either the SELECT clause, TACL ASSIGN directive, or DEFINE is assumed to be the correct tape. No dialogue appears for any tape, whether or not NO REWIND is specified; however, if a reel swap occurs, the tape dialog appears for that file connector. PRINTER-CONTROL specifies that the operating environment must return control to the program when the printer specified by the cobol-file-name is not ready or is out of paper. cobol-file-name is the FD name of a file in a COBOL program (not the operating system file name or a DEFINE name). When the PRINTER-CONTROL parameter is absent, the HP COBOL run-time routines provide automatic handling for printer fault conditions, without control returning to the program until the printer is again made ready. parameter-name is a parameter to be handled through the SMU. For information on the SMU, see Saved Message Utility (SMU) Overview. parameter-value is the value to be given to parameter-name. Note. To see what parameters are currently defined, enter just PARAM followed by a carriage return. Usage Considerations: • WAITED-IO and HP COBOL Fast I-O If a program for which WAITED-IO was specified attempts to open a file for HP COBOL Fast I-O, sequential block buffering of buffered cache is used instead, degrading performance by a factor of five to ten. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -12 Program Execution • PARAM Command EXECUTION-LOG Parameter There are three circumstances in which a COBOL program can interact with the home terminal without your explicitly instructing it to do so: ° A DISPLAY statement does not include an UPON phrase, so it defaults to the OUT file, which itself is defaulted to the home terminal. ° An ACCEPT statement does not include a FROM phrase, so it defaults to the IN file, which itself is defaulted to the home terminal. ° A run-time routine needs to report an error or to engage in dialog with the system operator, and normally does so through the home terminal. The EXECUTION-LOG parameter provides a means of redirecting such unintentional input-output activity from the home terminal to another device, called the execution log file. In the CRE, the EXECUTION-LOG parameter can also redirect unintentional inputoutput activity from #IN and #OUT to the execution log file. In the absence of an EXECUTION-LOG parameter, the execution log file is the home terminal. If the EXECUTION-LOG parameter specifies asterisk (*), such output is discarded. In this case, whenever the program attempts to engage the operator in dialog, such as for: ° ° ° ° Tape mount Device not ready No write ring Printer is out of paper The run-time routines return I-O status code “30” to the program. The special register GUARDIAN-ERR then contains a code indicating what action is expected. If a program has its EXECUTION-LOG parameter set to asterisk (*), and the program attempts to execute an ACCEPT statement that defaults to the home terminal, the run unit terminates abnormally. If the EXECUTION-LOG parameter specifies a file name, the processing of the designated file depends on the device-type assigned to the file: Exclusion Device Type In CRE In Non-CRE Environment Access 0 (process) Exclusive Shared Read/write 1 (operator console) Shared Shared Write 3 (disk) Exclusive Shared (file must exist) Write 4 (magnetic tape) Exclusive Shared Write 5 (line printer) Exclusive Shared Write 6 (terminal) Shared Shared Read/write HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -13 Program Execution PARAM Command The file is opened the first time the run unit attempts to write a message. This means that it will not be opened at all for most jobs. If the open operation fails, no messages can be written anywhere and run unit execution terminates abnormally. Once opened, the file remains open for the duration of the run unit. If any error occurs during a write or read operation on the execution log file, no messages can report this problem and the run unit terminates abnormally. If the access mode is read/write, the run-time routines use the WRITEREAD system routine to send messages requiring a response and WRITE for messages not requiring a response. If the access mode is write, the run-time routines use a WRITE request for all messages. Those requiring a response are assumed to have a response of end of file. If the device is a process, the process is responsible for analyzing the messages to determine if an operator response is needed. If the process is also a COBOL run unit, it can do this by using the MESSAGE-SOURCE option in its (the process’s) RECEIVE-CONTROL paragraph to get the appropriate information to use in an ENTER RECEIVEINFO call. If RECEIVEINFO returns a nonzero value for the read-count, a reply is expected. In this case, the process can return an appropriate string value (such as would be supplied by an operator) indicating what action to take. If a reply is null or the access mode of the execution log is write, the run-time routines assume that no action is desired and, if the operation is a file processing statement, return I-O Status 30 to the program (GUARDIAN-ERR contains the code indicating what action is expected). If the operation is an ACCEPT statement, the default values are returned to the receiving item. In the case of tape mount messages, the run unit terminates abnormally. • PRINTER-CONTROL Parameter When an application program is writing to a printer, and the printer leaves the ready state (perhaps it is out of paper or it is off line), the program does not automatically regain control. The HP COBOL run-time library issues a message to the home terminal to report the printer fault, and waits for the printer to be restored to the ready state. In certain circumstances, the application program needs to regain control and take some action when an active printer leaves the ready state. For example, the program might be printing checks and keeping record of the preprinted check numbers issued to each payee. The program asks the operator for the first check number in the sequence, then processes checks depending on the number to increase by 1 each time. When the printer comes to the end of a box of check forms (or suffers a paper jam and destroys some checks), the program needs to be informed that a particular write operation was not completed routinely so that it can ask the operator for the number of the next check it will be printing on. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -14 Program Execution PARAM Command The PRINTER-CONTROL parameter provides a way for the program to respond to printer faults. Suppose a PRINTER-CONTROL parameter specifies the file name CHEX. This causes the run-time library to keep track of each elementary control function or write request that it sends to the operating environment for the file CHEX. If one of those operations fails because the printer to which CHEX is assigned is not ready, the WRITE statement completes with I-O status code “30” (permanent error condition) and a GUARDIAN-ERR value of 100 (not ready) or 102 (out of paper). To make use of the PRINTER-CONTROL parameter, the application program must use a declarative procedure, preferably one of the form USE AFTER STANDARD ERROR PROCEDURE ON CHEX that responds only to errors on the printer file. The procedure receives control when the operating environment detects the printer problem. The procedure determines that the printer’s I-O status code is “30” and handles the GUARDIAN-ERR values of 100 and 102. It might notify the operator of which problem has occurred. Although the record area still contains the record that was being written, there is no way for the procedure to determine whether or not the record actually has been written to the printer. For example, if “WRITE a-rec BEFORE ADVANCING PAGE” was specified, perhaps the printer was off line before the write operation began, or perhaps the record was written but the printer reached the end of the paper before it could position to the top of a new sheet. There is, however, a way to assure that the record does get written only once and that any related control operations occur only once. The program must reissue exactly the same form of the WRITE statement (same record name, same ADVANCING clause, and so on). The run-time library does not repeat any control function or system write request that successfully completed the first time, and reissues the control function or system write request that caused the status to occur, plus any subsequent operations that were not completed. One easy way to use this mechanism is to have the declarative respond to the combination of I-O status code “30” and GUARDIAN-ERR value of 100 or 102 by moving a FALSE value to a condition variable (associated to the condition-name PRINT-OK) and conducting the dialog with the operator, then instead of coding just a WRITE statement, code the sequence: PERFORM UNTIL PRINT-OK SET PRINT-OK TO TRUE WRITE CHEX BEFORE ADVANCING 10 END-PERFORM HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -15 Program Execution • PARAM Command Additional Considerations ° A parameter value that contains any embedded commas or leading or trailing spaces must be enclosed in quotation marks. Between the delimiting quotation marks, two consecutive quotation marks ("") represent any one quotation mark (") that is part of the value. The delimiting quotation marks are not stored. ° TACL provides internal storage for 1024 bytes of parameters. Each parameter occupies a number of bytes equal to: 2 + number-of-characters-in-parameter-name + number-of-characters-in-parameter-value ° ° Multiple PARAM name and value pairs must be delimited by commas. The compiler makes use of certain parameters and their values in performing the compilation (see PARAM Commands). For more information on the PARAM command, see the TACL Reference Manual. Example 12-4. PARAM Command 85> 86> 87> 88> 89> == Set the DEBUG switch, and set SWITCH-02 PARAM DEBUG ON, SWITCH-02 ON == Set user parameter THEDATE PARAM THEDATE 1991DEC02 == Route home terminal messages to a file 90> 91> 92> 93> 94> ... 99> PARAM EXECUTION-LOG $ARK.GKH.D0289 == Return control when the file that "myprog" == calls PRINT-FL leaves the ready state PARAM PRINTER-CONTROL PRINT-FL RUN myprog CLEAR ALL PARAM HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -16 Program Execution CLEAR Command CLEAR Command Use the CLEAR command to revoke a specific ASSIGN or PARAM command, all of the ASSIGN commands, all of the PARAM commands, or all of both commands. CLEAR ALL ASSIGN PARAM ASSIGN assignation PARAM DEBUG EXECUTION-LOG INSPECT NONSTOP PRINTER-CONTROL WAITED-IO SWITCH- nn parameter-name VST340.vsd ALL means clear all currently active ASSIGN and PARAM references. ALL ASSIGN means clear all currently active ASSIGN references. ALL PARAM means clear all currently active PARAM references. ASSIGN means clear the reference to the specified COBOL file name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -17 Program Execution CLEAR Command assignation COBOL-file-name program-name . * VST638.vsd specifies what is to be cleared. COBOL-file-name is the COBOL name of a file. program-name is the name of the COBOL program that contains COBOL-file-name. * means all programs in the object file. PARAM means clear the reference to the specified parameter. DEBUG EXECUTION-LOG INSPECT NONSTOP PRINTER-CONTROL SWITCH-nn WAITED-IO parameter-name are parameters of the PARAM command (see PARAM Command). Example 12-5. CLEAR Command 43>CLEAR 44>CLEAR 45>CLEAR 46>CLEAR 47>CLEAR ALL ALL ASSIGN ALL PARAM ASSIGN in-file PARAM DEBUG { { { { { Clears Clears Clears Clears Clears all ASSIGN and PARAM values } all ASSIGN values } all PARAM values } assignment for in-file only } the DEBUG switch } HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -18 Program Execution DEFINEs DEFINEs A DEFINE is a named set of attribute/value pairs. DEFINEs are similar to ASSIGN messages, but more versatile. DEFINEs involve too many commands to be described completely here. Topics: • • • • • DEFINE and ASSIGN Controlling the Propagation of DEFINEs DEFINE Names DEFINE Attributes ADD DEFINE Command For more information on DEFINEs: Topics Sources Full documentation TACL Reference Manual Programmatic use Guardian Programmer’s Guide Further information Guardian User’s Guide DEFINE and ASSIGN Both DEFINEs and ASSIGN messages allow you to specify information about a file before you start the process that uses that file. Table 12-1. Differences Between DEFINE and ASSIGN DEFINE ASSIGN Processed by Operating environment HP COBOL program Propagated to Any process that your HP COBOL program creates, unless the new process specifies DEFMODE OFF Processes that your HP COBOL program creates and to which it explicitly passes ASSIGNs Accepted for compiler input and output files Yes No for HP COBOL, HP C, and HP C++; yes for FORTRAN, Pascal, and TAL Not accepted by FastSort SQL/MP or SQL/MX Yes, but it can be used only to access a Guardian disk file, tape device, or spooler location No Available from OSS environment HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -19 Program Execution Controlling the Propagation of DEFINEs The statements of a COBOL program refer to files through a COBOL file name. The ASSIGN clause in each file-control entry associates the COBOL file name with a system-file-name, the name by which a file is known to the operating environment. In the Guardian environment, the TACL command ASSIGN can override that association and DEFINEs provide a different form of name redirection. Suppose a program PROG1 includes a file-control entry for an fd-name of MAJORACCT, and associates it with a system-file-name: SELECT MAJORACCT ASSIGN TO "\AKRON.$SLB.MAJ.ACC" If you execute PROG1, when it opens MAJORACCT, the file it actually opens is \AKRON.$SLB.MAJ.ACC. If, when you execute the program, you want to redirect the assignment to a different file, you can issue a command interpreter ASSIGN command such as ASSIGN PROG1.MAJORACCT,\NICE.$FRNC.SIGNIF.CUST and then run PROG1. When the COBOL program opens MAJORACCT, it opens the file \NICE.$FRNC.SIGNIF.CUST. If, however, the program had associated MAJORACCT with a define-name with a filecontrol entry of the form SELECT MAJORACCT ASSIGN TO "=BIGGY" then you would need to have a DEFINE named “=BIGGY” established at execution time; otherwise, any OPEN statement would fail. Controlling the Propagation of DEFINEs You control whether or not the Guardian environment allows the creation and processing of DEFINEs. Use the DEFMODE ON/OFF command to enable or disable DEFINE creation and processing. Similarly, when one process starts another process, the creator can specify a DEFMODE setting for the new process; if it does not specify one, the new process inherits the DEFMODE setting of the creator. DEFINE Names Every DEFINE has a name. A name you give to a DEFINE must: • • • Consist of at least 2 and no more than 24 characters Begin with an equals sign (=) followed by a letter Continue with any combination of letters, digits, hyphens (-), underscores (_), and carets (^). HP has reserved the set of DEFINE names beginning with equals sign followed by underscore (_) for future use. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -20 Program Execution DEFINE Attributes Example 12-6. DEFINE Names =A =The_chosen_file =Long--but-not-too-long =The-File-of-The-Week =X_-^-_-_-^-_-_-^ Uppercase and lowercase letters are equivalent in DEFINE names. Wherever a DEFINE name can appear in the text of a COBOL source program, it must appear in quotation marks. Wherever a DEFINE name appears in commands to the command interpreter, such as on the command line that initiates a COBOL compilation, the DEFINE name must appear without quotation marks. DEFINE Attributes The CLASS attribute determines which other attributes a DEFINE can have. Table 12-2. DEFINE Attributes (page 1 of 2) Other Attributes of DEFINE CLASS Attribute Value Required CATALOG SUBVOL DEFAULTS VOLUME MAP (default) FILE SEARCH SUBVOL n SORT Optional SWAP BLOCK CPU CPUS MODE NOTCPUS PRI PROGRAM SCRATCH SEGMENT SUBSORTS SWAP * Required only if you specify the optional USE attribute with IN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -21 Program Execution DEFINE Attributes Table 12-2. DEFINE Attributes (page 2 of 2) Other Attributes of DEFINE CLASS Attribute Value Required Optional SPOOL LOC BATCHID BATCHNAME COPIES FORM HOLDAFTER MAXPRINTLINES MAXPRINTPAGES OWNER PAGESIZE REPORT SELPRI SUBSORT SCRATCH BLOCK CPU PRI PROGRAM SEGMENT SWAP TAPE VOLUME* BLOCKLEN DENSITY, DEVICE EBCDIC, EXPIRATION FILEID, FILESECT, FILESEQ GEN LABELS OWNER MOUNTMSG RECFORM, RECLEN REELS, RETENTION SYSTEM TAPEMODE USE VERSION * Required only if you specify the optional USE attribute with IN. To create a DEFINE, you must: 1. Set the value of its CLASS attribute (use the SET DEFINE CLASS command in your command interpreter) 2. Give values to its other attributes For details, see the TACL Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -22 Program Execution ADD DEFINE Command Usage Considerations: • TAPE DEFINE Provides the Only Way to Use Labeled Tapes For details, see Section 25, Executing and Debugging HP COBOL Programs, and the Guardian User’s Guide. • • You Can Use SPOOL DEFINES instead of COBOLSPOOLOPEN Special DEFAULTS DEFINE: =_DEFAULTS DEFINE Processes can use the =_DEFAULTS DEFINE without referring to it explicitly. The file system uses this DEFINE whenever it needs the values stored in the DEFINE’s attributes. You cannot delete the =_DEFAULTS DEFINE or change its name. ADD DEFINE Command Your COBOL program can, in the ASSIGN clause of a file-control entry, associate a DEFINE name with a COBOL file name, just as it would associate a file-system file name with a COBOL file name. When the process compiled from that source attempts to open that file, the file system looks for the stored set of attribute/value pairs and uses them to complete the specification of the file before making it available to the process. If it cannot make a file available (based on what it finds, or fails to find), the open operation fails. To create and name a DEFINE, you use the ADD DEFINE command. Suppose that your current CLASS attribute has the value MAP. If your COBOL program includes this file-control entry: SELECT MARKET-ANALYSIS ASSIGN TO "=MARKT" ACCESS MODE IS DYNAMIC RECORD KEY IS PRODUCT-CODE FILE STATUS IS M-STAT. Before executing your program, you must issue a command of this form: >ADD DEFINE =MARKT, FILE \MAG.$EAST.APRIL.SALES to associate the file SALES in subvolume APRIL on volume $EAST on system \MAG with the name =MARKT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -23 Program Execution Initial State Initial State Every program in a run unit has an initial state in which a process places it at certain times while the run unit executes. When a program is in its initial state: • • • • • • Each data item in the Linkage Section has the value specified by the calling program. Each Working-Storage or Extended-Storage data item that is described with a VALUE clause (except level-88 condition-names) has the specified value. The value of each data item in the Working-Storage Section or the ExtendedStorage Section that is not described with a VALUE clause depends on whether the NOBLANK directive was active during compilation. If not, each data item has a space character (octal 40) in each character position or (for a COMPUTATIONAL, COMPUTATIONAL-3, or COMPUTATIONAL-5 data item) a value consisting of a series of space characters interpreted as a binary number. If the NOBLANK directive was active during compilation, the value of each data item is unpredictable. The open mode of each internal file connector is either Closed or Locked. The other dynamic attributes of the file connector (such as the file position indicator setting) and the contents of the record area for the file associated with the file connector are undefined. The control mechanisms for all PERFORM statements in the program are set to their initial state (inactive). GO TO statements whose destinations can be modified by ALTER statements are restored to the forms specified in the source program. A program is placed in its initial state at these times: • • • The first time the program is executed in a run unit. For a main program, this is at the beginning of each separate execution of the run unit. For a called program, this is the first time it is called by a CALL statement during each execution of the run unit. The first time the program is called after a CANCEL statement cancels it. For an initial program, each time it is called. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -24 Program Execution Status of Internal Entities During Program Execution Status of Internal Entities During Program Execution During the execution of a program, each internal entity retains the status in which it was left by the execution of the last statement that affected its status: • • • • Each internal data item retains the last value assigned to it. If no new value has been assigned since the last time the program was placed in its initial state, its “last value” is its initial value. Each internal file connector retains the open-mode state and other dynamic attributes, such as the file position indicator, set or assigned by execution of the last statement that affects them. The record area for a file associated with an internal file connector retains whatever contents were last assigned to it. If the file has not been opened since the last time the program was placed in its initial state, the file is closed (and perhaps locked), and the other dynamic attributes are undefined. In this case, the record area contents are also undefined. Each GO TO statement that was modified by execution of an ALTER statement retains the last destination procedure specified. A PERFORM statement is active if it has been executed during the current execution of the program it is in, and the termination conditions for its control mechanism have not yet occurred (see PERFORM); otherwise, the statement is inactive, and its control mechanism is in the initial state. Status of External Entities During Program Execution The values of external data items and the statuses of external file connectors are not affected by the actions performed for individual programs. When a program is called, placed in its initial state, terminated by its own execution logic, or cancelled, the status of each external entity remains unchanged. Of course, the execution of a statement that makes reference to an external data item or an external file connector changes its status as the topic on that statement in Section 9, Procedure Division Verbs, describes. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -25 Program Execution Called Program Termination Called Program Termination A called program terminates its own execution either by executing an EXIT PROGRAM statement or by allowing control to pass beyond the end of its Procedure Division. The completion of the program’s execution implicitly completes the execution of all of its statements; therefore, if any PERFORM statement contained in the program is still active, it is rendered inactive by the program’s resetting its control mechanism to the initial state. The final status of any other internal entity depends on whether or not the program has the initial attribute. When a called program that has the initial attribute terminates its own execution, an implicit CANCEL statement referencing the program is executed just after control passes from the called program. This causes the value of each internal data item to become undefined and performs an implicit close operation for each internal file connector that is not closed (with or without lock). The implicit close operations proceed as if a CLOSE statement without any of the optional phrases were executed for each of the affected files. If the program is called again, it is placed in its initial state. When a called program that does not have the initial attribute terminates its own execution, each internal entity (except a data item described in the Linkage Section) retains its status: • • • Each internal data item (except those described in the Linkage Section) retains its current value. Each internal file connector retains all of its current dynamic attributes; therefore, if it is open in some mode, it remains open in that mode and the record area for the file associated with the internal file connector retains its current contents. Each GO TO statement modified by execution of an ALTER statement retains the last destination procedure specified. If the program is called again during this execution of the run unit, its state upon entry is normally unchanged from the state in which its termination logic left it, except that those data items described in the Linkage Section have whatever values are supplied by the calling program; however, if a CANCEL statement designating the program is executed after the program terminates, it causes the value of each internal data item to become undefined and performs an implicit close operation for each internal file connector that is neither closed nor locked. The implicit close operations proceed as if a CLOSE statement without any of the optional phrases were executed for each of the affected files. In this case, the program is placed in its initial state the next time it is called. HP COBOL Manual for TNS and TNS/R Programs —522555-006 12 -26 13 Libraries and Utility Routines Utility routines are object programs that your HP COBOL program can call. Utility routines are in libraries. TNS libraries are categorized by the memory area in which their routines execute: Library Type Memory Area Where Routines Execute Private object library (linkfile) User code space System library System code space TNS user library User library space If a TNS HP COBOL program calls a utility routine, the routine must be bound into the program’s target file. The files COBOLEX0, COBOLEX1, COBOLEXT, CBL85UTL, COBOLLIB, and CLULIB contain utility routines that are to be configured into either the system library or TNS user library or made available to Binder to enable you to bind them into your own object files. Among these utility routines are FastSort interface routines and Saved Message Utility (SMU) routines. As Figure 13-1 shows, FastSort interface routines are in CBL85UTL, SMU routines for the non-CRE environment are in COBOLLIB, and SMU routines for the CRE are in CLULIB (Figure 13-1 is not to scale). Figure 13-1. TNS Libraries and Their Utility Routines CBL85UTL COBOLLIB CLULIB SMU Routines FastSort Routines Other Routines COBOL85 Environment Other Routines CRE CLU_PROCESS_CREATE _ CLU_PROCESS_FILE_NAME_ VST619.vsd For native HP COBOL programs, utility routines are in public shared run-time libraries (SRLs) named ZCOBSRL and ZCRESRL. (You can also create a user library for a native HP COBOL program.) If a program calls a utility routine, the NMCOBOL compiler automatically searches the SRLs for the routine, but the routine is not bound into the program’s target file. As Figure 13-2 shows, ZCOBSRL contains native versions of the routines in CBL85UTL and COBOLLIB, and ZCRESRL contains routines that are in CLULIB. ZCOBSRL and ZCRESRL also contain routines that were in the system library for TNS HP COBOL programs (Figure 13-2 is not to scale). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 1 Libraries and Utility Routines Figure 13-2. Native SRLs and Their Utility Routines ZCOBSRL ZCRESRL FastSort Routines SMU Routines Other CBL85UTL routines Other COBOLLIB routines CLU_PROCESS_CREATE_ Routines whose TNS versions are in the system library Routines whose TNS versions are in the system library VST730.vsd PIC programs (native HP COBOL programs that are compiled with the NMCOBOL compiler and the directive CALL-SHARED or SHARED) can call dynamic-link libraries (DLLs), which you can build. SRLs can call DLLs, but DLLs cannot call SRLs. Note. In this section, references to $SYSTEM apply only to the NonStop system. For the locations of files on the PC, see NonStop COBOL for TNS/R (ETK). Topics: • • • • • • • • • • • • • Memory Areas Linkfiles as Libraries System Library TNS User Library User Library Dynamic-Link Libraries (DLLs) Files of Dummy Routines CBL85UTL Overview FastSort Interface Overview COBOLLIB Overview ZCOBSRL Overview CLULIB Overview Saved Message Utility (SMU) Overview HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 2 Libraries and Utility Routines • • • • • ZCRESRL Overview CBL85UTL and ZCOBSRL Routines COBOLLIB, CLULIB, and ZCOBSRL Routines Saved Message Utility (SMU) Routines Guardian Environment Level 3 Spooling Routines Table 13-1. All TNS and TNS/R Utility Routines (page 1 of 3) Utility Routines Environments Libraries ALTERPARAMTEXT Non-CRE COBOLLIB CHECKLOGICALNAME Non-CRE COBOLLIB CHECKMESSAGE Non-CRE COBOLLIB CLU_PROCESS_CREATE_ Non-CRE and CRE CLULIB and ZCRESRL CLU_PROCESS_FILE_NAME_ Non-CRE and CRE CLULIB COBOL85^ARMTRAP Non-CRE CBL85UTL COBOL85^COMPLETION Non-CRE CBL85UTL COBOL85^RETURN^SORT^ERRORS Non-CRE CBL85UTL COBOL85^REWIND^SEQUENTIAL Non-CRE CBL85UTL COBOL85^SET^SORT^PARAM^TEXT Non-CRE CBL85UTL COBOL85^SET^SORT^PARAM^VALUE Non-CRE CBL85UTL COBOL85^SPECIAL^OPEN2 Non-CRE CBL85UTL COBOL_ASSIGN_ CRE/Guardian COBOLLIB and ZCOBSRL COBOL_COMPLETION_ CRE CBL85UTL and ZCOBSRL COBOL_CONTROL_ CRE CBL85UTL and ZCOBSRL COBOL_FILE_INFO_ CRE COBOLLIB and ZCOBSRL COBOL_GETENV_ CRE CBL85UTL and ZCOBSRL COBOL_PUTENV_ CRE CBL85UTL and ZCOBSRL COBOL_RETURN_SORT_ERRORS_ CRE/Guardian CBL85UTL and ZCOBSRL COBOL_REWIND_SEQUENTIAL_ CRE CBL85UTL and ZCOBSRL COBOL_SET_SORT_PARAM_TEXT_ CRE/Guardian CBL85UTL and ZCOBSRL COBOL_SET_SORT_PARAM_VALUE_ CRE CBL85UTL and ZCOBSRL COBOL_SETMODE_ CRE CBL85UTL and ZCOBSRL 1. Routines for the non-CRE environment are available only in the Guardian environment. Most routines for the CRE are available in the Guardian and OSS environments; those whose environment is specified “CRE/Guardian” are available only in the Guardian environment. 2. This routine replaces the COBOLSPOOLOPEN routine (for level 2 spooling) and Guardian environment routines (for level 3 spooling). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 3 Libraries and Utility Routines Table 13-1. All TNS and TNS/R Utility Routines (page 2 of 3) Utility Routines Environments Libraries COBOL_SPECIAL_OPEN_2 CRE/Guardian CBL85UTL and ZCOBSRL COBOLASSIGN Non-CRE COBOLLIB COBOLFILEINFO Non-CRE and CRE (Guardian) COBOLLIB and ZCOBSRL COBOLSPOOLOPEN Non-CRE COBOLLIB CREATEPROCESS Non-CRE COBOLLIB DELETEASSIGN Non-CRE COBOLLIB DELETEPARAM Non-CRE COBOLLIB DELETESTARTUP Non-CRE COBOLLIB GETASSIGNTEXT Non-CRE COBOLLIB GETASSIGNVALUE Non-CRE COBOLLIB GETBACKUPCPU Non-CRE COBOLLIB GETPARAMTEXT Non-CRE COBOLLIB GETSTARTUPTEXT Non-CRE COBOLLIB PUTASSIGNTEXT Non-CRE COBOLLIB PUTASSIGNVALUE Non-CRE COBOLLIB PUTPARAMTEXT Non-CRE COBOLLIB PUTSTARTUPTEXT Non-CRE COBOLLIB SMU_Assign_CheckName_ CRE CLULIB and ZCRESRL SMU_Assign_Delete_ CRE CLULIB and ZCRESRL SMU_Assign_GetText_ CRE CLULIB and ZCRESRL SMU_Assign_GetValue_ CRE CLULIB and ZCRESRL SMU_Assign_PutText_ CRE CLULIB and ZCRESRL SMU_Assign_PutValue_ CRE CLULIB and ZCRESRL SMU_Message_CheckNumber_ CRE CLULIB and ZCRESRL SMU_Param_Delete_ CRE CLULIB and ZCRESRL SMU_Param_GetText_ CRE CLULIB and ZCRESRL SMU_Param_PutText_ CRE CLULIB and ZCRESRL 1. Routines for the non-CRE environment are available only in the Guardian environment. Most routines for the CRE are available in the Guardian and OSS environments; those whose environment is specified “CRE/Guardian” are available only in the Guardian environment. 2. This routine replaces the COBOLSPOOLOPEN routine (for level 2 spooling) and Guardian environment routines (for level 3 spooling). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 4 Libraries and Utility Routines Table 13-1. All TNS and TNS/R Utility Routines (page 3 of 3) Utility Routines Environments Libraries SMU_Startup_Delete_ CRE CLULIB and ZCRESRL SMU_Startup_GetText_ CRE CLULIB and ZCRESRL SMU_Startup_PutText_ CRE CLULIB and ZCRESRL 1. Routines for the non-CRE environment are available only in the Guardian environment. Most routines for the CRE are available in the Guardian and OSS environments; those whose environment is specified “CRE/Guardian” are available only in the Guardian environment. 2. This routine replaces the COBOLSPOOLOPEN routine (for level 2 spooling) and Guardian environment routines (for level 3 spooling). For information about individual routines: Library Source CBL85UTL CBL85UTL and ZCOBSRL Routines COBOLLIB CLULIB COBOLLIB, CLULIB, and ZCOBSRL Routines ZCOBSRL CBL85UTL and ZCOBSRL Routines COBOLLIB, CLULIB, and ZCOBSRL Routines ZCRESRL CRE Programmer’s Guide HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 5 Libraries and Utility Routines Memory Areas Memory Areas The memory a COBOL process uses is divided into distinct areas, each holding code blocks or data blocks for the COBOL run unit or for Guardian environment routines that serve the run unit. Table 13-2. Memory Area Characteristics (page 1 of 2) Memory Area User code space Purpose Size Comments Holds code blocks produced by the compilation For TNS processes, up to 16 segments of up to 128 KB each with a user library; up to 32K segments without a user library Routines from loadfiles execute here. For native processes, 32 megabytes For TNS processes, an individual HP COBOL program (in any environment) that contains no nested programs cannot exceed 128 KB. A nest of HP COBOL programs (the outermost, plus all programs nested within it) can exceed 128 KB, but no single In the non-CRE environment, run units that include HP COBOL routines must have an HP COBOL main program and can occupy almost 16 x 128 KB. User library space1 Holds additional user code (HP COBOL and non-COBOL routines called by the HP COBOL program) Up to 16 segments of up to 128 KB each TNS user library routines execute here. User data space1 Holds data blocks produced by the compilation 128 KB Only the lower 64 KB of the 64K space are available for user data. The upper 64 KB are reserved for buffers and run-time data structures. 1. TNS processes only 2. Native processes only HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 6 Libraries and Utility Routines Memory Areas Table 13-2. Memory Area Characteristics (page 2 of 2) Memory Area Purpose Size Comments Holds data blocks of data declared in Extended-Storage Sections of COBOL programs and compiler-generated tables One segment of extended memory (134,217,726 bytes) The maximum data item size is 134,217,726 bytes. Small data area2 Holds data blocks produced by the compilation 32,768 characters See LARGEDATA. Large data area2 Holds data blocks produced by the compilation 1.1 GB for native processes on G05 and later systems See LARGEDATA. System code space Holds code for the system routines that service the run unit in the user code space System code extension Provides more space for execution of system library routines System data space Holds data for the system routines that service the run unit in the user code space User extended space1 Run-time routines can allocate additional segments for EDIT files and HP COBOL Fast I-O System library routines execute here. 128 MB for TNS processes, D-series systems, and preG05 systems 1.1 GB for native processes on G05 and later systems 1. TNS processes only 2. Native processes only HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 7 Libraries and Utility Routines Linkfiles as Libraries Linkfiles as Libraries A linkfile can serve as your TNS user library (for the COBOL85 compiler) or user library (for the NMCOBOL compiler). A link file cannot be executed as a process, due to its lack of a main program; however, the code in the file can be executed. To call utility routines from a user library, use CALL or ENTER statements (see CALL and ENTER). CALL and ENTER statements allow you to specify the user library that contains the routine you want to call. If you do not specify the user library in the CALL or ENTER statement, the compilers resolves the references to the external routines as explained in How the Compiler Resolves Unqualified References. System Library System library content is determined at system generation (SYSGEN). System library routines run in the system code space. For a TNS program, the file COBOLLIB can be configured into the system library. (Alternatively, it can be configured into the user library or made available to Binder to enable you to bind it into your own object files.) TNS User Library This section applies only to the COBOL85 compiler. A native HP COBOL program uses a user library (see User Library). A TNS user library contains routines that the operating environment binds to the loadfile (run unit) at run time. Run-time binding does not include copying the routines from the TNS user library into the loadfile. A loadfile can have only one TNS user library associated with it. An HP COBOL program can call routines contained in a user library that are written in HP C, HP C++, FORTRAN, Pascal, and TAL. In the CRE, programs written in HP COBOL can also be called. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 8 Libraries and Utility Routines User Library The language in which a routine is written determines whether it can execute in user library space: Language in Which Routine is Written Routine Can Execute in User Library Space HP COBOL Yes, if the ENV LIBRARY directive is specified HP C Yes, if the ENV EMBEDDED directive is specified HP C++ Yes, if the ENV EMBEDDED directive is specified FORTRAN Yes, but then it cannot have any COMMON, DATA, or SAVE statements Pascal No TAL Yes, if no global blocks are defined A CRE HP COBOL program can be put in a TNS user library if it satisfies the criteria listed in Library Programs. Note. ASSIGN and PARAM commands for files in a TNS user library are ignored. A loadfile can include as many as 32 code segments—16 in user code space and 16 in user library space, or all 32 segments in user code space. Each code segment consists of up to 128 KB. HP COBOL enables you to write COBOL programs nested within other COBOL programs. No individual HP COBOL program can produce a program unit of more than 128 KB. No nested set of HP COBOL programs can produce a program unit of more than 128 KB, in which no program but the outermost can exceed 64 KB. The program units that make up a run unit can total no more than 32 x 128 KB (16 x 128 KB if it calls any TNS user library routines). You can specify a TNS user library in the LIB option of the RUN command. For information on the LIB option, see the TACL Reference Manual. For more information on user libraries, see the Binder Manual. User Library Note. This topic applies only to the NMCOBOL compiler. A TNS program uses a TNS user library (see TNS User Library). A user library contains routines that the operating environment links to the loadfile (run unit) at run time. Run-time linking does not include copying the routines into the loadfile. A loadfile can have only one user library associated with it. Topics: • • Building a User Library Specifying a User Library HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 9 Libraries and Utility Routines Building a User Library Building a User Library A program can be put in a user library if: • • • It is not a main program. It does not contain embedded SQL/MP or SQL/MX statements. It does not contain external objects (data or files that are to be shared with code that is outside the library). Note. ASSIGN and PARAM commands for files in a user library are ignored. From a Single Source File To build a user library from a single source file (which can contain one or more source programs), compile the source file with these directives: • • RUNNABLE UL The resulting loadfile is a user library. If you use this method of building a user library, each object file that is to be included in the library must be referenced with either a file-mnemonic (see CALL and ENTER) or a SEARCH directive (see SEARCH and NOSEARCH) so that the compiler can find it. From Multiple Source Files To build a user library from multiple source files (each of which can contain one or more source programs), compile each source file with the UL directive but without the RUNNABLE directive. Link the resulting linkfiles, using the linker with the -ul flag. The -ul flag causes the linker to link the object files into a single loadfile, which is a user library. Specifying a User Library At compilation time, you must specify the user library that you want your program to use in a CONSULT directive (see CONSULT and NOCONSULT). At run time, you must specify the same user library by using the LIB option of the RUN command (in the Guardian environment) or the -lib flag of the run command (in the OSS environment). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -10 Libraries and Utility Routines Dynamic-Link Libraries (DLLs) Dynamic-Link Libraries (DLLs) Note. This topic applies only to the NMCOBOL compiler. A TNS program uses a TNS user library (see TNS User Library). A DLL is a library of shared code [PIC] that contains functions or data for other PIC loadfiles. (For more information about PIC and DLLs, see the DLL Programmer’s Guide for TNS/R Systems.) You can put a program in a DLL if: • • • It is not a main program. It does not contain embedded SQL/MP or SQL/MX statements. It does not contain external objects (data or files that are to be shared with code that is outside the library). Note. ASSIGN and PARAM commands for files in a DLL are ignored. If you put an HP COBOL program in a DLL, you must export the program name when you build the DLL; otherwise, other programs cannot call the HP COBOL program. To export the HP COBOL program name, use either the LD directive (Guardian) or the -Wld option (OSS and PC), with one of the linker options in Table 13-3. Table 13-3. Linker Options That Export Program Names Option exports ... Environment All program names in the source file Only the specified program name Guardian LD (-export_all) LD (-export program-name ) OSS and PC -Wld="-export_all" -Wld="-export program-name " Topics: • • • Building a DLL From a Single Source File Building a DLL from Multiple Source Files Specifying a DLL Building a DLL From a Single Source File The single source file from which you build the DLL can contain one or more source programs. You can build a DLL from a single source file in either one step or two: either compile the source file and have the compiler call the linker, or compile the source file and call the linker yourself. (For linker instructions, see the ld Manual.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -11 Libraries and Utility Routines Building a DLL From a Single Source File Topics: • • • • • • Guardian Environment: One-Step Method Guardian Environment: Two-Step Method OSS Environment: One-Step Method OSS Environment: Two-Step Method PC Environment: One-Step Method PC Environment: Two-Step Method Guardian Environment: One-Step Method Compile the source file with these directives: • • • SHARED RUNNABLE LD with either of these options: ° ° -export_all, which exports all program names in the source file -export program-name, which exports only the specified program name. You must repeat this option for every program name that you want to export. The resulting loadfile is a DLL. The command in Example 13-1 compiles the source file LIB1 and links the resulting object file, creating a DLL named MYDLL. Example 13-1. Building a DLL From a Single Source File in One Step (Guardian) NMCOBOL /IN LIB1/ MYDLL; SHARED; RUNNABLE; & &LD(-export_all) Guardian Environment: Two-Step Method 1. Compile the source file with the directive SHARED. Note. Do not use the RUNNABLE directive. The result is a linkfile. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -12 Libraries and Utility Routines Building a DLL From a Single Source File 2. Link the linkfile, using the ld utility with these options: • Either: ° ° • -export_all, which exports all program names in the source file -export program-name, which exports only the specified program name. You must repeat this option for every program name that you want to export. -optional_lib -l ZCOBSRL -l ZCRESRL, which links your file with the SRLs named ZCOBSRL and ZCRESRL The resulting loadfile is a DLL. In Example 13-2, the first command compiles the source file LIB1, creating the linkable object file LIB1O. The second command links LIB1O with the SRLs named ZCOBSRL and ZCRESRL, creating a DLL named MYDLL. Example 13-2. Building a DLL From a Single Source File in Two Steps (Guardian) NMCOBOL /IN LIB1/ LIB1O; SHARED LD LIB1O -SHARED -EXPORT_ALL -optional_lib -l ZCOBSRL -l ZCRESRL -o MYDLL OSS Environment: One-Step Method Compile the source file with these options: • -Wshared Note. Do not use -c. • -Wld with either of these arguments: ° ° -export_all, which exports all program names in the source file -export program-name, which exports only the specified program name. You must repeat this option for every program name that you want to export. The resulting loadfile is a DLL. The command in Example 13-3 compiles the source file lib1.cob and links the resulting object file, creating a DLL named mydll. Example 13-3. Building a DLL From a Single Source File in One Step (OSS) nmcobol lib1.cob -Wshared -Wld="-export_all HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -13 Libraries and Utility Routines Building a DLL From a Single Source File OSS Environment: Two-Step Method 1. Compile the source file with these options: • • -Wshared -c The result is a linkfile. 2. Link the linkfile, using the ld utility with these options: • Either: ° ° • -export_all, which exports all program names in the source file -export program-name, which exports only the specified program name. You must repeat this option for every program name that you want to export. -optional_lib -l ZCOBSRL -l ZCRESRL, which links your file with the SRLs named ZCOBSRL and ZCRESRL The resulting loadfile is a DLL. In Example 13-4, the first command compiles the source file lib1.cob, creating the linkable object file lib1.o. The second command links lib1.o with the SRLs named ZCOBSRL and ZCRESRL, creating a DLL named mydll. Example 13-4. Building a DLL From a Single Source File in Two Steps (OSS) nmcobol lib1.cob -Wshared -c ld lib1.o -shared -export_all -optional_lib -l ZCOBSRL -l ZCRESRL -o mydll PC Environment: One-Step Method Compile the source file with these options: • -Wshared Note. Do not use -c. • -Wld with either of these arguments: ° ° -export_all, which exports all program names in the source file -export program-name, which exports only the specified program name. You must repeat this option for every program name that you want to export. The resulting loadfile is a DLL. The command in Example 13-5 compiles the source file lib1.cob and links the resulting object file, creating a DLL named mydll. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -14 Libraries and Utility Routines Building a DLL from Multiple Source Files Example 13-5. Building a DLL From a Single Source File in One Step (PC) nmcobol lib1.cob -Wshared -Wld="-export_all" -o mydll PC Environment: Two-Step Method 1. Compile the source file with these options: • • -Wshared -c The result is a linkfile. 2. Link the linkfile, using the ld utility with these options: • Either: ° ° • -export_all, which exports all program names in the source file -export program-name, which exports only the specified program name. You must repeat this option for every program name that you want to export. -optional_lib followed by: ° -L lib-directory -lcob, which links your file with the SRL named ZCOBSRL ° -obey lib-directory\libc.obey, which links your file with the SRL named ZCRESRL lib-directory is the name of the directory of libraries. The resulting loadfile is a DLL. In Example 13-6, the first command compiles the source file lib1.cob, creating the linkable object file lib1.o. The second command links lib1.o with the SRLs named ZCOBSRL and ZCRESRL, creating a DLL named mydll. Example 13-6. Building a DLL From a Single Source File in Two Steps (PC) nmcobol lib1.cob -Wshared -c ld lib1.o -shared -export_all -optional_lib -L lib-directory -lcob -obey lib-directory\libc.obey -o mydll Building a DLL from Multiple Source Files Each source file from which you build the DLL can contain one or more source programs. Building a DLL from multiple source files takes two steps: 1. Compile the source files. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -15 Libraries and Utility Routines Building a DLL from Multiple Source Files 2. Link the resulting linkfiles into a single loadfile. Topics: • • • Guardian Environment OSS Environment PC Environment Guardian Environment 1. Compile each source file with the directive SHARED. Note. Do not use the RUNNABLE directive. The result of each compilation is a linkfile. 2. Link the linkfiles into a single loadfile, using the ld utility with these options: • Either: ° ° • • -export_all, which exports all program names in the source file -export program-name, which exports only the specified program name. You must repeat this option for every program name that you want to export. -shared, which links the linkfiles into a single loadfile that is a DLL -optional_lib -l ZCOBSRL -l ZCRESRL, which links your file with the SRLs named ZCOBSRL and ZCRESRL In Example 13-7, the first four commands compile four source files (LIB1, LIB2, LIB3, and LIB4), creating four linkable object files (LIB1O, LIB2O, LIB3O, and LIB4O). The last command links the four linkable object files with the SRLs named ZCOBSRL and ZCRESRL, creating the DLL named MYDLL. Example 13-7. Building a DLL From Multiple Source Files (Guardian) NMCOBOL /IN LIB1/ LIB1O;SHARED NMCOBOL /IN LIB2/ LIB2O;SHARED NMCOBOL /IN LIB3/ LIB3O;SHARED NMCOBOL /IN LIB4/ LIB4O;SHARED LD LIB1O LIB2O LIB3O LIB4O -shared -export_all -optional_lib -l ZCOBSRL -l ZCRESRL -o MYDLL HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -16 Libraries and Utility Routines Building a DLL from Multiple Source Files OSS Environment 1. Compile each source file with these options: • • -Wshared -c The result of each compilation is a linkfile. 2. Link the linkfiles into a single loadfile, using the ld utility with these options: • Either: ° ° • • -export_all, which exports all program names in the source file -export program-name, which exports only the specified program name. You must repeat this option for every program name that you want to export. -shared, which links the linkfiles into a single loadfile that is a DLL -optional_lib -l ZCOBSRL -l ZCRESRL, which links your file with the SRLs named ZCOBSRL and ZCRESRL In Example 13-8, the first four commands compile four source files (lib1.cob, lib2.cob, lib3.cob, and lib4.cob), creating four linkable object files (lib1.o, lib2.o, lib3.o, and lib4.o). The last command links the four linkable object files with the SRLs named ZCOBSRL and ZCRESRL, creating a DLL named mydll. Example 13-8. Building a DLL From Multiple Source Files (OSS) nmcobol lib1.cob -Wshared -c nmcobol lib2.cob -Wshared -c nmcobol lib3.cob -Wshared -c nmcobol lib4.cob -Wshared -c ld lib1.o lib2.o lib3.o lib4.o -shared -export_all -optional_lib -l ZCOBSRL -l ZCRESRL -o mydll PC Environment 1. Compile each source file with these options: • • -Wshared -c The result of each compilation is a linkfile. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -17 Libraries and Utility Routines Building a DLL from Multiple Source Files 2. Link the linkfiles into a single loadfile, using the ld utility with these options: • Either: ° ° • • -export_all, which exports all program names in the source file -export program-name, which exports only the specified program name. You must repeat this option for every program name that you want to export. -shared, which links the linkfiles into a single loadfile that is a DLL -optional_lib followed by: ° -L lib-directory -lcob, which links your file with the SRL named ZCOBSRL ° -obey lib-directory\libc.obey, which links your file with the SRL named ZCRESRL lib-directory is the name of the directory of libraries. In Example 13-9, the first four commands compile four source files (lib1.cob, lib2.cob, lib3.cob, and lib4.cob), creating four linkable object files (lib1.o, lib2.o, lib3.o, and lib4.o). The last command links the four linkable object files with the SRLs named ZCOBSRL and ZCRESRL, creating a DLL named mydll. Example 13-9. Building a DLL From Multiple Source Files (PC) nmcobol lib1.cob -Wshared -c nmcobol lib2.cob -Wshared -c nmcobol lib3.cob -Wshared -c nmcobol lib4.cob -Wshared -c ld lib1.o lib2.o lib3.o lib4.o -shared -export_all -optional_lib -L lib-directory -lcob -obey lib-directory\libc.obey -o mydll HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -18 Libraries and Utility Routines Specifying a DLL Specifying a DLL To use an existing DLL, you must specify it to both the compiler and the linker. You can do this in either one step or two. Topics: • • • • • • Guardian Environment: Compile and Link in One Step Guardian Environment: Compile and Link in Two Steps OSS Environment: Compile and Link in One Step OSS Environment: Compile and Link in Two Steps PC Environment: Compile and Link in One Step PC Environment: Compile and Link in Two Steps Guardian Environment: Compile and Link in One Step Compile the program that uses the DLL with these directives: • • • CALL-SHARED CONSULT with the name of the DLL as an object-name (see CONSULT and NOCONSULT) LD with these options: ° ° -L (which is similar to the nmcobol option -L) -l or -lib (which is similar to the nmcobol option -l) For more information about the ld options -l or -lib, see the ld Manual. The result is a loadfile. The command in Example 13-10 compiles the source file MAIN and links the resulting object file with the DLL named MYDLL, creating a loadfile named MAINO. Example 13-10. Specifying a DLL When the Compiler Calls the Linker (Guardian) NMCOBOL /IN MAIN/ MAINO; CALL-SHARED; CONSULT MYDLL; RUNNABLE;& &LD(-L $VOL.SUBVOL -l MYDLL) Guardian Environment: Compile and Link in Two Steps 1. Compile the program that uses the DLL with these directives: • • CALL-SHARED CONSULT with the name of the DLL as an object-name (see CONSULT and NOCONSULT) The result is a linkfile. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -19 Libraries and Utility Routines Specifying a DLL 2. Link the linkfile, using the ld utility with these ld options: • • • -L (which is similar to the nmcobol option -L) -l or -lib (which is similar to the nmcobol option -l) -optional_lib -l ZCOBSRL -l ZCRESRL, which links your file with the SRLs named ZCOBSRL and ZCRESRL For more information about the ld options -l or -lib, see the ld Manual. In Example 13-11, the first command compiles the source file MAIN, specifying the DLL named MYDLL and creating the linkable object file MAINO. The second command links MAINO with MYDLL and the SRLs named ZCOBSRL and ZCRESRL, creating a loadfile named MYPROG. Example 13-11. Specifying a DLL When You Compile and Then Link (Guardian) NMCOBOL /IN MAIN/ MAINO; CALL-SHARED; CONSULT MYDLL LD MAINO -CALL_SHARED -L $VOL.SUBVOL -l MYDLL -optional_lib -l ZCOBSRL -l ZCRESRL -O MYPROG OSS Environment: Compile and Link in One Step Compile the program that uses the DLL with these options: • • • -Wcall_shared -L -l Note. Do not use -c. The result is a loadfile. The command in Example 13-12 compiles the source file main.cob and links the resulting object file with the DLL named mydll, creating the loadfile main.exe. Example 13-12. Specifying a DLL When the Compiler Calls the Linker (OSS) nmcobol main.cob -Wcall_shared -Wcobol="CONSULT MYDLL" -L /usr/xxx/yyy -l mydll -o main.exe OSS Environment: Compile and Link in Two Steps 1. Compile the program that uses the DLL with these options: • • -Wcall_shared -c The result is a linkfile. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -20 Libraries and Utility Routines Specifying a DLL 2. Link the linkfile, using the ld utility with these ld options: • • • -L (which is similar to the nmcobol option -L) -l or -lib (which is similar to the nmcobol option -l) -optional_lib -l ZCOBSRL -l ZCRESRL, which links your file with the SRLs named ZCOBSRL and ZCRESRL For more information about the ld options -l or -lib, see the ld Manual. In Example 13-13, the first command compiles the source file main.cob, specifying the DLL named mydll and creating the linkable object file main.o. The second command links main.o with mydll and the SRLs named ZCOBSRL and ZCRESRL, creating the loadfile main.exe. Example 13-13. Specifying a DLL When You Compile and Then Link (OSS) nmcobol main.cob -Wcall_shared -Wcobol="CONSULT MYDLL" -c ld main.o -call_shared -L /usr/xxx/yyy -l mydll -optional_lib -l ZCOBSRL -l ZCRESRL -o main.exe PC Environment: Compile and Link in One Step Compile the program that uses the DLL with these nmcobol flags: • • • • -Wcall_shared -Wcobol with the argument “CONSULT MYDLL” -L, where directory is the name of the directory of libraries -l, where library is the name of the DLL Note. Do not use -c. The result is a loadfile. The command in Example 13-14 compiles the source file main.cob and links the resulting object file with the SRLs named ZCOBSRL and ZCRESRL and the DLL named mydll, creating the loadfile main.exe. MYDLL is in dll-location. (An example of dll-location is C:\xxx\yyy.) Example 13-14. Specifying a DLL When the Compiler Calls the Linker (PC) nmcobol main.cob -Wcall_shared -Wcobol="CONSULT MYDLL" -L dll-location -l mydll -optional_lib -L lib-directory -l ZCOBSRL -l ZCRESRL -o main.exe HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -21 Libraries and Utility Routines Specifying a DLL PC Environment: Compile and Link in Two Steps 1. Compile the program that uses the DLL with these options: • • • -Wcall_shared -c -Wcobol, with the argument “CONSULT MYDLL” The result is a linkfile. 2. Link the linkfile, using the ld utility with these ld options: • • -l or -lib (which is similar to the nmcobol option -l), where library is the name of the DLL -optional_lib followed by: ° -L lib-directory -lcob, which links your file with the SRL named ZCOBSRL ° -obey lib-directory\libc.obey, which links your file with the SRL named ZCRESRL lib-directory is the name of the directory of libraries. For more information about the ld options -l or -lib, see the ld Manual. In Example 13-15, the first command compiles the source file main.cob, specifying the DLL named MYDLL and creating the linkable object file main.o. The second command links main.o with mydll and the SRLs named ZCOBSRL and ZCRESRL, creating the loadfile main.exe. MYDLL is in dll-location. (An example of dlllocation is C:\xxx\yyy.) Example 13-15. Specifying a DLL When You Compile and Then Link (PC) nmcobol main.cob -Wcall_shared -c -Wcobol="CONSULT MYDLL" ld main.o -call_shared -L dll-location -l mydll -optional_lib -L lib-directory -lcob -obey lib-directory\libc.obey -o main.exe HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -22 Libraries and Utility Routines Files of Dummy Routines Files of Dummy Routines Files of dummy routines enable the compiler to accept ENTER statements that are to be resolved at program load time rather than by Binder during compilation (in the case of the COBOL85 compiler) or by the linker (in the case of the NMCOBOL compiler). Table 13-4. Files of Dummy Routines File Name COBOL85 Compiler NMCOBOL Compiler COBOLEX0 NMCOBEX0 Contains one dummy routine for each operating system routine in the EXTDECS0 file. Represents the latest RVU. COBOLEX1 NMCOBEX1 Contains one dummy routine for each operating system routine in the EXTDECS1 file. Represents the next-tolatest RVU. COBOLEXT NMCOBEXT Contains one dummy routine for each operating system routine in the EXTDECS file. Represents the secondnext-to-latest RVU. CBLIBEXT Description of File (as released by HP) Contains one dummy routine for each COBOLLIB routine. Your system manager can bind all the CBLIBEXT routines into COBOLEXT. When you install the compiler, the files of dummy routines are stored on the subvolume $SYSTEM.SYSTEM. If you move any of them to another subvolume, use the CONSULT directive to tell the compiler where to find the files you moved. CBL85UTL Overview CBL85UTL routines fall into two functional categories: • • FastSort interface routines Other routines The CBL85UTL file is only for the COBOL85 compiler. Its CRE routines are also in the ZCOBSRL file, which is for the NMCOBOL compiler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -23 Libraries and Utility Routines CBL85UTL Overview Table 13-5. CBL85UTL Routines Utility Routine Environments COBOL85^ARMTRAP COBOL COBOL85^COMPLETION COBOL COBOL85^RETURN^SORT^ERRORS COBOL COBOL85^REWIND^SEQUENTIAL COBOL COBOL85^SET^SORT^PARAM^TEXT COBOL COBOL85^SET^SORT^PARAM^VALUE COBOL COBOL85^SPECIAL^OPEN2 COBOL COBOL_COMPLETION_ CRE COBOL_CONTROL_ CRE COBOL_FILE_INFO_ COBOL and CRE COBOL_GETENV_ CRE COBOL_PUTENV_ CRE COBOL_RETURN_SORT_ERRORS_ CRE/Guardian COBOL_REWIND_SEQUENTIAL_ CRE COBOL_SET_MAX_RECORD_ COBOL and CRE COBOL_SETMODE_ CRE COBOL_SET_SORT_PARAM_TEXT_ CRE/Guardian COBOL_SET_SORT_PARAM_VALUE_ CRE COBOL_SPECIAL_OPEN_2 CRE/Guardian 1. Routines for the non-CRE environment are available only in the Guardian environment. Most routines for the CRE are available in the Guardian and OSS environments; those whose environment is specified “CRE/Guardian” are available only in the Guardian environment. 2. This routine replaces the COBOLSPOOLOPEN routine (for level 2 spooling) and Guardian environment routines (for level 3 spooling). Topics Sources FastSort interface routines FastSort Interface Overview ZCOBSRL file ZCOBSRL Overview Descriptions of individual CBL85UTL and ZCOBSRL routines (including FastSort interface routines) CBL85UTL and ZCOBSRL Routines HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -24 Libraries and Utility Routines FastSort Interface Overview FastSort Interface Overview The FastSort interface routines (in the CBL85UTL and ZCOBSRL files) give your HP COBOL program access to the FastSort utility program, which provides more extensive sorting features than HP COBOL has (such as parallel sorting). Use the FastSort interface routines only with FastSort. If you use them with SORT, the sort process might terminate abnormally. To use FastSort routines, you must establish a set of parameters and then execute a statement that uses those parameters. You can establish the set of parameters with either FastSort interface routines or the =_SORT_DEFAULTS DEFINE. Topics: • • Establishing Parameters With FastSort Interface Routines Establishing Parameters With =_SORT_DEFAULTS DEFINE For descriptions of individual FastSort interface routines, see CBL85UTL and ZCOBSRL Routines. Establishing Parameters With FastSort Interface Routines One way to establish FastSort parameters is with the FastSort interface routines. Each FastSort interface routine has a version for the non-CRE environment and a version for the CRE. Table 13-6. FastSort Interface Routines* COBOL-Environment Routine CRE Routine for Guardian Environment Purpose COBOL85^RETURN^SORT^ERRORS COBOL_RETURN_SORT_ERRORS_ Specifies the data item to which FastSort will report error messages COBOL85^SET^SORT^PARAM^TEXT COBOL_SET_SORT_PARAM_TEXT_ Establishes an alphanumeric parameter (which must be a data item described in any section of the Data Division) COBOL85^SET^SORT^PARAM^VALUE COBOL_SET_SORT_PARAM_VALUE_ Establishes a numeric parameter, specifying that it is a literal, an identifier, or an arithmetic expression * In the CBL85UTL file for the COBOL85 compiler and the ZCOBSRL file for the NMCOBOL compiler. At run time, HP COBOL routines collect these parameters into a storage area called the option block. When a SORT or MERGE verb is executed, other HP COBOL runtime routines pass these parameters to FastSort. If you do not establish FastSort parameters with FastSort interface routines (and certain other conditions are true), FastSort uses the attributes of the =_SORT_DEFAULTS DEFINE). For details, see Establishing Parameters With =_SORT_DEFAULTS DEFINE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -25 Libraries and Utility Routines Establishing Parameters With =_SORT_DEFAULTS DEFINE For explanations of individual FastSort interface routines, see CBL85UTL and ZCOBSRL Routines. Establishing Parameters With =_SORT_DEFAULTS DEFINE Another way to establish FastSort parameters is with the default SORT DEFINE =_SORT_DEFAULTS. This method is recommended when it would be difficult to modify existing applications. When an HP COBOL program calls FastSort, FastSort uses the attributes of =_SORT_DEFAULTS if all of these conditions are true: • • • No user DEFINEs have been specified No FastSort parameters are set DEFMODE is on You can create a =_SORT_DEFAULTS DEFINE by using the ALTER DEFINE statement in your command interpreter. You can use the command 22> INFO DEFINE =_SORT_DEFAULTS, DETAIL to determine whether the DEFINE exists and what its current settings are. You cannot use =_SORT_DEFAULTS to alter the FastSort parameters SCRATCH and MODE, because the compiler sets these itself whenever it executes a COBOL SORT statement. (It sets SCRATCH to the file that the SD entry specifies. It sets MODE to AUTOMATIC.) If you specify any FastSort options with FastSort interface routines, you can only use =_SORT_DEFAULTS to alter the parameters CPU, NOTCPUS, and SUBSORTS; however, if you specify CPU-MASK, NO-CPU-MASK, or SUBSORT-COUNT with a FastSort interface, routine, it overrides the respective parameter that you specified with =_SORT_DEFAULTS. For more information on the =_SORT_DEFAULTS DEFINE, see the FastSort Manual. COBOLLIB Overview The COBOLLIB file is a COBOL object file that contains utility routines supplied by HP. These routines support COBOL applications that must obtain file information or use operations not available through the normal language constructs. COBOLLIB routines fall into two categories: • • Saved Message Utility (SMU) routines for the non-CRE environment Other routines Most COBOLLIB routines have a non-CRE version and a CRE version. The COBOLLIB file is only for the COBOL85 compiler, and primarily for the non-CRE environment. The CRE and native versions of the COBOLLIB routines are in other files, as Table 13-7 shows. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -26 Libraries and Utility Routines COBOLLIB Overview Table 13-7. Where Versions of COBOLLIB Routines Are COBOL85 Compiler Routine Category Non-CRE Environment CRE NMCOBOL Compiler SMU COBOLLIB CLULIB ZCRESRL Other COBOLLIB COBOLLIB ZCOBSRL Table 13-8. COBOLLIB Routines Utility Routine Environments* In ZCOBSRL ALTERPARAMTEXT COBOL No CHECKLOGICALNAME COBOL No CHECKMESSAGE COBOL No COBOL_ASSIGN_ COBOL Yes COBOL_FILE_INFO_ COBOL Yes COBOLASSIGN COBOL Mapped to COBOL_ASSIGN_ COBOLFILEINFO COBOL and CRE Yes COBOLSPOOLOPEN COBOL No CREATEPROCESS COBOL No DELETEASSIGN COBOL No DELETEPARAM COBOL No DELETESTARTUP COBOL No GETASSIGNTEXT COBOL No GETASSIGNVALUE COBOL No GETBACKUPCPU COBOL No GETPARAMTEXT COBOL No GETSTARTUPTEXT COBOL No PUTASSIGNTEXT COBOL No PUTASSIGNVALUE COBOL No PUTPARAMTEXT COBOL No PUTSTARTUPTEXT COBOL No * Routines for the non-CRE environment are available only in the Guardian environment. COBOLFILEINFO is available in the CRE but only in the Guardian environment. The material in this COBOLLIB overview applies to SMU and non-SMU routines. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -27 Libraries and Utility Routines COBOLLIB Routines in User Code Space You can put the routines that are in the file COBOLLIB in any one of these places: • • • • COBOLLIB Routines in User Code Space COBOLLIB Routines in User Library Space COBOLLIB Routines in a Special TNS User Library COBOLLIB Routines in System Code Space Topics Sources SMU routines in general Saved Message Utility (SMU) Overview Descriptions of individual SMU routines Saved Message Utility (SMU) Overview ZCOBSRL file ZCOBSRL Overview ZCRESRL file ZCRESRL Overview Descriptions of non-SMU individual COBOLLIB and ZCOBSRL routines COBOLLIB, CLULIB, and ZCOBSRL Routines COBOLLIB Routines in User Code Space When you want to use a routine from the COBOLLIB file, you can have it bound into your loadfile to run in your user code space. Include a SEARCH directive that specifies $SYSTEM.SYSTEM.COBOLLIB (or the volume and subvolume where your installation has stored the COBOLLIB file). COBOLLIB Routines in User Library Space You can set up the routines from the COBOLLIB file to run in the user library space. To do this, include a LIBRARY directive of the form ?LIBRARY $SYSTEM.SYSTEM.COBOLLIB during your compilation. The compiler must be able to validate your ENTER statement, which requires the CBLIBEXT file—see Files of Dummy Routines. For more information on user libraries, see the Binder Manual. COBOLLIB Routines in a Special TNS User Library You can use Binder to create a special TNS user library of your own that includes whichever routines you need from the COBOLLIB file, and use the LIBRARY directive to make that your user library. For more information on TNS user libraries, see the Binder Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -28 Libraries and Utility Routines COBOLLIB Routines in System Code Space COBOLLIB Routines in System Code Space If you want the routines from the COBOLLIB file to run as part of the system library, and hence in the system code space, then your system manager must have incorporated the routines in the system library at system generation time. The COBOL85 compiler must be able to validate your ENTER statement, which requires the file CBLIBEXT. CBLIBEXT is part of every HP COBOL product version. It contains empty declarations of the COBOLLIB routines. Your system manager can bind all the CBLIBEXT routines into COBOLEXT. If you want the COBOLLIB routines to execute outside your user code space, you can arrange this. The COBOL85 compiler does not accept ENTER statements unless the compilers can verify that the parameters in the statement correspond to those expected by the routine being called. ZCOBSRL Overview ZCOBSRL, a native SRL, is the native HP COBOL run-time library. It contains the HP COBOL run-time routines which, for the COBOL85 compiler, reside in either the system library, CBL85UTL, or COBOLLIB. ZCOBSRL routines are not bound into a user object file. The NMCOBOL compiler consults ZCOBSRL automatically. ZCOBSRLs resides on the subvolume $SYSTEM.SYSnn. Table 13-9. ZCOBSRL Routines (page 1 of 2) Utility Routine COBOL_ASSIGN_ COBOL_COMPLETION_ COBOL_CONTROL_ COBOL_FILE_INFO_ COBOL_GETENV_ COBOL_PUTENV_ COBOL_RETURN_SORT_ERRORS_ COBOL_REWIND_SEQUENTIAL_ COBOL_SETMODE_ COBOL_SET_SORT_PARAM_TEXT_ 1. Replaces COBOLSPOOLOPEN routine (for level 2 spooling) and Guardian environment routines (for level 3 spooling) 2. Guardian environment only HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -29 Libraries and Utility Routines CLULIB Overview Table 13-9. ZCOBSRL Routines (page 2 of 2) Utility Routine COBOL_SET_SORT_PARAM_VALUE_ COBOL_SPECIAL_OPEN_1 COBOLFILEINFO2 1. Replaces COBOLSPOOLOPEN routine (for level 2 spooling) and Guardian environment routines (for level 3 spooling) 2. Guardian environment only For descriptions of individual ZCOBSRL routines, see: • • CBL85UTL and ZCOBSRL Routines COBOLLIB, CLULIB, and ZCOBSRL Routines. CLULIB Overview The Common Language Utility library (CLULIB) contains functions that provide common services to two or more language products. Specifically, Common Language Utility (CLU) functions provide services that enable: • • • HP COBOL and FORTRAN routines to locate and identify file connectors (CLU_PROCESS_FILE_NAME_ routine) HP COBOL and FORTRAN routines to create processes using the conventions of the TACL command RUN (CLU_PROCESS_CREATE_ routine) HP COBOL, FORTRAN, and TAL routines to save and manipulate messages that the operating environment sends to processes (see Saved Message Utility (SMU) Overview) CLU functions differ from CRE functions in that: • • • CLU functions are in the file CLULIB, while CRE functions are in the file CRELIB CLU functions must be explicitly bound into programs that use them, while CRE functions are configured into the system library CLU functions work in certain language-specific run-time environments as well as the CRE, while CRE functions work only in the CRE CLULIB routines must be used in the Guardian environment. Table 13-10. CLULIB Routines (page 1 of 2) Utility Routine Environments CLU_PROCESS_CREATE_ COBOL and CRE CLU_PROCESS_FILE_NAME_ COBOL and CRE SMU_Assign_CheckName_ CRE/Guardian HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -30 Libraries and Utility Routines Saved Message Utility (SMU) Overview Table 13-10. CLULIB Routines (page 2 of 2) Utility Routine Environments SMU_Assign_Delete_ CRE/Guardian SMU_Assign_GetText_ CRE/Guardian SMU_Assign_GetValue_ CRE/Guardian SMU_Assign_PutText_ CRE/Guardian SMU_Assign_PutValue_ CRE/Guardian SMU_Message_CheckNumber_ CRE/Guardian SMU_Param_Delete_ CRE/Guardian SMU_Param_GetText_ CRE/Guardian SMU_Param_PutText_ CRE/Guardian SMU_Startup_Delete_ CRE/Guardian SMU_Startup_GetText_ CRE/Guardian SMU_Startup_PutText_ CRE/Guardian The CLULIB file is only for the COBOL85 compiler. Its routines are also in the ZCRESRL file, which is for the NMCOBOL compiler. Topics Sources CLU_PROCESS_CREATE_ routine CLU_PROCESS_FILE_NAME_ routine CRE Programmer’s Guide ZCRESRL file ZCRESRL Overview Saved Message Utility (SMU) Overview The Saved Message Utility (SMU) consists of several routines that manipulate saved ASSIGN, PARAM, and startup messages. SMU routines can be used only in the Guardian environment. The Open System Services environment does not have ASSIGN, PARAM, or startup messages. The internal data structures of the saved ASSIGN, PARAM, and startup messages differ from COBOL data structures. SMU routines retrieve, replace, alter, or delete components of saved messages and reformat them either to or from a specific external representation. (For descriptions of the ASSIGN, PARAM, and startup messages, see the Guardian Programmer’s Guide.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -31 Libraries and Utility Routines Saved Message Utility (SMU) Overview Figure 13-3. Effect of Saved Message Utility (SMU) Routines Startup Message (IN, OUT, default volume and subvolume) ASSIGNs (fd-name = actual-file-name) PARAMs (name and associated value) "Parent" COBOL process Saves the messages Saved Messages Modifies the messages Uses CREATEPROCESS to launch a new process that has customtailored ASSIGN, PARAM, and startup messages Descendent Process VST521.vsd Programs compiled with the COBOL85 compiler can call all of the SMU routines listed in Table 13-1. Programs compiled with the NMCOBOL compiler can call only the new routines. Table 13-11. Saved Message Utility (SMU) Routines (page 1 of 2) Original Routine1 New Routine2 ALTERPARAMTEXT None CHECKLOGICALNAME SMU_Assign_CheckName_ CHECKMESSAGE SMU_Message_CheckNumber_ DELETEASSIGN SMU_Assign_Delete_ DELETEPARAM SMU_Param_Delete_ DELETESTARTUP SMU_Startup_Delete_ GETASSIGNTEXT SMU_Assign_GetText_ 1. In the COBOLLIB file. Extension to the HP COBOL and FORTRAN 77 products, except as noted. 2. In the CLULIB file for the COBOL85 compiler and the ZCRESRL file for the NMCOBOL compiler. 3. In the OSS environment, you can also use the HP C getenv function. SMU_Param_GetText_ returns only PARAM equivalents, but the HP C getenv function returns other environment variables as well. 4. Not an extension to the HP COBOL and FORTRAN 77 products HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -32 Libraries and Utility Routines Saved Message Utility (SMU) Overview Table 13-11. Saved Message Utility (SMU) Routines (page 2 of 2) Original Routine1 New Routine2 GETASSIGNVALUE SMU_Assign_GetValue_ GETBACKUPCPU None GETPARAMTEXT SMU_Param_GetText_3 GETSTARTUPTEXT SMU_Startup_GetText_ PUTASSIGNTEXT SMU_Assign_PutText_ PUTASSIGNVALUE SMU_Assign_PutValue_ PUTPARAMTEXT4 SMU_Param_PutText_ PUTSTARTUPTEXT SMU_Startup_PutText_ 1. In the COBOLLIB file. Extension to the HP COBOL and FORTRAN 77 products, except as noted. 2. In the CLULIB file for the COBOL85 compiler and the ZCRESRL file for the NMCOBOL compiler. 3. In the OSS environment, you can also use the HP C getenv function. SMU_Param_GetText_ returns only PARAM equivalents, but the HP C getenv function returns other environment variables as well. 4. Not an extension to the HP COBOL and FORTRAN 77 products Table 13-12. Message Operated Upon by Saved Message Utility (SMU) Routines Messages Operated Upon Function STARTUP CHECK ASSIGN PARAM CHECKLOGICALNAME SMU_Assign_CheckName_ CHECKMESSAGE SMU_Message_CheckNumber_ GET GETSTARTUPTEXT GETASSIGNTEXT GETPARAMTEXT SMU_Startup_GetText_ SMU_Assign_GetText_ SMU_Param_GetText_ GETASSIGNVALUE GETBACKUPCPU SMU_Assign_GetValue_ PUT PUTSTARTUPTEXT PUTASSIGNTEXT PUTPARAMTEXT SMU_Startup_PutText_ SMU_Assign_PutText_ SMU_Param_PutText_ PUTASSIGNVALUE SMU_Assign_PutValue_ DELETE ALTER DELETESTARTUP DELETEASSIGN DELETEPARAM SMU_Startup_Delete_ SMU_Assign_Delete_ SMU_Param_Delete_ ALTERPARAMTEXT HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -33 Libraries and Utility Routines Saved Message Utility (SMU) Overview The SMU consists of these routines. For complete descriptions of these routines, see Saved Message Utility (SMU) Routines. Routine Description ALTERPARAMTEXT Creates or replaces the value for a specific parameter name, in the saved PARAM message (enables you to include trailing spaces in the new value, unlike the PUTPARAMTEXT routine) CHECKLOGICALNAME SMU_Assign_CheckName_ Checks whether a saved ASSIGN message with a given logical file name exists CHECKMESSAGE Checks whether a specific saved message exists SMU_Message_CheckNumber_ DELETEASSIGN SMU_Assign_Delete_ DELETEPARAM Deletes either a portion or all of a saved ASSIGN message SMU_Param_Delete_ Deletes either a portion or all of the saved PARAM message DELETESTARTUP Deletes the entire saved startup message SMU_Startup_Delete_ GETASSIGNTEXT SMU_Assign_GetText_ GETASSIGNVALUE SMU_Assign_GetValue_ Retrieves a portion of a saved ASSIGN message as text and assigns it to a string variable Retrieves a portion of a saved ASSIGN message as an integer and assigns it to an integer variable GETBACKUPCPU Retrieves a backup processor number from the saved PARAM message GETPARAMTEXT Retrieves a portion of the saved PARAM message as text and assigns it to a string variable SMU_Param_GetText_ GETSTARTUPTEXT SMU_Startup_GetText_ PUTASSIGNTEXT SMU_Assign_PutText_ PUTASSIGNVALUE SMU_Assign_PutValue_ PUTPARAMTEXT SMU_Param_PutText_ PUTSTARTUPTEXT SMU_Startup_PutText_ Retrieves a portion of the saved startup message as text and assigns it to a string variable Creates or replaces a portion of a saved ASSIGN message with text from a string variable Creates or replaces a portion of a saved ASSIGN message with a value from an integer variable Creates or replaces a portion of the saved PARAM message with text from a string variable Creates or replaces a portion of the saved startup message with text from a string variable HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -34 Libraries and Utility Routines Checkpoint Lists for Process Pairs These routines operate upon copies of the process-creation messages that establish the execution environment of the program. Copies of these messages are not saved automatically and must be requested by a SAVE directive in the main program. For information on the SAVE directive, see SAVE. Topics: • • Checkpoint Lists for Process Pairs (non-CRE environment only) Defined Portions of Saved Messages Checkpoint Lists for Process Pairs This topic applies only to non-CRE SMU routines, as CRE SMU routines do not support checkpointing. In an HP COBOL program, the saved message storage space is not part of the direct variable space. When a program designed to run as a process pair needs to change or delete saved messages, it needs a checkpoint list. A checkpoint list is a COBOL record with a specific structure in which the message changes are recorded. (Examples of checkpoint lists are given in the individual routine descriptions in Saved Message Utility (SMU) Routines where required.) The information in a checkpoint list must be transmitted to the backup member of a process pair, just as values of critical HP COBOL program variables must. This is the purpose of the CHECKPOINT statement. When a checkpoint list appears in a CHECKPOINT statement, the reserved word QUEUE must precede its name. Checkpoint lists can be mixed with any of the other items that are legal in a CHECKPOINT statement, as in this example: CHECKPOINT ITEM-1, QUEUE CP-LIST-1, ITEM-2, FILE ITEM-3. The compiler interprets CP-LIST-1 as a checkpoint list and checkpoints the information it contains and the values of the other items. It then resets CP-LIST-1 to empty so that its information storage space is available to record further message changes. Caution. An HP COBOL program must not modify the contents of a checkpoint list directly. The execution logic of the routines and the CHECKPOINT statement maintain checkpoint lists without any other program action. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -35 Libraries and Utility Routines Defined Portions of Saved Messages Defined Portions of Saved Messages The SMU routines operate on the ASSIGN, PARAM, and startup messages, which have standard sets of defined portions. Table 13-13. Portions of the ASSIGN Message Portion What It Identifies Portion Type LOGICALNAME Logical unit name Text message portion TANDEMNAME File-system file name Text message portion PRIEXT Primary extent size Integer message portion SECEXT Secondary extent size Integer message portion FILECODE File code Integer message portion EXCLUSION Exclusion mode Integer message portion ACCESS Access mode Integer message portion RECSIZE Record size Integer message portion BLKSIZE Block size Integer message portion Table 13-14. Portions of the Startup Message Portion What It Identifies Portion Type VOLUME Default volume and subvolume names Text message portion IN Input file name Text message portion OUT Output file name Text message portion STRING Message’s parameter string Text message portion The PARAM message portions consist of the set of parameter names and their values. A legal parameter name identifier is any combination of letters, digits, hyphens, and circumflexes. It can contain a maximum of 30 characters. Table 13-15. Portions of the PARAM Message Portion What It Identifies Portion Type Parameter name Associated parameter value Text message portion HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -36 Libraries and Utility Routines ZCRESRL Overview ZCRESRL Overview ZCRESRL, a native SRL (public shared run-time library), is the native CRE run-time library. It contains the CRE routines which, for the COBOL85 compiler, resided in either the system library or CLULIB—that is, the CRE versions of the SMU routines. ZCRESRL routines are not bound into a user object file. The NMCOBOL compiler consults ZCRESRL automatically. ZCRESRL resides on the subvolume $SYSTEM.SYSnn. The ZCRESRL routines are: • • • • • • • • • • • • • • CLU_PROCESS_CREATE_ SMU_Assign_CheckName_ SMU_Assign_Delete_ SMU_Assign_GetText_ SMU_Assign_GetValue_ SMU_Assign_PutText_ SMU_Assign_PutValue_ SMU_Message_CheckNumber_ SMU_Param_Delete_ SMU_Param_GetText_ SMU_Param_PutText_ SMU_Startup_Delete_ SMU_Startup_GetText_ SMU_Startup_PutText_ CLU_PROCESS_CREATE_ is available in the Guardian and OSS environments, but the SMU routines are available only in the Guardian environment. Topics Sources CLU_PROCESS_CREATE_ routine CRE Programmer’s Guide Other ZCRESRL routines Saved Message Utility (SMU) Routines HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -37 Libraries and Utility Routines CBL85UTL and ZCOBSRL Routines CBL85UTL and ZCOBSRL Routines This topic explains the individual routines in the CBL85UTL file, which is for the COBOL85 compiler. The CRE routines are also in the ZCOBSRL file, which is for the NMCOBOL compiler. Table 13-16. CBL85UTL and ZCOBSRL Routines COBOL-Environment Routine1 CRE Routine2 COBOL85^ARMTRAP None (unnecessary) COBOL85^COMPLETION COBOL_COMPLETION_ None COBOL_CONTROL_ None COBOL_GETENV_ None COBOL_PUTENV_ COBOL85^RETURN^SORT^ERRORS3 COBOL_RETURN_SORT_ERRORS_3 COBOL85^REWIND^SEQUENTIAL COBOL_REWIND_SEQUENTIAL_ COBOL85^SET^SORT^PARAM^TEXT3 COBOL_SET_SORT_PARAM_TEXT_3 COBOL85^SET^SORT^PARAM^VALUE3 COBOL_SET_SORT_PARAM_VALUE_3 None COBOL_SET_MAX_RECORD_ None COBOL_SETMODE_ COBOL85^SPECIAL^OPEN2 COBOL_SPECIAL_OPEN_4 1. These routines are only in CBL85UTL, not in ZCOBSRL. 2. These routines are in both CBL85UTL and ZCOBSRL. 3. FastSort interface routine. 4. This routine replaces the COBOLSPOOLOPEN routine (for level 2 spooling) and Guardian environment routines (for level 3 spooling). The COBOLSPOOLOPEN routine is in the COBOLLIB library. Corresponding COBOL-environment and CRE routines have the same parameters, with this exception: COBOL85^COMPLETION has the parameter text-length, but COBOL_COMPLETION_ does not (the CRE gets the text length from the specified text instead). If you omit an optional parameter when you call a CBL85UTL or ZCOBSRL routine, you must put the keyword OMITTED in its position if you specify subsequent parameters. Trailing OMITTEDs are not required. (The syntax diagrams do not reflect this, because it would make them much harder to read.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -38 Libraries and Utility Routines COBOL85^ARMTRAP Topics: • • • • • • • • • • • • COBOL85^ARMTRAP COBOL85^COMPLETION and COBOL_COMPLETION_ COBOL_CONTROL_ COBOL_GETENV_ COBOL_PUTENV_ COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ COBOL_SET_MAX_RECORD_ COBOL_SETMODE_ COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ COBOL85^ARMTRAP The COBOL85^ARMTRAP routine stops a process when an arithmetic overflow occurs. Without COBOL85^ARMTRAP, the process would enter the selected debugger (see Debugger Selection). Use the COBOL85^ARMTRAP routine in the Guardian environment. ns ENTER " ns COBOL85^ARMTRAP " VST341.vsd If an arithmetic overflow occurs, COBOL85^ARMTRAP either stops the process in which the overflow occurred or enters the selected debugger. In either case, it also writes a run-time diagnostic message to the output device. COBOL85^ARMTRAP is unavailable and unnecessary in the CRE and native HP COBOL. Topics Sources Debugger selection Debugger Selection Run-time diagnostic messages Section 48, Run-Time Diagnostic Messages HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -39 Libraries and Utility Routines COBOL85^COMPLETION and COBOL_COMPLETION_ COBOL85^COMPLETION and COBOL_COMPLETION_ The COBOL85^COMPLETION and COBOL_COMPLETION_ routines pass completion parameters to either the STOP or ABEND routine in the operating environment (depending on the abend-or-stop parameter). ns ENTER " ns COBOL85^COMPLETION " TAL OF library-reference USING abend-or-stop completion-code termination-info subsys-id text-length text VST342.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -40 Libraries and Utility Routines COBOL85^COMPLETION and COBOL_COMPLETION_ The CRE equivalent of COBOL85^COMPLETION is COBOL_COMPLETION_. Unlike COBOL85^COMPLETION, COBOL_COMPLETION_ does not accept the parameter text-length. ns ENTER " ns COBOL_COMPLETION_ " TAL OF library-reference USING abend-or-stop completion-code termination-info subsys-id text VST343.vsd library-reference is a mnemonic-name in the SPECIAL-NAMES paragraph. For the COBOL85 compiler, this mnemonic-name is associated with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL85^COMPLETION. For the NMCOBOL compiler, this mnemonicname is associated with either $SYSTEM.SYSnn.ZCOBSRL or some other object file containing an object copy of COBOL_COMPLETION_. abend-or-stop is a numeric operand that specifies either the STOP or ABEND routine. abendor-stop is evaluated and truncated to produce an integer result with a value in the range of -32,768 through 32,767. The value 0 specifies the STOP routine; all other values specify the ABEND routine. The default is 0. completion-code is a numeric operand, the evaluation of which includes truncation as necessary to an integer result with a value in the range of -32,768 through 32,767. If this parameter is present, the value is passed to STOP or ABEND as the completion-code parameter for that routine. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -41 Libraries and Utility Routines COBOL85^COMPLETION and COBOL_COMPLETION_ termination-info is a numeric operand, the evaluation of which includes truncation as necessary to an integer result with a value in the range of -32,768 through 32,767. If this parameter is present, the value is passed to STOP or ABEND as the termination-info parameter for that routine. subsys-id is a data item occupying at least twelve character positions. If this parameter is present, a reference to the data item is passed to STOP or ABEND as the subsys-id parameter for that routine. text-length is a numeric operand, the evaluation of which includes truncation as necessary to an integer result. If this parameter is present, the value is passed to STOP or ABEND as the length parameter for that routine. text is an alphanumeric data item containing at least as many characters as specified by the value of text-length (alphabetic and alphanumeric-edited data items are also permissible). If this parameter is present, a reference to the data item is passed to STOP or ABEND as the text parameter for that routine. Usage Considerations: • Parameters Are Not Validated When the run unit calls COBOL85^COMPLETION or COBOL_COMPLETION_, the HP COBOL run-time routines terminate execution of the run unit in an orderly fashion. The final step in the termination logic is to call either the STOP or the ABEND routine of the operating environment (as specified by the implicit or explicit abend-or-stop parameter value). All other parameters are made available to the STOP or ABEND routine as described previously. It is the application’s responsibility to verify that the combination of supplied parameters and their values meet the expectations of the STOP or ABEND routine. Neither the COBOL85^COMPLETION routine, the COBOL_COMPLETION_ routine, nor the HP COBOL run-time routines validate the parameters. • Calling COBOL85^COMPLETION or COBOL_COMPLETION_ From the CRE A CRE HP COBOL program can call either COBOL85^COMPLETION (the COBOL-environment routine) or COBOL_COMPLETION_ (the equivalent CRE routine). If it calls COBOL85^COMPLETION, it actually calls COBOL_COMPLETION_ indirectly. COBOL85^COMPLETION has the parameter text-length, but COBOL_COMPLETION_ does not (the CRE gets the text length from the specified text instead). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -42 Libraries and Utility Routines COBOL_CONTROL_ COBOL_CONTROL_ The COBOL_CONTROL_ routine controls device-dependent I-O operations through a call to the Guardian environment routine CONTROL. If a no-waited, input-output request is active when the COBOL_CONTROL_ routine is called, the request is completed before the CONTROL routine is called. If the file is closed when the call is made, the request is queued until the next OPEN request for the file is issued. Caution. The HP COBOL run-time library does not attempt to validate calls to CONTROL. To avoid interfering with the operation of the HP COBOL run-time library, use COBOL_CONTROL_ only if absolutely necessary. " ENTER OF ns COBOL_CONTROL_ ns " library-reference USING file-name GIVING operation param error-return cpinfo VST610.vsd library-reference is a mnemonic-name in the SPECIAL-NAMES paragraph. For the COBOL85 compiler, this mnemonic-name is associated with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL_CONTROL_. For the NMCOBOL compiler, this mnemonic-name is associated with either $SYSTEM.SYSnn.ZCOBSRL or some other object file containing an object copy of COBOL_CONTROL_. file-name is a COBOL file name associated with a file that is not $RECEIVE and that is not open for HP COBOL Fast I-O. If the file is not open, the call to the Guardian environment routine CONTROL is made during the next successful open request for the file. operation is a numeric data item or arithmetic expression that is the operation parameter of the Guardian environment routine CONTROL. For more information, see the Guardian Procedure Calls Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -43 Libraries and Utility Routines COBOL_CONTROL_ param is a numeric data item or arithmetic expression that is the param parameter of the Guardian environment routine CONTROL. For more information, see the Guardian Procedure Calls Reference Manual. cpinfo is a checkpoint list in which the routine records the changes to the message storage data space, for example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cpinfo can contain. In the CRE, the maximum number of elements that cpinfo can contain is the initial value of MAX-COUNT divided by 2.5. The cpinfo in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 03 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. error-return is a numeric data item that has one of these values upon completion: Value Meaning (page 1 of 2) n The call to CONTROL caused Guardian file error n. 0* No error occurred. 1 A required parameter is missing. *error-return is 0 for a deferred call (that is, one that is held until the file is open). If an error occurs at that time, a run-time diagnostic is issued. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -44 Libraries and Utility Routines COBOL_GETENV_ Value Meaning (page 2 of 2) 2 file-name is not a COBOL file name. 5 One of: • • • file-name specifies an open file that is either $RECEIVE or is open for Fast I-O. file-name specifies a closed file and there is not enough control space to allocate the queued information for the next open request. The program is running in the non-CRE environment and cpinfo has too few entries. *error-return is 0 for a deferred call (that is, one that is held until the file is open). If an error occurs at that time, a run-time diagnostic is issued. Usage Consideration: In a fault-tolerant program, put the CHECKPOINT statement that specifies cpinfo immediately before the call to COBOL_CONTROL_; otherwise, the queued information can be lost if a backup process takes over. COBOL_GETENV_ The COBOL_GETENV_ routine returns the value of a specified environment variable. This routine is available only to programs compiled for the CRE. ns ENTER " ns COBOL_GETENV_ USING env-var GIVING length " return-value VST722.vsd env-var is the name of the environment variable whose value is to be returned. It cannot have trailing spaces or a zero-byte terminator. return-value is the name of the variable that will hold the returned value of env-var. It must be large enough to hold the maximum possible value of env-var. length is the number of characters that return-value contains. If length is zero, env-var was not found. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -45 Libraries and Utility Routines COBOL_PUTENV_ COBOL_PUTENV_ The COBOL_PUTENV_ routine sets a specified environment variable to a specified value. This routine is available only to programs compiled for the CRE. ENTER " ns COBOL_PUTENV_ USING env-var GIVING return-value ns " VST723.vsd env-var is the name of the environment variable whose value is to be set. It cannot have trailing spaces or a zero-byte terminator. return-value is zero if the value of env-var was successfully set, nonzero if the value of envvar was not set because of insufficient heap space. COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ The COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ routines return any error message from the FastSort utility program. " ENTER ns COBOL85^RETURN^SORT^ERRORS ns " COBOL_RETURN_SORT_ERRORS_ OF library-reference USING sd-name error-report GIVING return-code VST344.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -46 Libraries and Utility Routines COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ library-reference is a mnemonic-name in the SPECIAL-NAMES paragraph. For the COBOL85 compiler, this mnemonic-name is associated with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL85^RETURN^SORT^ERRORS. For the NMCOBOL compiler, this mnemonic-name is associated with either $SYSTEM.SYSnn.ZCOBSRL or some other object file containing an object copy of COBOL_RETURN_SORT_ERRORS_. sd-name is the COBOL name of a file defined in an SD entry. The specification of the remaining parameter is applied to any subsequent SORT or MERGE statements that refer to this file name. If a subsequent call to the same routine refers to the same sd-name, that call resets the specifications for any subsequent SORT or MERGE statements that refer to the same file name. error-report is an 01 level item with this structure: 01 error-info 02 error-message-text 02 error-message-length 02 error-code. 03 file-system-code 03 input-file-index 03 sort-code 02 error-source 02 subsort-index 02 subsort-id PIC X(64). NATIVE-2. NATIVE-2. NATIVE-2. NATIVE-2. NATIVE-2. NATIVE-2. NATIVE-2 For the meaning of these fields, see the FastSort Manual discussion of SORTERRORSUM. The input-file-index and sort-code are partial word fields in that section, but are full word fields in the above record. If this parameter is omitted, any previously set error reporting is cleared. return-code is an identifier of a numeric data item in which an error value will be returned. The expected values and their respective meanings are: Value Meaning 0 The call was correct. 1 file-name does not name a sort-merge file. 2 error-report is not the correct length. 5 Space for the options block cannot be allocated. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -47 Libraries and Utility Routines COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ Usage Considerations: • Error Detection and Reporting If the process calls COBOL85^RETURN^SORT^ERRORS or COBOL_RETURN_SORT_ERRORS_ before it executes a SORT or MERGE statement, the HP COBOL run-time library returns the appropriate values in error-info after execution of a a RELEASE, RETURN, SORT, or MERGE statement. If the sort/merge routines do not detect errors during the execution of one of the above statements, sort-code is set to 0 and the contents of the other data items is undefined (unpredictable). If the sort/merge routines do detect an error, the HP COBOL run-time routines terminate execution of the sort process and return to the program with the fields of error-info set to the values returned by the sort/merge routines. The HP COBOL run-time routines do not produce error messages of their own (they typically go to the home terminal), and no recovery is possible. It is your responsibility to determine whether the operation is successful, and to determine how to proceed. If the error happened during execution of a RELEASE or RETURN statement, execution should proceed to the end of the input or output procedure, at which point it continues after the SORT or MERGE statement. If an error occurs without the process ever having made a call to COBOL85^RETURN^SORT^ERRORS or COBOL_RETURN_SORT_ERRORS_ (or if the error-report parameter was omitted, cancelling further error reporting), the HP COBOL run-time library processes sort errors, prints a message on the error file (normally the home terminal) that has all of the above information, and abnormally terminates the run unit. • Calling COBOL85^RETURN^SORT^ERRORS or COBOL_RETURN_SORT_ERRORS_ From the CRE in the Guardian Environment In the Guardian environment, a CRE HP COBOL program can call either COBOL85^RETURN^SORT^ERRORS (the COBOL-environment routine) or COBOL_RETURN_SORT_ERRORS_ (the equivalent CRE routine). If it calls COBOL85^RETURN^SORT^ERRORS, it actually calls COBOL_RETURN_SORT_ERRORS_ indirectly. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -48 Libraries and Utility Routines COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ The COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ routines enable you to reposition a sequential disk or single-file tape file to its beginning without closing and reopening it. ENTER ns " COBOL85^REWIND^SEQUENTIAL ns " COBOL_REWIND_SEQUENTIAL_ OF library-reference USING file-name GIVING return-code VST345.vsd library-reference is a mnemonic-name in the SPECIAL-NAMES paragraph. For the COBOL85 compiler, this mnemonic-name is associated with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL85^REWIND^SEQUENTIAL. For the NMCOBOL compiler, this mnemonic-name is associated with either $SYSTEM.SYSnn.ZCOBSRL or some other object file containing an object copy of COBOL_REWIND_SEQUENTIAL_. file-name is the name of a COBOL data file; that is, a file described in a File Description entry. It must be an FD name associated with a file name that specifies an unstructured or entry sequenced file. return-code is an identifier of a numeric data item in which an error value will be returned. The expected values and their respective meanings are: Value Meaning 0 Successful execution 1 file-name is missing or is invalid. 5 An operation error occurred (for example, the file could not be rewound). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -49 Libraries and Utility Routines COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ Usage Considerations: • File Criteria file-name must be a valid COBOL file name, the file associated with filename must be open at the time of the call and the file-control entry for file-name must specify ORGANIZATION SEQUENTIAL. If these criteria are not met, return-code (if specified) is set to 1, I-O Status for file-name is set to “30” (if file-name is a COBOL file name), GUARDIANERR is set to 0, and no action is taken on the file (the rewind operation is considered to be unsuccessful, but execution of the run unit continues). • Successful Rewind Operation If the rewind operation is successful, the run-time routine rewinds the file if rewinding or the concept of rewinding applies to the file, I-O Status is set to “00,” and GUARDIAN-ERR is set to 0. • If Rewind Does Not Apply to the File If rewinding does not apply to the file (a printer for example), I-O Status is set to “07,” GUARDIAN-ERR is set to 0, and the operation is a “no-op.” • File Position Indicator For all files, the file position indicator is set as if the file were newly opened. If alternate keys are specified for the file, the key of reference is set to the prime key. • Calling COBOL85^REWIND^SEQUENTIAL or COBOL_REWIND_SEQUENTIAL_ From the CRE A CRE HP COBOL program can call either COBOL85^REWIND^SEQUENTIAL (the COBOL-environment routine) or COBOL_REWIND_SEQUENTIAL_ (the equivalent CRE routine). If it calls COBOL85^REWIND^SEQUENTIAL, it actually calls COBOL_REWIND_SEQUENTIAL_ indirectly. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -50 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ The COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ routines establish alphanumeric parameters in the option block (the local list of parameters that HP COBOL passes to FastSort for the next sort or merge operation). ns " ENTER COBOL85^SET^SORT^PARAM^TEXT ns " COBOL_SET_SORT_PARAM_TEXT_ OF library-reference USING sd-name param-id param-text subsort-number GIVING return-code VST346.vsd Note. COBOL85 only: COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ use a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name in the SPECIAL-NAMES paragraph. For the COBOL85 compiler, this mnemonic-name is associated with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL85^SET^SORT^PARAM^TEXT. For the NMCOBOL compiler, this mnemonic-name is associated with either $SYSTEM.SYSnn.ZCOBSRL or some other object file containing an object copy of COBOL_SET_SORT_PARAM_TEXT_. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -51 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ sd-name is the COBOL name of a file defined in an SD entry. The specification of the remaining parameter is applied to any subsequent SORT or MERGE statements that refer to this file name. If a subsequent call to a FastSort routine refers to the same sd-name and to the same parameter, that call resets the specifications for any subsequent SORT or MERGE statements that refer to the same file name. Certain parameters can be reset to their default values, as indicated in the discussion of the parameters below. param-id is one of: CPU-MASK SCRATCH-FILE SWAP-FILE NO-CPU-MASK SORT-PROGRAM param-text is the identifier of an alphanumeric data item whose contents is used for the parameter specified by param-id. If this parameter is omitted, any text previously set for this value of param-id is reset to its default value. The value of param-text depends on the value of param-id and sometimes on the value of subsort-number (see Table 13-17). subsort-number is a numeric operand whose value specifies the sort process to which the parameter pertains. The number of subsorts must have been set previously, and the specified subsort-number must be in the range 0 to that number. The value of subsort-number depends on the value of param-id (seeTable 13-17). return-code is an identifier of a numeric data item in which an error value will be returned. The expected values and their respective meanings are: Value Meaning 0 The call was correct. 1 file-name does not name a sort-merge file. 2 param-id is not one of the allowed values. 3 param-text does not conform to the expected values. 4 subsort-number was not within the range of the specified number of subsorts. 5 Space for the options block cannot be allocated. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -52 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ Table 13-17. Relationship Between param-id, subsort-number, and paramtext (page 1 of 2) param-id subsort-number param-text CPU-MASK Unspecified or 0 Contains a string of zeros and ones, with a maximum of 16 characters. The value of each character indicates whether a processor is to be used for subsort processes for a parallel sort. The leftmost character corresponds to processor 0, the next to 1, and so on, up to processor 15. If there are fewer than 16 characters, the unspecified ones are assumed to be 0. If the value of the data item is “0” (ASCII zero), that processor will not be used. If the value is “1,” that processor is a candidate for use. Any other value is an error. Default: All processors on the system are candidates for use. NO-CPU-MASK Unspecified or 0 Contains a string of zeros and ones, with a maximum of 16 characters. The value of each character indicates whether a processor is to be used for subsort processes for a parallel sort. The leftmost character corresponds to processor 0, the next to 1, and so on, up to processor 15. If there are fewer than 16 characters, the unspecified ones are assumed to be 0. If the value of the data item is “0” (ASCII zero), that processor will not be used. If the value is “1,” that processor is a candidate for use. Any other value is an error. NO-CPU-MASK overrides CPU-MASK. SCRATCH-FILE SORT-PROGRAM File system name of file to be used by sort as a scratch file. If only a volume name is specified, FastSort assigns a scratch file on that volume; otherwise, a legal file name must be specified. ASSIGN commands that specify that file name are ignored. Unspecified or 0 File in the ASSIGN clause for the SD used is used. Greater than 0 Scratch file is assigned on $SYSTEM for that subsort. Unspecified or 0 File-system file name of the file that contains the SORTPROG program. If SORTPROG is not specified or is specified with a value of all spaces, FastSort uses $SYSTEM.SYSTEM.SORTPROG. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -53 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ Table 13-17. Relationship Between param-id, subsort-number, and paramtext (page 2 of 2) param-id subsort-number SWAP-FILE param-text File-system file name of the file to be used for the extended memory swap file (must be on the local system). If the name is all spaces (the default value) or is not specified, the swap file is created on the same volume as the scratch file. If the scratch file is not local, the swap file is assigned on $SYSTEM. If param-id is omitted (param-text and subsort-number must also be omitted in this case), all values and text previously set for sdname will be reset to their default values. This option releases the option block (about 700 characters long), so you might want to use it if the SD will not be referenced again in this program. Unspecified or 0 If subsort-number is not specified or is 0, the scratch file for the distributor/collector is implied. If SUBSORT-COUNT is 0, the swap file for the normal sort process in assigned. Greater than 0 If SUBSORT-COUNT is greater than 0, the subsort-number indicates the subsort to which the swap file applies. Usage Consideration: In the Guardian environment, a CRE HP COBOL program can call either COBOL85^SET^SORT^PARAM^TEXT (the COBOL-environment routine) or COBOL_SET_SORT_PARAM_TEXT_ (the equivalent CRE routine). If it calls COBOL85^SET^SORT^PARAM^TEXT, it actually calls COBOL_SET_SORT_PARAM_TEXT_ indirectly. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -54 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ The COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ routines establish numeric parameters in the option block. These parameters affect any subsequent SORT statement execution. ns " ENTER COBOL85^SET^SORT^PARAM^VALUE ns " COBOL_SET_SORT_PARAM_VALUE_ OF library-reference USING sd-name param-id param-value GIVING subsort-or-file-number return-code VST347.vsd Note. COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ use a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name in the SPECIAL-NAMES paragraph. For the COBOL85 compiler, this mnemonic-name is associated with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL85^SET^SORT^PARAM^VALUE. For the NMCOBOL compiler, this mnemonic-name is associated with either $SYSTEM.SYSnn.ZCOBSRL or some other object file containing an object copy of COBOL_SET_SORT_PARAM_VALUE_. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -55 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ sd-name is the COBOL name of a file defined in an SD entry. The specification of the remaining parameter is applied to any subsequent SORT statements that refer to this file name. If a subsequent call to a FastSort routine refers to the same file name and to the same parameter, that call resets the specifications for any subsequent sort operations that refer to the same file name. Certain parameters can be reset to their default values, as indicated in the discussion of the parameters below. param-id is an alphanumeric data item whose contents identify the parameter whose value is to be set. The values param-id might contain are: BUFFER-SIZE MINSPACE SAVE-SCRATCH CPU MINTIME SCRATCH-BLOCK CREATE-NEW-OUTPUT NOPURGE-OUTPUT SCRATCH-CHECK CREATE-NEW-SCRATCH NOWAIT-IO SECOND-BUFFER DATA-SLACK OUT-FILE-EXCL SEGMENT IN-FILE-COUNT OUT-FILE-FORMAT SUBSORT-COUNT IN-FILE-EXCL PRIORITY OUT-FILE-EXCL INDEX-SLACK REMOVE-DUPLICATES SYSTEM Any letter in the value can be either uppercase or lowercase. If param-id, param-value, and subsort-or-file-number are all omitted, the run-time routines reset all values and texts previously set for sd-name to their default values. This option releases the option block (about 700 characters long), so you may wish to use it if the SD will not be referenced again in this program. param-value is a numeric operand whose value gives the value to be used for the parameter specified by param-id. If this parameter is omitted, any value previously set for this value of param-id will be reset to its default value. In the case where a value may be zero or nonzero, the nonzero value must be greater than -2,147,483,648 and less than 2,147,483,648. If it is outside this range, an arithmetic overflow will result when the ENTER statement executes. The value of param-value depends on the value of param-id. See Usage Considerations:. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -56 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ subsort-or-file-number is a numeric operand whose value is the sort process to which the parameter pertains or, if the parameter applies to a file, it is a file ordinal. If a subsort-number is being supplied, the number of subsorts must have been set previously (with the SUBSORT-COUNT parameter) and subsort-number must be in the range 1 to that number. Subsort-number must be 0 if the parameter applies to the distributor/collector process or if the number of subsorts has been set to zero (a normal sort is implied). In the latter case, the parameter applies to the normal sort. return-code is an identifier of a numeric data item in which an error value will be returned. The expected values and their respective meanings are: Value Meaning 0 The call was correct. 1 The file-name does not name a sort-merge file. 2 The param-id does not have one of the allowed values. 3 The param-value is outside the allowed range. 4 If subsort-or-file-number is used to specify subsort-number, one of these is true: • • • subsort-number was not within the range of the specified number of subsorts. subsort-number was required but not specified. subsort-number was specified, was nonzero and a subsort-number was not legal for this parameter. If subsort-or-file-number is used to specify file-number, then file-number is not within the range 1 through 32. 5 Space for the options block cannot be allocated. Usage Considerations: • Calling COBOL85^SET^SORT^PARAM^VALUE or COBOL_SET_SORT_PARAM_VALUE_ in the CRE A CRE HP COBOL program can call either COBOL85^SET^SORT^PARAM^VALUE (the COBOL-environment routine) or COBOL_SET_SORT_PARAM_VALUE_ (the equivalent CRE routine). If it calls COBOL85^SET^SORT^PARAM^VALUE, it actually calls COBOL_SET_SORT_PARAM_VALUE_ indirectly. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -57 Libraries and Utility Routines • COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ Value of param-value Depends on Value of param-id The default for each param-value is the same as the default for its param-id. For example, if you do not specify BUFFER-SIZE, you get the same result as you do if you specify BUFFER-SIZE with no param-value : you get 8192. ° BUFFER-SIZE specifies the size of the buffer used for processing records when an input procedure or an output procedure is specified. The value of param-value must be greater than 4095 and less than 8193. The default is 8192. subsort-or-file-number must not be specified or must be 0. ° CPU specifies a processor in which the sort or subsort is to occur. Allowable Value for param-value -1 Meaning If the param-value associated with SUBSORT-COUNT is 0 or has not been specified, the sort process selects a processor. If the param-value associated with SUBSORT-COUNT is greater than 1, the selection of a processor depends on subsortor-file-number: • • 0 - maximum processor number of the system If subsort-or-file-number is 0 or not specified, the processor for the distributor/collector process will be the same as that in which the run unit is executing. If subsort-or-file-number is greater than 0, the sort process will select a processor for the specified subsort depending on CPU-MASK and NO-CPU-MASK. Specifies a specific processor. If the param-value associated with SUBSORT-COUNT is 0 or not specified the processor selected will be used for the distributor/collector process. If subsort-or-file-number is specified, it indicates which subsort will use the specified processor. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -58 Libraries and Utility Routines ° COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ CREATE-NEW-OUTPUT specifies whether the output (GIVING) file is to be created anew or the existing output file is to be used. Allowable Value for param-value Meaning 0 (default) If the output file exists and is large enough for the sort, the data is purged from the file. If the file is too small, the file is purged and a new one is created. nonzero The file is purged and a new one is created. subsort-or-file-number must not be specified or must be 0. ° CREATE-NEW-SCRATCH specifies whether the scratch file is to be created anew or the existing scratch file is to be used. Allowable Value for param-value Meaning 0 (default) If the scratch file exists and is large enough for the sort, the data is purged from the file. If the file is too small, the file is purged and a new one is created. nonzero The file is purged and a new one is created. subsort-or-file-number must not be specified or must be 0. ° DATA-SLACK specifies a percentage of slack space in each data block for an indexed output file. It is applicable only if one GIVING file is specified and that file is an indexed file. The value of param-value is in the range 0 through 99. The default is 0. subsort-or-file-number must not be specified or must be 0. ° IN-FILE-COUNT specifies the number of records that will be sorted from each input file or that will be supplied by an input procedure. FastSort uses it to determine the size of the scratch file. Allowable Value for param-value Meaning -1 (default) FastSort uses a default based on the file assigned. For disk files, FastSort calculates a number based on the file size. For tape files or if an input procedure is used, the default is 50K. 1 - 2,147,483,647 Number of records that will be sorted from each input file or that will be supplied by an input procedure. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -59 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ Large sorts (greater than 50K records) may terminate abnormally with the scratch file being too small if record-count is not used for sorts using tapes or sorts using an input procedure. Small sorts may use more system resources than necessary. If subsort-or-file-number specifies a file number, it must be in the range 1 through 32. The number is the ordinal number of a USING file (from left to right in the USING phrase of the next SORT statement that is executed). If an input procedure is to be used, subsort-or-file-number should be omitted or should be one. ° IN-FILE-EXCL specifies the exclusion mode with which the sort opens a USING file. Allowable Value for param-value Meaning -1 Default (exclusive for disk or tape, shared for any other file type) 0 Shared 1 Exclusive 3 Protected If subsort-or-file-number specifies a file-number, it must be in the range 1 through 32. The number is the ordinal number of a USING file (from left to right in the USING phrase of the next SORT statement that is executed). If subsort-or-file-number is omitted, the first file is assumed. ° INDEX-SLACK specifies a percentage of slack space in each index block for an indexed output file. It is applicable only if one GIVING file is specified and that file is an indexed file. The value of param-value is in the range 0 through 99. The default is 0. subsort-or-file-number must not be specified or must be 0. ° MINSPACE specifies whether FastSort is to operate in the MINSPACE mode; that is, whether FastSort should attempt to restrict the use of physical memory at the expense of sort time. Allowable Value for param-value Meaning 0 (default) FastSort uses up to 50% of the available physical memory. This may result in loss of overall system performance if the system is busy. nonzero FastSort uses a 64-page extended memory area. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -60 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ See the FastSort Manual for details. subsort-or-file-number must not be specified or must be 0. ° MINTIME specifies whether FastSort is to operate in the MINTIME mode; that is, whether FastSort should attempt to reduce execution time at the expense of physical memory. Allowable Value for param-value Meaning 0 (default) Operation is similar to MINSPACE mode. nonzero Up to 70% of the available memory will be used. See the FastSort Manual for details. subsort-or-file-number must not be specified or must be 0. ° NOPURGE-OUTPUT specifies whether FastSort is to purge an existing output (GIVING) file if it seems too small. Allowable Value for param-value Meaning 0 (default) FastSort purges an existing GIVING file that seems too small before writing the new data to it. nonzero FastSort does not purge an existing GIVING file that seems too small unless it has the wrong file type or wrong record length. subsort-or-file-number must not be specified or must be 0. • NOWAIT-IO specifies whether FastSort performs NOWAIT I-O in passing records to and from the HP COBOL run-time interface (for input and output procedures, for example). Allowable Value for param-value Meaning 0 (default) FastSort must use waited I-O. nonzero FastSort must use NOWAIT I-O. subsort-or-file-number must not be specified or must be 0. If paramvalue is nonzero, you must also specify SECOND-BUFFER. NOWAIT-IO is ignored if the file if being read or written by FastSort. If SECOND-BUFFER is not specified, FastSort error 74 occurs. If SECONDBUFFER cannot be allocated, run-time error 123 occurs, followed by FastSort error 74. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -61 Libraries and Utility Routines ° COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ OUT-FILE-EXCL specifies the exclusion mode with which the sort opens a GIVING file. Allowable values are: Value Exclusion Mode Specified -1 Default (exclusive for disk or tape, shared for any other file type) 0 Shared 1 Exclusive 3 Protected subsort-or-file-number must not be specified or must be 0. ° OUT-FILE-FORMAT specifies the format of the output file. Allowable values are 0, 1, 2, and 3. The default value is 0. See the FastSort Manual for details. This parameter may cause problems if the record area is not large enough or too large. Use it with caution. subsort-or-file-number must not be specified or must be 0. ° PRIORITY specifies the desired execution priority of the sort or subsort process. Allowable Value for param-value Meaning -1 (default) The process is to have the same priority as the calling process. 1 - 199 Specifies the desired priority. If the param-value associated with SUBSORT-COUNT is 0 or not specified, PRIORITY applies to the normal process and subsort-or-file-number must be omitted or 0. If the param-value associated with SUBSORT-COUNT is greater than 0, subsort-or-file-number specifies the subsort to which the priority applies; 0 refers to the distributor/collector process. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -62 Libraries and Utility Routines ° COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ REMOVE-DUPLICATES specifies whether FastSort should remove records with duplicate keys during the sort operation. Allowable Value for param-value Meaning 0 (default) Duplicates are not to be removed. nonzero FastSort must remove every record whose keys duplicate those of a previous record. subsort-or-file-number must not be specified or must be 0. ° SAVE-SCRATCH specifies whether FastSort should save the scratch file after a sort run. Allowable Value for param-value Meaning 0 (default) FastSort must purge the scratch file after the sort run. nonzero FastSort must save the scratch file, if it has an explicit name (provided by a call to COBOL85^SET^SORT^PARAM^TEXT or COBOL_SET_SORT_PARAM_TEXT_ with the SCRATCH-FILE parameter). subsort-or-file-number must not be specified or must be 0. ° SCRATCH-BLOCK specifies the size of the input and output blocks for the scratch file. Allowable Value for param-value Meaning -1 (default) FastSort chooses a default block size depending on the type of disk on which the scratch file resides. Any multiple of 512 in the range 512 through 32768 Size of the input and output blocks for the scratch file See the FastSort Manual for a description of this parameter. subsort-or-file-number must not be specified or must be 0. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -63 Libraries and Utility Routines ° COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ SCRATCH-CHECK specifies whether FastSort must check the size of each named scratch file to see whether it is large enough. Allowable Value for param-value Meaning 0 FastSort must check scratch file size. nonzero (default) FastSort must not check scratch file size. Nonzero is the default for HP COBOL—the default for the FastSort product by itself is 0). subsort-or-file-number must not be specified or must be 0. When the param-value associated with SUBSORT-COUNT is nonzero, each subsort requires a scratch file. You must first call COBOL85^SET^SORT^PARAM^TEXT or COBOL_SET_SORT_PARAM_TEXT_ once for each subsort, specifying a param-id of SCRATCH-FILE, a param-text giving a name for the scratch file (usually just a volume name), and a subsort-number. ° SECOND-BUFFER specifies whether FastSort must use a second buffer. Allowable Value for param-value Meaning 0 (default) FastSort does not use a second buffer. nonzero FastSort uses a second buffer, which is allocated in user data space. SECOND-BUFFER is ignored under any of these conditions: • • • There is not enough space for a second buffer. NOWAIT-IO is not specified. The operation is a merge and none of the USING files are magnetic tape files. subsort-or-file-number must not be specified or must be 0. ° SEGMENT specifies the size of the extended memory area, in pages. Allowable Value for param-value Meaning -1 (default) Segment size is controlled by the MINSPACE and MINTIME parameters. The size cannot be more than 90% of the processor’s physical memory not locked down by the NonStop operating system. 64 - 8192(16 MB) Size of the extended memory area, in pages. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -64 Libraries and Utility Routines COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ If subsort-or-file-number is specified, SEGMENT applies to the indicated subsort. If subsort-or-file-number is 0, SEGMENT applies to the distributor/collector process. If the param-value associated with SUBSORT-COUNT is 0 or not specified, SEGMENT applies to the normal sort, and subsort-or-file-number must be omitted or 0. ° SUBSORT-COUNT specifies the number of parallel sorts that FastSort is to use to improve performance. Allowable Value for param-value Meaning 0 (default) FastSort uses normal, non-parallel sort. 2-8 FastSort uses parallel sort, and the value of param-value is the number of processes to be used. (A parallel sort might be faster, but it uses more system resources. In a busy system, this might cause an overall loss in system throughput.) subsort-or-file-number must not be specified or must be 0. An error occurs if SUBSORT-COUNT has the value 1. ° SYSTEM specifies the system on which the sorting is to occur. A value other than -1 specifies that a particular other system will be used (which may result in very poor performance). Allowable Value for param-value Meaning -1 (default) Sorting occurs on the current system. valid system number Sorting occurs on the system specified by param-value. subsort-or-file-number must not be specified or must be 0. If the param-value associated with SUBSORT-COUNT is greater than 1, SYSTEM is ignored (the current system is used). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -65 Libraries and Utility Routines COBOL_SET_MAX_RECORD_ COBOL_SET_MAX_RECORD_ The COBOL_SET_MAX_RECORD_ routine sets the maximum record size in the COBOL internal file block. This routine is typically used to allow one file description (FD) to be used to write and read files whose maximum record lengths are less than or equal to that specified in the COBOL program. Without the use of this routine, if the file has a maximum record length that is shorter than that specified in the program, you can open the file in INPUT mode, but not in EXTEND or I-O mode. ns ENTER " USING ns COBOL_SET_MAX_RECORD_ " file-name new-length GIVING result VST737.vsd file-name is the COBOL file name of the file to be affected. It must be the name of a file defined by an FD, not a sort-merge file description (SD). In the non-CRE environment, the FD cannot contain the EXTERNAL phrase. At the time the ENTER statement is executed, the file connector referenced by file-name must not be open. new-length is the new maximum record size. It must be less than 4096 and must not be larger than the length specified in the RECORD clause in the FD; if no RECORD clause is specified, new-length must not be larger than the largest record description associated with the FD. The compiler cannot determine if the new size is too large; improper use can cause corruption when reading the file. It is your responsibility to ensure this does not happen. If you omit new-length, the run-time system queries the file that will be assigned when the file is opened and uses the maximum record length from that file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -66 Libraries and Utility Routines COBOL_SETMODE_ return is a variable into which the routine places a value indicating the success of the operation: Value Meaning 0 The operation was successful. 1 The first parameter is missing. 2 One of these occurred: • • • The first parameter is not a file-name of an FD. The second parameter is greater than 4095. For the non-CRE environment: the FD is external. 3 The second parameter has been omitted and no file exists from which to obtain the record length. 5 The file is not closed. Usage Consideration: If you use COBOL_ASSIGN_ or another method to assign the physical file before the OPEN occurs, that assignment must take place before you call COBOL_SET_MAX_RECORD_. COBOL_SETMODE_ The COBOL_SETMODE_ routine sets device-dependent functions using a call to the Guardian environment routine SETMODE. If a NOWAIT input-output request is active when the COBOL_SETMODE_ routine is called, the request is completed before the SETMODE routine is called. If the file is closed when the call is made, the request is queued until the next OPEN request for the file is issued. Caution. The HP COBOL run-time library does not attempt to validate calls to SETMODE. To avoid interfering with the operation of the HP COBOL run-time library, use COBOL_SETMODE_ only if absolutely necessary. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -67 Libraries and Utility Routines ENTER " OF COBOL_SETMODE_ ns COBOL_SETMODE_ ns " library-reference USING file-name function param-1 param-2 lastparams cpinfo GIVING error-return VST611.vsd library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL_SETMODE_. file-name is a COBOL file name associated with a file that is not $RECEIVE and is not open for HP COBOL Fast I-O. If the file is not open, the call to the Guardian environment routine SETMODE is made during the next successful open request for the file. function is a numeric data item or arithmetic expression that is the function parameter of the Guardian environment routine SETMODE. For more information, see the Guardian Procedure Calls Reference Manual. param-1 param-2 are numeric data items or arithmetic expressions that are the param1 and param2 parameters of the Guardian environment routine SETMODE. For more information, see the Guardian Procedure Calls Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -68 Libraries and Utility Routines COBOL_SETMODE_ lastparams is a data item at least four characters long that corresponds to the last-params parameter of the Guardian environment routine SETMODE. For best results, define it as a group with two NATIVE-2 data items immediately subordinate to it; for example: 01 LASTPARAMS 02 PARAM1 02 PARAM2 NATIVE-2 NATIVE-2 cpinfo is a checkpoint list in which the routine records the changes to the message storage data space. Example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cpinfo can contain. In the CRE, the maximum number of elements that cpinfo can contain is the initial value of MAX-COUNT divided by 2.5. The cpinfo in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 03 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. error-return is a numeric data item that has one of these values upon completion: Value Meaning (page 1 of 2) n The call to SETMODE caused Guardian file error n. 0* No error occurred. 1 A required parameter is missing. 2 file-name is not a COBOL file name. *error-return is 0 for a deferred call (that is, one that is held until the file is open). If an error occurs at that time, a run-time diagnostic is issued. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -69 Libraries and Utility Routines Value Meaning (page 2 of 2) 5 One of: • • • COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ file-name specifies an open file that is either $RECEIVE or is open for HP COBOL Fast I-O. file-name specifies a closed file and there is not enough control space to allocate the queued information for the next open request. The program is running in the non-CRE environment and cpinfo has too few entries. *error-return is 0 for a deferred call (that is, one that is held until the file is open). If an error occurs at that time, a run-time diagnostic is issued. Usage Consideration: In a fault-tolerant program, put the CHECKPOINT statement that specifies cpinfo immediately before the call to COBOL_SETMODE_; otherwise, the queued information can be lost if a backup process takes over. COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ The COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ routines open these: • • • • Printers or Spoolers System Log Files Partitioned Disk Files Tape Files in the CRE The COBOL file-control entry, file description entry, and OPEN statement do not provide a way to specify these attributes. Usage Considerations: • Calling COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ From the CRE in the Guardian Environment In the Guardian environment, a CRE HP COBOL program can call either COBOL85^SPECIAL^OPEN (the COBOL-environment routine) or COBOL_SPECIAL_OPEN_ (the equivalent CRE routine). If it calls COBOL85^SPECIAL^OPEN, it actually calls COBOL_SPECIAL_OPEN_ indirectly. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -70 Libraries and Utility Routines • COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ Acceptable Values for the Parameter open-type The value of the open-type parameter determines what type of device the COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ routine opens. Acceptable values for open-type (after truncation to an integer value, if necessary) and their meanings are: Value Meaning 1 Open a printer or spooler. 2 Open a system log file. 3 Open a partitioned disk file. 4 Open a tape file in the CRE. Any other value for open-type causes an error. Printers or Spoolers When the parameter open-type has the value 1, the COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ routine opens a line printer or a print spooler collector. Unlike the COBOLSPOOLOPEN routine, COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ allows parameters to be defined in the Extended-Storage Section. Furthermore, COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ provides the only mechanism for suppressing the initial page ejection that COBOL always provides for jobs destined for printing. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -71 Libraries and Utility Routines ENTER COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ ns " COBOL85^SPECIAL^OPEN ns " COBOL_SPECIAL_OPEN_ OF library-reference USING file-name open-type = 1 exclusion sync-depth no-eject level-3 location form-name report-name copies page-size flags owner max-lines max-pages code-129 form-feed GIVING return-code VST348.vsd library-reference is a mnemonic-name in the SPECIAL-NAMES paragraph. For the COBOL85 compiler, this mnemonic-name is associated with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL85^SPECIAL^OPEN. For the NMCOBOL compiler, this mnemonicname is associated with either $SYSTEM.SYSnn.ZCOBSRL or some other object file containing an object copy of COBOL_SPECIAL_OPEN_. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -72 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ file-name is the name of a COBOL data file; that is, a file described in a File Description entry. It must be an FD name associated with a file-system file name that specifies a line printer (device type 5) or a spooler collector (device type 0, subdevice type 31). open-type is a numeric operand whose value (after truncation to an integer value, if necessary) is 1. The value 1 (the default) signifies the opening of a line printer or a spooler collector. exclusion is a numeric operand that specifies the exclusion attribute for the open operation. The evaluation of this operand includes truncation to an integer value if necessary. If exclusion is present, its value must be 0 (shared), 1 (exclusive), or 3 (protected). If it is omitted, the routine determines the exclusion attribute from a command interpreter ASSIGN command if one applies to the specified FD-name; otherwise, it assumes the value 1 (exclusive). sync-depth is a numeric operand that specifies the sync-depth attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. If this parameter is present, it must be in the range 0 through 255; if it is omitted, the value assumed depends on the nature of the file. For a line printer, the routine uses a value of 1; for a spooler collector, it uses a value of 3. no-eject is a numeric operand that specifies whether a page ejection must precede the first record delivered to the file. The evaluation of this operand includes, if necessary, truncation to an integer value. A value of 0 requests that a page ejection be done; a nonzero value requests that there be no initial ejection. If no value is specified, the routine uses a value of zero. no-eject does not apply if file-name has LINAGE specified. level-3 is a numeric operand that specifies whether level-2 or level-3 spooling is to be used. The evaluation of this operand includes, if necessary, truncation to an integer value. Any nonzero value requests level-3 spooling; the value zero requests level-2 spooling. If no value is specified, the routine uses a value of zero. This parameter applies only to spooler collectors. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -73 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ location is a 16-character alphanumeric, PIC X(16), that identifies the string passed to the spooler as its location parameter. The data item must be at least 16 characters. If longer, only the first 16 characters are passed to the spooler. The spooler expects a two-part location name in the format #gggggggdddddddd where #ggggggg is the group name and dddddddd is the destination name. The pound sign (#) is required. All remaining characters can be letters, digits, or spaces. The access mode (see Linkage Section) of location must be STANDARD. form-name is an alphanumeric or equivalent data item that specifies the spooler job form name. form-name must not: • • Start with a number or a space character Contain any special characters or embedded blanks Any value provided is adjusted to a length of 16 characters (by extending with spaces or truncating). If no value is specified, the routine uses a value of all spaces. This parameter applies only to spooler collectors. report-name is an alphanumeric or equivalent data item that specifies the spooler job report name. Any value provided is adjusted to a length of 16 characters (by extending with spaces or truncating). The first character cannot be a space. No character can be a hyphen (-). If no value is specified, the routine uses the user name associated with the calling process. This parameter applies only to spooler collectors. copies is a numeric operand that specifies the number of copies of the job the spooler must print. The evaluation of this operand includes, if necessary, truncation to an integer value. If no value is specified, the routine uses a value of 1. This parameter applies only to spooler collectors. page-size is a numeric operand that specifies the number of lines the spooler interface program is to consider as a page. The evaluation of this operand includes, if necessary, truncation to an integer value. If no value is specified, the routine uses the value 60. This parameter applies only to spooler collectors. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -74 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ flags is a numeric operand that specifies certain attributes of the job. The evaluation of this operand includes, if necessary, truncation to an integer value. The value is represented as a 16-bit integer: Bits Contents 0 Reserved 1 ASCII compression flag (0 = OFF, 1 = ON). Ignored if code-129 is omitted. See the description of code-129 for more information. 2-8 Reserved 9 HOLD flag (0 = OFF, 1 = ON) 10 HOLDAFTER flag (0 = OFF, 1 = ON) 11 Specifies whether the output routines of the interface should exit before writing a level-3 buffer to the collector process, so that you can checkpoint (0 = not exit, 1 = exit). The run-time library always sets bit 11 to 0 because you cannot control checkpointing of the level-3 buffer. 12 Purge existing data flag for spooler job files (0 = append new data to existing data, 1 = purge existing data). Ignored if code-129 is omitted. See the description of code-129 for more information. 13-15 Job priority If no value is specified, the routine uses a value of 4 (job priority = 4; all other bits off). This parameter applies only to spooler collectors. owner is an alphanumeric or equivalent data item that specifies a user name; the job is created in the spooler as belonging to that user. Any value provided is adjusted to a length of 16 characters (by extending with spaces or truncating). If no value is specified, the routine uses the user name associated with the calling process. This parameter applies only to spooler collectors. max-lines is a numeric operand in the range 0 through 65534 that specifies the maximum number of lines that can be printed. If max-lines is 0 or omitted, no maximum number is enforced. max-pages is a numeric operand in the range 0 through 65534 that specifies the maximum number of pages that can be printed. If max-lines is 0 or omitted, no maximum number is enforced. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -75 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ code-129 is a numeric operand that specifies whether a code 129 file (spooler job file) is to be created or a regular spooler file is to be created. A nonzero value indicates that the run-time library is to call SPOOLSTART with file-name reflecting the name specified in the ASSIGN phrase of the SELECT clause for the file or by an ASSIGN TACL command. See the description of SPOOLSTART in the Guardian Procedure Calls Reference Manual for details on spooler job files. The resulting file must be a disk file and must be a code 129 spooler job file if it exists. The filesystem file name must be a name acceptable in the non-CRE environment. For example, the volume name cannot exceed seven characters. If the actual file is incorrect, an error is reported and the program terminates abnormally. If the value of code-129 is 0, it is assumed that the actual file assigned will be a normal spooler process. You can use flags to control whether the file is compressed and whether old data in the file is deleted or new data is appended. If code-129 is specified, these parameters are ignored: Parameter Value Used exclusion Protected sync-depth 1 level-3 Level 3 location The file specified in the SELECT clause form-feed is a numeric operand that specifies whether a form feed (CONTROL (file, 1, 0)) is to be used to position to the top of a new page rather than using spacing when LINAGE is specified for the file. A value of 0 (the default) indicates that spacing is to be used; a nonzero value indicates that a form feed is to be used. If form-feed is nonzero, the sizes of the pages may not conform to that specified in the LINAGE clause for the file. The size depends on the forms control mechanism of the printer. return-code is an identifier of a numeric data item in which an error value will be returned. The expected values and their respective meanings are: Value Meaning 0 Successful execution 1 file-name is missing or is invalid, or an extraneous parameter is present. 2 The value of the open-type, exclusion, or sync-depth parameter is invalid. 3 The value of the owner parameter is invalid. 4 The device-type of the file specified is not compatible with the value specified for open-type. 5 An operation error occurred (for example, the file could not be opened). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -76 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ In the Guardian environment, all the functions of this form of COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ except those provided by the parameters no-eject, code-129, and form-feed can also be provided by a DEFINE of class SPOOL, but COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ brings the functionality into the program, while the DEFINE solution leaves it out in the run-time environment. A file assigned to a printer or to a spooler collector process (identified at run time by its subdevice type of 31) is handled as a printer, in that calls to Guardian environment routines CONTROL and SETMODE are used to initialize the file’s state, to suppress automatic forms skipping, and to handle ADVANCING clauses, and the writing of a given record is deferred until the next record is ready to be written (or the file is to be closed) to minimize the number of Guardian procedure calls involved in writing. When a file is assigned to a process that is not a spooler collector, the records are written immediately, with no optimization attempted and no SETMODE or CONTROL procedure involvement. System Log Files When the parameter open-type has the value 2, the COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ routine does one of: • Opens the EMS device ($0) or an alternate collector so that it can receive EMS events Note. To send an ASCII text message (rather than an EMS event) to a collector, open the collector with an OPEN statement, not with the COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ routine. • Opens the SPI device ($0.#ZSPI) so that it can receive SPI commands. Note. To send SPI commands to an alternate collector, open the collector with an OPEN statement, not with the COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ routine. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -77 Libraries and Utility Routines ENTER " COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ ns COBOL85^SPECIAL^OPEN ns " COBOL_SPECIAL_OPEN_ OF library-reference USING file-name open-type = 2 exclusion sync-depth GIVING time-limits return-code VST349.vsd library-reference is a mnemonic-name in the SPECIAL-NAMES paragraph. For the COBOL85 compiler, this mnemonic-name is associated with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL85^SPECIAL^OPEN. For the NMCOBOL compiler, this mnemonicname is associated with either $SYSTEM.SYSnn.ZCOBSRL or some other object file containing an object copy of COBOL_SPECIAL_OPEN_. file-name is the name of a COBOL data file; that is, a file described in a File Description entry. It must be an FD name associated with a file-system file name that specifies a system log (device type 1, subdevice type 0 or 1). open-type is a numeric operand whose value (after truncation to an integer value, if necessary) is 2. The value 2 signifies the opening of a system log file. exclusion is a numeric operand that specifies the exclusion attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. If the parameter is present, its value must be 0 (shared), 1 (exclusive), or 3 (protected); if it is omitted, the routine determines the exclusion attribute from a command interpreter ASSIGN command (when one applies to the specified FDname, or assumes the value 0 (shared) for a system log file otherwise. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -78 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ sync-depth is a numeric operand that specifies the sync-depth attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. If this parameter is present, it must be in the range 0 through 255; if it is omitted, the value assumed depends on the nature of the file. For a system log file, the routine uses a value of 1. time-limits is a numeric operand that specifies the TIME-LIMITS attribute for a system log file only when the subdevice type is other than 0; if the subdevice type is 0, this parameter is ignored. The evaluation of this operand includes, if necessary, truncation to an integer value. If this parameter is present and its value is not zero, LOCKFILE and READ statements that refer to the system log file can include the TIME LIMIT wait-time phrase, indicating the maximum time a process waits for a request to complete. If the parameter is omitted, the routine uses a value of zero. return-code is an identifier of a numeric data item in which an error value will be returned. The expected values and their respective meanings are: Value Meaning 0 Successful execution 1 file-name is missing or is invalid, or an extraneous parameter is present. 2 The value of the open-type, exclusion, or sync-depth parameter is invalid. 4 The device-type of the file specified is not compatible with the value specified for open-type. 5 An operation error occurred (for example, the file could not be opened). Usage Considerations: • Sending a Message to $0 To send an EMS event or ASCII text message to the EMS device ($0) or an alternate collector, use the WRITE statement. • Sending an SPI command to $0.#ZSPI To send an SPI command to the SPI device ($0.#ZSPI), use the READ statement with a PROMPT phrase. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -79 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ Partitioned Disk Files When the parameter open-type has the value 3, the COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ routine opens a partitioned disk file even though some partitions cannot be accessed. (The OPEN statement requires all partitions to be accessible.) ENTER " ns COBOL85^SPECIAL^OPEN ns " COBOL_SPECIAL_OPEN_ OF library-reference USING file-name open-type = 3 exclusion sync-depth open-mode GIVING time-limits return-code VST350.vsd library-reference is a mnemonic-name in the SPECIAL-NAMES paragraph. For the COBOL85 compiler, this mnemonic-name is associated with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL85^SPECIAL^OPEN. For the NMCOBOL compiler, this mnemonicname is associated with either $SYSTEM.SYSnn.ZCOBSRL or some other object file containing an object copy of COBOL_SPECIAL_OPEN_. file-name is the name of a COBOL data file; that is, a file described in a File Description entry. It must be an FD name associated with a file-system file name that specifies a disk file (device type 3). open-type is a numeric operand whose value (after truncation to an integer value, if necessary) is 3. The value 3 signifies the opening of a partitioned disk file, even though some partitions cannot be accessed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -80 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ exclusion is a numeric operand that specifies the exclusion attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. If the parameter is present, its value must be 0 (shared), 1 (exclusive), or 3 (protected); if it is omitted, the routine determines the exclusion attribute from a command interpreter ASSIGN command (when one applies to the specified FDname); otherwise the routine assumes the value 3 (protected) when the open mode is Input or assumes the value 1 (exclusive) for any other open mode. sync-depth is a numeric operand that specifies the sync-depth attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. If this parameter is present, it must be in the range 0 through 255; if it is omitted, the value assumed depends on the nature of the file. For a disk file, the routine uses a value of 1. time-limits is a numeric operand that specifies the TIME-LIMITS attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. The presence of a nonzero value for this parameter is equivalent to the presence of a TIME LIMITS phrase with a nonzero value in an ordinary OPEN statement. If the parameter is omitted, the routine uses a value of zero, which has no effect. open-mode is a numeric operand that specifies the open mode attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. If this parameter is supplied, its value must be 0 (open mode is Input), 1 (I-O), 2 (Output), or 3 (Extend). If the parameter is omitted, the routine uses a value of 0 (Input). return-code is an identifier of a numeric data item in which an error value will be returned. The expected values and their respective meanings are: Value Meaning 0 Successful execution 1 file-name is missing or is invalid, or an extraneous parameter is present. 2 The value of the open-type, exclusion, or sync-depth parameter is invalid. 4 The device-type of the file specified is not compatible with the value specified for open-type. 5 An operation error occurred (for example, the file could not be opened). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -81 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ When the COBOL85^SPECIAL^OPEN or COBOL85_SPECIAL_OPEN_routine with an open-type of 3 has performed a successful open operation, the special register GUARDIAN-ERR contains the value 3 (failure to open a partition) if the operating environment reports that file code. In this case, the I-O status code is “00.” If a subsequent input-output statement attempts to make reference to a logical record which resides in an unavailable partition of the file, the HP COBOL run-time routines assign a value of 72 (attempt to access unmounted partition) to the special register GUARDIAN-ERR, because that is the file code reported by the operating environment. The I-O status code in this case is “30” (COBOL permanent error). This, in turn, causes the run-time routines to abnormally terminate the execution of the run unit, unless an applicable Declarative procedure is specified in the Procedure Division of the program unit that contains the statement whose execution failed. Tape Files in the CRE When the parameter open-type has the value 4, the COBOL_SPECIAL_OPEN_ routine opens a tape file in the CRE. ns ENTER OF ns COBOL_SPECIAL_OPEN_ " " library-reference USING file-name open-type = 4 exclusion sync-depth time-limits open-mode mount-messages end-of-tape-process GIVING return-code VST614.vsd library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.CBL85UTL or some other object file containing an object copy of COBOL_SPECIAL_OPEN_. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -82 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ file-name is the name of a COBOL data file; that is, a file described in a File Description entry. It must be an FD name associated with a file-system file name that specifies a tape file. open-type is a numeric operand whose value (after truncation to an integer value, if necessary) is 4. The value 4 signifies the opening of a tape file. exclusion is a numeric operand that specifies the exclusion attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. If the parameter is present, its value must be 0 (shared), 1 (exclusive), or 3 (protected). If it is omitted, the routine determines the exclusion attribute from a command interpreter ASSIGN command (when one applies to the specified FDname); otherwise the routine assumes the value 3 (protected) when the open mode is Input or assumes the value 1 (exclusive) for any other open mode. sync-depth is a numeric operand that specifies the sync-depth attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. If this parameter is present, it must be in the range 0 through 255. If it is omitted, the value assumed depends on the nature of the file. time-limits is a numeric operand that specifies the TIME-LIMITS attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. The presence of a nonzero value for this parameter is equivalent to the presence of a TIME LIMITS phrase with a nonzero value in an ordinary OPEN statement. If the parameter is omitted, the routine uses a value of zero, which has no effect. open-mode is a numeric operand that specifies the open mode attribute for the open operation. The evaluation of this operand includes, if necessary, truncation to an integer value. If this parameter is supplied, its value must be one of: Value Open Mode 0 Input (default) 1 Input-Output 2 Output 3 Extend HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -83 Libraries and Utility Routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ mount-messages is the name of a data item that describes the name of the file to be used for tape mount messages. The file name must be left-justified and in Guardian external format with no trailing spaces. Reference modification can give the length of the name. The file must be a process or terminal. If mount-messages is omitted, tape mount messages are written to the execution log file. end-of-tape-process is an alphanumeric data item of at least seven characters, whose value specifies the action to be taken if the file operation causes a reel swap. If the value is “RETURN ” (in any combination of uppercase and lowercase letters and with a space after N ), a read or write operation returns an I-O status code of “97” and a GUARDIAN-ERR of 150 when a reel swap occurs. If the reel swap occurs during a WRITE statement, the record that was just written and several of the records previously written might or might not be on the tape just completed. If the value is not “RETURN ” or end-of-tape-process is omitted, a read or write operation does not return anything to the program when a reel swap occurs. return-code is an identifier of a numeric data item in which an error value will be returned. The expected values and their respective meanings are: Value Meaning 0 Successful execution 1 file-name is missing or is invalid, or an extraneous parameter is present. 2 The value of the open-type, exclusion, sync-depth, or mountmessages parameter is invalid. 4 The device-type of the file specified is not compatible with the value specified for open-type. 5 An operation error occurred (for example, the file could not be opened). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -84 Libraries and Utility Routines COBOLLIB, CLULIB, and ZCOBSRL Routines COBOLLIB, CLULIB, and ZCOBSRL Routines This topic explains the individual routines in the COBOLLIB and ZCOBSRL files that are not Saved Message Utility (SMU) routines. Not all of the CRE equivalents are in the COBOLLIB file (see the table notes). Programs compiled with the COBOL85 compiler can call all of the routines listed in Table 13-18. Programs compiled with the NMCOBOL compiler can call only the new routines. Table 13-18. Non-SMU COBOLLIB Routines Original Routine New Routine(s) COBOLASSIGN COBOL_ASSIGN_1, 2 COBOLFILEINFO COBOLFILEINFO2 COBOL_FILE_INFO_3, 4 COBOLSPOOLOPEN COBOL_SPECIAL_OPEN_4 CREATEPROCESS CREATEPROCESS5 CLU_PROCESS_CREATE1, 6 1. In the CLULIB file for the COBOL85 compiler and the ZCOBSRL file for the NMCOBOL compiler 2. For the Guardian environment 3. For the OSS environment 4. In the CBL85UTL file for the COBOL85 compiler and the ZCOBSRL file for the NMCOBOL compiler 5. Cannot create a high-PIN process 6. Can create a high-PIN process An HP COBOL program that was compiled to run in the non-CRE environment can call only the COBOL-environment routines. An HP COBOL program that was compiled to run in the CRE can call only the CRE routines. Note. If you omit an optional parameter when you call a COBOLLIB routine, you must put the keyword OMITTED in its position if you specify subsequent parameters. Trailing OMITTEDs are not required. (The syntax diagrams do not reflect this, because it would make them much harder to read.) Topics: • • • • • • COBOLASSIGN COBOL_ASSIGN_ COBOLFILEINFO COBOL_FILE_INFO_ COBOLSPOOLOPEN CREATEPROCESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -85 Libraries and Utility Routines COBOLASSIGN COBOLASSIGN The COBOLASSIGN routine enables an HP COBOL program to perform an ASSIGNlike statement while the program is executing. It associates a COBOL file name (fd-name ) with a file-system file name. You must declare the COBOL file name as dynamically assignable in a file-control entry in the Input-Output Section. The syntax for this declaration is: SELECT fd-name OPTIONAL ASSIGN #DYNAMIC TO VST355.vsd This form of the ASSIGN clause specifies only that fd-name is dynamically assignable; unlike the other forms of the ASSIGN clause (or of the command interpreter ASSIGN command), it does not associate fd-name with any file-system file name. After fd-name is declared as dynamically assignable, the HP COBOL program can use ENTER to call COBOLASSIGN. The general form of the ENTER statement to use COBOLASSIGN is: ns ENTER OF " ns COBOLASSIGN " library-reference USING fd-name GIVING error-number system-file-name VST354.vsd Note. COBOLASSIGN uses a protocol different from that used by normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -86 Libraries and Utility Routines COBOLASSIGN library-reference is a mnemonic-name associated, in the SPECIAL-NAMES paragraph, with either COBOLLIB or some other object file containing an object copy of COBOLASSIGN. See Files of Dummy Routines. fd-name is the fd-name of a file connector. The file specified in the ASSIGN phrase of the SELECT clause that references fd-name will be replaced by system-filename. If the program was compiled in OSS, the file will be an OSS file unless it was defined as a Guardian file by an ASSIGN command; for example: ASSIGN TO "GUARDIAN #DYNAMIC" system-file-name is a data item holding the file-system file name of the file to be assigned. On a C-Series system, system-file-name can have a maximum of 34 bytes; on a D-Series system, it can have a maximum of 35 bytes. The file name is in external form. The unused part of the data item must contain spaces. If system, volume, or subvolume is not specified, the respective default value is used. The access mode (see Linkage Section) of system-file-name must be STANDARD. error-number is a numeric data item, PIC 9(4) COMPUTATIONAL or DISPLAY, in which an error code produced by COBOLASSIGN is returned. Possible values for errornumber and their respective meanings are: Value Meaning 0 No error occurred. 1 Invalid syntax is in the specified file-system file name. 2 Cannot change the file-system file name of a COBOL file that is open. 3 fd-name has not been declared as #DYNAMIC. The access mode (see Linkage Section) of error-number must be STANDARD. COBOLASSIGN does not determine whether the assigned file actually exists or is accessible. This checking is done by the OPEN statement. COBOLASSIGN can be called repeatedly for one fd-name. An attempt to open a file using a dynamically assignable fd-name before COBOLASSIGN has been used on it is an attempt to open $volume.#DYNAMIC (where $volume is the default volume). This causes a run-time error. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -87 Libraries and Utility Routines COBOLASSIGN A CLOSE LOCK on a file using a dynamic fd-name closes the file but does not lock it. If locking were allowed, it would only prevent the reuse of the fd-name for the remainder of the run unit’s existence; the file would still be accessible through another dynamic fd-name. A command interpreter ASSIGN command cannot designate an fd-name as dynamically assignable—you must do this in the source program. ASSIGN can, however, assign a default value to the previously designated dynamic file name. The effect is the same as having an ENTER COBOLASSIGN statement as the first statement in the program. See ASSIGN Command. A CRE HP COBOL program can call either COBOLASSIGN (the COBOL-environment routine) or COBOL_ASSIGN_ (the equivalent CRE routine). If it calls COBOLASSIGN, it actually calls COBOL_ASSIGN_ indirectly. There are advantages to calling COBOL_ASSIGN_ directly (see COBOL_ASSIGN_). Example 13-16. COBOLASSIGN Routine IDENTIFICATION DIVISION. ... ENVIRONMENT DIVISION. ... SPECIAL-NAMES. FILE "$SYSTEM.SYSTEM.COBOLLIB" IS COBOLLIB. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT PARTNO ASSIGN #DYNAMIC. DATA DIVISION. ... WORKING-STORAGE SECTION. 01 PART-FILE-NAME PICTURE X(35). 01 ASSIGN-ERROR COMP PICTURE 9999. PROCEDURE DIVISION. SETUP. DISPLAY "ENTER CHOSEN PART FILE NAME" ACCEPT PART-FILE-NAME ENTER "COBOLASSIGN" OF COBOLLIB USING PARTNO PART-FILE-NAME GIVING ASSIGN-ERROR IF ASSIGN-ERROR = 0 OPEN INPUT PARTNO ELSE IF ASSIGN-ERROR = 1 ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -88 Libraries and Utility Routines COBOL_ASSIGN_ COBOL_ASSIGN_ COBOL_ASSIGN_ is the CRE-equivalent of the COBOL-environment routine COBOLASSIGN. If a CRE HP COBOL program calls COBOLASSIGN, it actually calls COBOL_ASSIGN_ indirectly. The advantages to calling COBOL_ASSIGN_ directly are: • • • You can pass all parameters from the Extended-Storage Section or Linkage Section. You can specify temporary file names. You can specify two additional parameters, file-code and file-type. ns ENTER OF ns COBOL_ASSIGN_ " " library-reference USING fd-name system-file-name file-code file-type GIVING error-number VST356.vsd library-reference is a mnemonic-name associated, in the SPECIAL-NAMES paragraph, with either COBOLLIB or some other object file containing an object copy of COBOL_ASSIGN_. See Files of Dummy Routines. fd-name is the fd-name of a file connector. The file specified in the ASSIGN phrase of the SELECT clause that references fd-name will be replaced by system-filename. If the program was compiled in the OSS environment, the file will be an OSS file, unless it was defined as a Guardian file by an ASSIGN such as: ASSIGN TO "GUARDIAN #DYNAMIC" HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -89 Libraries and Utility Routines COBOL_ASSIGN_ system-file-name is an alphanumeric data item holding the file-system file name of the file to be assigned. system-file-name is in external form. It must be left-justified in the data item and any unused portion of the name must contain spaces. If the program identifies system-file-name as an OSS file system name, then the program assumes that fd-name is an OSS file; otherwise, the program assumes that fd-name is a Guardian file. If system, volume, or subvolume of a Guardian file is not specified, the respective default value is used ($volume.file is no longer allowed.) If system-file-name is omitted, COBOL_ASSIGN_ does not change the original file-system file name. For more information on OSS file system names, see Files in the OSS Environment. file-code can be specified in the Guardian environment only. It is a numeric data item or a numeric literal whose value is a file code acceptable to the file system. For example, file code 101 indicates that the file is an EDIT file and file code 180 indicates that the file is an OSS ASCII text file. If file-code is omitted, COBOL_ASSIGN_ does not change the original file code. file-type can be specified in the Guardian environment only. It is a numeric data item whose content, or a numeric literal whose value, is either 0 (for an unstructured file) or 2 (for an entry-sequenced file). You can specify file-type only for a file whose organization is sequential. For other file organizations, the organization determines the file type (relative for ORGANIZATION RELATIVE and key sequenced for ORGANIZATION INDEXED). If file-type is omitted, COBOL_ASSIGN_ and does not change the original file type. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -90 Libraries and Utility Routines COBOLFILEINFO error-number is a numeric data item in which COBOL_ASSIGN_ returns an error code. Possible values for error-number and their respective meanings are: Value Meaning 0 No error occurred. 1 system-file-name has invalid syntax or the name has no length (such as a group containing an OCCURS DEPENDING whose length is 0). 2 system-file-name is open and cannot be changed. 4 There is not enough system space to add the new name. 5 file-type is not 0 or 2, file-type is specified for a file whose organization is not sequential, or file-type or file-code is specified for an OSS file. COBOLFILEINFO The COBOLFILEINFO routine is for the Guardian environment. In the OSS environment, use the COBOL_FILE_INFO_ routine. The COBOLFILEINFO routine is for these situations: • • • An application needs to perform some operation not defined in HP COBOL on a file normally managed by the HP COBOL run-time routines. This application must obtain the file system file number assigned when the file was opened. An application that manages a file through TAL routines can operate as a process pair, letting HP COBOL perform the open, close, and checkpoint operations with the run-time routines. This application must be able to obtain the file system file number assigned when the file is opened. An application can put the file-system file name of a file into an applicationgenerated error message. As with any ENTER statement, you must either qualify the name COBOLFILEINFO with the library-reference COBOLLIB or include a SEARCH directive specifying HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -91 Libraries and Utility Routines COBOLFILEINFO COBOLLIB to provide automatic resolution of the reference. The general form of the ENTER statement to use COBOLFILEINFO follows. ns ENTER " ns COBOLFILEINFO " TAL OF library-reference USING fd-name error-code file-name file-number VST357.vsd library-reference is a mnemonic-name associated, in the SPECIAL-NAMES paragraph, with either COBOLLIB or some other object file containing an object copy of COBOLFILEINFO. fd-name is the COBOL name of the file in the FD entry. error-code is a numeric data item described as USAGE COMPUTATIONAL PICTURE 9999 (or S9999)or USAGE NATIVE-2. The COBOLFILEINFO routine returns the last file system file-system error code to this data item. The value returned is always positive. The access mode (see Linkage Section) of error-code must be STANDARD. file-name is a DISPLAY data item of at least 24 characters where the actual 24-byte internal file name is returned. The internal form of the file name is three 8-character fields containing the three portions of the file name, with trailing spaces inserted and with no period (.) separators. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -92 Libraries and Utility Routines COBOL_FILE_INFO_ In the CRE, if file-name is composed entirely of spaces or has an 8-character volume name, it cannot be converted to internal form. To convert it to internal form, use the COBOL_FILE_INFO_ routine. The access mode (see Linkage Section) of file-name must be STANDARD. file-number is a numeric data item described as USAGE COMPUTATIONAL PICTURE S99. The COBOLFILEINFO routine returns the file’s open number to this data item. file-number has the value -1 in each of these cases: • • • The file is not open. The file is OPTIONAL and not present (even if it is open). After the file was opened, the I-O status code was “05,” rather than “00” (see Nonexistent Files). The access mode (see Linkage Section) of file-number must be STANDARD. Usage Consideration: Do not use COBOLFILEINFO to obtain the operating environment error number associated with the failure of any input-output operation that is performed simply with COBOL input-output verbs (such as READ). The HP COBOL special register GUARDIAN-ERR was created for that purpose. Certain operations, such as a READ statement operating on the $RECEIVE file, deliver meaningful values to GUARDIAN-ERR, but a call to COBOLFILEINFO would return an inappropriate value of zero or an arbitrary, undefined value. COBOL_FILE_INFO_ The COBOL_FILE_INFO_ routine is for both the OSS and Guardian environments. In the Guardian environment, it works only in the CRE (in the non-CRE environment, use the routine COBOLFILEINFO). The COBOL_FILE_INFO_ routine is for these situations: • • An application needs to perform some operation not defined in HP COBOL on a file normally managed by the HP COBOL run-time routines. This application must obtain the file system file number assigned when the file was opened. An application can put the file-system file name of a file into an applicationgenerated error message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -93 Libraries and Utility Routines COBOL_FILE_INFO_ As with any ENTER statement, you must either qualify the name COBOL_FILE_INFO_ with the library-reference COBOLLIB or include a SEARCH directive specifying COBOLLIB to provide automatic resolution of the reference. The general form of the ENTER statement to use COBOL_FILE_INFO_ follows. ENTER " COBOL_FILE_INFO_ " TAL OF library-reference USING file-name name-buffer name-size file-number error VST636.vsd library-reference is a mnemonic-name associated, in the SPECIAL-NAMES paragraph, with either COBOLLIB or some other object file containing an object copy of COBOL_FILE_INFO_. file-name is the COBOL name of the file in the FD entry. name-buffer is the buffer in which the file name is returned. To accommodate the maximum file name size, name-buffer must hold at least 1023 characters. To accommodate the largest Guardian file name, name-buffer must be at least 35 characters. If name-buffer is too short for the file name, the file name is truncated. If the file name is an OSS file, the terminating zero byte is included in the name and in the name size. name-size is the data item in which the size of the file name is returned. If the file name was truncated, name-size contains the actual size, not the truncated size. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -94 Libraries and Utility Routines COBOLSPOOLOPEN file-number is the Guardian or OSS file number. If the file is not open, file-number is 0. If, after the file was opened, the I-O status code was “05,” rather than “00” (see Nonexistent Files), file-number is -1. error is the last Guardian error number. If the file is an OSS file, error is 0. Usage Consideration: Do not use COBOL_FILE_INFO_ to obtain the operating environment error number associated with the failure of any input-output operation that is performed simply with COBOL input-output verbs (such as READ). The HP COBOL special register GUARDIAN-ERR was created for that purpose. Certain operations, such as a READ statement operating on the $RECEIVE file, deliver meaningful values to GUARDIAN-ERR, but a call to COBOL_FILE_INFO_ would return an inappropriate value of zero or an arbitrary, undefined value. COBOLSPOOLOPEN COBOLSPOOLOPEN is available to COBOL-environment HP COBOL programs, but it is recommended that they use COBOL_SPECIAL_OPEN_ instead. CRE programs cannot use COBOLSPOOLOPEN and must use COBOL_SPECIAL_OPEN_ instead. Similar functionality is also available through use of a DEFINE of class SPOOL. This documentation is included for historical reasons. COBOLSPOOLOPEN provides Level 2 access to the HP spooler product from an HP COBOL program, enabling you to set various job parameters, such as report title and number of copies, from within the program. Topics: • • • Level 2 Spooler Protocol Establishing a Declarative-File Connection Error Code Level 2 Spooler Protocol Access to the HP spooler for Level 2 operation requires a special protocol that is not supported directly in HP COBOL. To open the spooler for Level 2 operation, an HP COBOL program must use an ENTER statement that calls COBOLSPOOLOPEN in place of the HP COBOL OPEN statement. This routine’s parameters do not include analogs of the open mode (for example, OUTPUT) or the REVERSED and NO REWIND phrases of the OPEN statement. Instead, OUTPUT is always assumed, and other options have no meaning for the spooler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -95 Libraries and Utility Routines COBOLSPOOLOPEN COBOLSPOOLOPEN accepts an fd-name associated with either a process or a printer. If the file referred to is a process, it is assumed to be an HP spooler. If the designated file is a printer, COBOLSPOOLOPEN ignores all spooler-specific parameters and produces the same results as a HP COBOL OPEN statement. The general form of the ENTER statement to use COBOLSPOOLOPEN is: ENTER COBOLSPOOLOPEN " " TAL OF library-reference USING fd-name «file-status» location form-name report-name copies page-size flags exclusion sync-depth owner level-3 GIVING error-code VST358.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -96 Libraries and Utility Routines COBOLSPOOLOPEN library-reference is a mnemonic-name associated, in the SPECIAL-NAMES paragraph, with either COBOLLIB or some other object file containing an object copy of COBOLSPOOLOPEN. The mnemonic-name must be left-justified and can have trailing spaces. fd-name is a file name that identifies the COBOL logical file, described by the FD entry associated with the spooler. The file name must be left-justified and can have trailing spaces. file-status Note. The 1985 COBOL standard classifies this parameter as obsolete, so you are advised not to use it. In HP COBOL, the I-O status data item associated with the fd-name is always used. The access mode (see Linkage Section) of file-status must be STANDARD. location is a 16-character alphanumeric, PIC X(16), that identifies the string passed to the spooler as its location parameter. The data item must be at least 16 characters. If longer, only the first 16 characters are passed to the spooler. The spooler expects a two-part location name in the format #gggggggdddddddd where #ggggggg is the group name, and dddddddd is the destination name. The # is required. All remaining characters can be letters, digits, or spaces. The value of location must be left-justified and can have trailing spaces. The access mode (see Linkage Section) of location must be STANDARD. form-name is a 16-character alphanumeric, PIC X(16), that identifies the string passed to the spooler as its form-name parameter. The data item must be left-justified and be at least 16 characters. If longer, only the first 16 characters are passed to the spooler. The only spaces allowed are trailing spaces. The access mode (see Linkage Section) of form-name must be STANDARD. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -97 Libraries and Utility Routines COBOLSPOOLOPEN report-name is a 16-character alphanumeric, PIC X(16), that identifies the string passed to the spooler as its report-name parameter. The data item must be at least 16 characters. If longer, only the first 16 characters are passed to the spooler. Only letters, digits, and spaces are acceptable to the spooler. The first character cannot be a space. No character can be a hyphen. The access mode (see Linkage Section) of report-name must be STANDARD. copies is a numeric item (COMPUTATIONAL or DISPLAY), a numeric literal, or a parenthetical expression, the value of which is passed to the spooler as its number-of-copies parameter. The value must evaluate to a positive integer in the range 1 through 32767. page-size is a numeric item (COMPUTATIONAL or DISPLAY), a numeric literal, or a parenthetical expression, the value of which is passed to the spooler as its pagesize parameter. The value must evaluate to a positive integer in the range 1 through 32767. flags is a numeric item (COMPUTATIONAL or DISPLAY), a numeric literal, or a parenthesized expression, the value of which is passed to the spooler as its flags parameter. The value must evaluate to a positive integer whose value is consistent with the specifications below. The appropriate value of flags is the sum of the values associated with the defined options, which follow: HOLD HOLDAFTER PRIORITY 64 (decimal) 32 (decimal) 0, 1, 2, 3, 4, 5, 6, or 7 exclusion is a numeric item (COMPUTATIONAL or DISPLAY), a numeric literal, or a parenthetical expression, the value of which is used as the exclusion attribute of the file open operation (for the purpose of this parameter, see OPEN). exclusion must evaluate to a positive integer consistent with these specifications. The defined options for exclusion and their associated values are: Value Meaning SHARED 0 EXCLUSIVE 1 PROTECTED 3 (equivalent to SHARED in this context) HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -98 Libraries and Utility Routines COBOLSPOOLOPEN sync-depth is a numeric item (COMPUTATIONAL or DISPLAY), a numeric literal, or a parenthetical expression that evaluates to a positive integer, which is used as the sync-depth of the spooler file. Its default value is 3. A value greater than 32 results in a file-system error 28 from the spooler. The sync-depth specifies the number of write requests whose completion status the file system is to remember. owner is an alphanumeric data item, PIC X(16), that specifies the owner of the spooler job in this format: gggggggguuuuuuuu The value gggggggg is a file-security system group name, and uuuuuuuu is a file-security system user name. Each of these names must be eight characters long, with trailing spaces inserted if necessary. The item does not include a period between the names. If you specify an invalid combination of names for this parameter, COBOLSPOOLOPEN returns error code 102. If you omit the owner parameter, the spooler uses the owner ID of the executing process. level-3 is a numeric item (COMPUTATIONAL or DISPLAY), a numeric literal, or a parenthesized expression. If its value is other than zero, the output to the spooler is done using level-3 spooling, which enhances performance by sending records to the spooler in blocks. If you omit the level-3 parameter, or if it has a value of zero, the output records are sent one at a time. error-code is a numeric data item, PIC 9(4) COMPUTATIONAL, that identifies the data item into which COBOLSPOOLOPEN returns an error code value. USAGE DISPLAY is permitted in place of USAGE COMPUTATIONAL; however, in this case the data item’s PICTURE character-string should be 9(4), so it is capable of containing the full range of potential values. The error code value returned for success is 0; a nonzero value implies failure to open the file. The access mode (see Linkage Section) of error-code must be STANDARD. All the parameters except fd-name are optional. If a parameter is omitted, but one or more following ones are present, its position in the USING phrase must be occupied by the reserved word OMITTED (for details, see ENTER). Although the GIVING phrase is optional, it is recommended for error analysis. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13 -99 Libraries and Utility Routines COBOLSPOOLOPEN Establishing a Declarative-File Connection The HP COBOL compilers find the connection between generic file declarative sections and logical files by examining the context of OPEN statements. A declarative section preceded by a USE AFTER EXCEPTION PROCEDURE ON OUTPUT statement is implicitly associated with each file whose name appears in an OPEN OUTPUT statement. In such cases, the section is called whenever an exception occurs during execution of an I-O statement for a file that is currently open for output. The section is not called if the exception occurs in conjunction with a file that could be open for output but is actually open in some other mode. The HP COBOL compilers do not find such a connection from the occurrence of an ENTER COBOLSPOOLOPEN statement; however, an application can instruct the compiler to establish a declarative-file connection in either of two ways: • • A declarative section preceded by a USE AFTER EXCEPTION PROCEDURE file-name-list is explicitly associated with each file whose name appears in the list. A declarative section preceded by a USE AFTER EXCEPTION PROCEDURE ON OUTPUT can be associated with a given logical file by inserting an OPEN OUTPUT file-name statement in a portion of the program that is never executed. Although both methods establish the connection in conjunction with WRITE, LOCKFILE, and CLOSE statements, a failure of the ENTER COBOLSPOOLOPEN statement does not call the declarative section. The error detection must be programmed explicitly by including the GIVING error-code phrase in the ENTER statement and testing the value returned. If the file-status item is present in the parameter list, a simple success-failure test can be made by examining its value. Error Code The error code returned by COBOLSPOOLOPEN can originate in either COBOLSPOOLOPEN or the spooler. In most cases, it is generated by the spooler and merely passed on by COBOLSPOOLOPEN. • • • • All spooler error codes have a value of at least 512 (%1000). For more information, see the Guardian Procedure Calls Reference Manual. COBOLSPOOLOPEN returns error code values in the range 1 through 511 (1-%777). For values in the range 1 through 99, refer to the corresponding number in Section 48, Run-Time Diagnostic Messages. If no fd-name is present, 100 is returned. If the associated file is neither a process nor a printer, 101 is returned. All nonzero codes imply the open operation failed. If the owner parameter does not specify a valid group/user combination, 102 is returned. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 100 Libraries and Utility Routines CREATEPROCESS CREATEPROCESS The CREATEPROCESS routine starts a new process according to parameters you specify. It can also send process-creation messages that might have been altered by SMU routines to the new process according to the option parameter specifications. The CREATEPROCESS routine is available only in the Guardian environment. In the OSS environment, use the OSS process create function fork() or tdm_fork(2) (see the Open System Services Programmer’s Guide). The CREATEPROCESS routine cannot create a high-PIN process. To do this, use the CLU_PROCESS_CREATE_ routine (see CLULIB Overview). The general form of the ENTER statement to use CREATEPROCESS is: ns ENTER " OF CREATEPROCESS ns " library-reference USING program-file process-name option priority processor memory process-id GIVING result VST359.vsd Note. CREATEPROCESS uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of CREATEPROCESS. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 101 Libraries and Utility Routines CREATEPROCESS program-file is an alphanumeric data item containing the file-system file name of the loadfile to be executed. Any trailing spaces are ignored. Example: 05 - PROGRAM-FILE PIC X(35) VALUE "\CENTRAL.$CRPMIS.DEVELOP.AMR1459". The access mode (see Linkage Section) of program-file must be STANDARD. process-name is an alphanumeric data item containing the name for the new process. Normally, the first six characters are significant and must be in the format defined by NEWPROCESS: the first character must be a dollar sign ($), and the second character must not be a space. The minimum number of characters allowed is two. The value can be all spaces to indicate that no name is supplied. The process-name parameter can be omitted by supplying the keyword OMITTED instead of an alphanumeric data item. OMITTED indicates that no name is supplied. Example: 03 PROCESS-NAME PIC X(6) VALUE "$A1459". The access mode (see Linkage Section) of process-name must be STANDARD. option is a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. option indicates which saved process creation messages are required by the new process. The value must evaluate to 0, 1, 2, 3 or 8, 9, 10, 11. The option parameter can be omitted by supplying the keyword OMITTED. OMITTED implies a 0 option value. Example: 07 OPTION PIC 9999 COMPUTATIONAL. The option values are interpreted like this: Value Meaning 0 Send copies of all saved ASSIGN, PARAM, and startup messages from the creator process. If no saved startup message exists, send a standard message where the volume and subvolume, IN-file, and OUT-file are those of the creator process, and the message parameter string is a null string. 1 Send a copy of the saved startup message from the creator process. If no saved startup message exists, send a standard message as described above. 2 Send a standard startup message. 3 Send no messages. The creator process does not open the new process. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 102 Libraries and Utility Routines CREATEPROCESS Normally, if NEWPROCESS reports a class one error, undefined externals, the new process stops. An application can force new process creation by adding 8 to the normal option value (8 instead of 0, 9 instead of 1, …, 11 instead of 3). CREATEPROCESS returns the class one error result even though the new process is created. The value 8 indicates the undefined externals are not considered an error. priority is the NEWPROCESS priority parameter. Priority can be either a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. Its value is passed to NEWPROCESS. If its value is 0, NEWPROCESS assigns the new process the same priority as that of the creator process. The first bit of the priority parameter is used to signal that the new process is to start in debug mode. The priority parameter can be omitted by supplying the keyword OMITTED. OMITTED implies a 0 priority value. Example: 77 PRIORITY PIC S9999 COMPUTATIONAL. processor is the NEWPROCESS processor parameter. processor can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. A nonnegative value is passed to NEWPROCESS. A negative value is replaced by the processor value of the creator process, so the new process executes in the same processor as the creator process. processor can be omitted by supplying the keyword OMITTED. OMITTED implies a value of -1. Example: 02 PROCESSOR PIC S9999 COMPUTATIONAL. memory is the NEWPROCESS memory parameter. memory can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. Its value is passed to NEWPROCESS. If 0, NEWPROCESS assigns the number of memory pages indicated by the new process. memory can be omitted by supplying the keyword OMITTED. OMITTED implies a value of 0. Example: 06 MEMORY-PAGES PIC 9999 COMPUTATIONAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 103 Libraries and Utility Routines CREATEPROCESS process-id is a numeric data item to be assigned the process identification of the new process. The process-id data item must be COMPUTATIONAL or NATIVE-8 and described with 10 through 18 nines. process-id can be omitted by supplying the keyword OMITTED instead of a numeric data item. OMITTED indicates that no process identification is returned. Example: 08 PROCESS-ID PIC S9(18) COMPUTATIONAL. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by CREATEPROCESS. Example: 11 RESULT PIC S9999 COMPUTATIONAL. CREATEPROCESS returns an integer value that indicates whether the new process creation completed or failed. The integer values and their meanings are: Value Meaning 0 Process creation completed successfully 1 Required parameter missing or illegal 2 Illegal loadfile name 3 Infile name, outfile name, or default volume name cannot be converted to network form 10 through 255 A file management error value that CREATEPROCESS received in attempting to transmit the startup message to the new process Greater than 255 A value greater than 255 is an error value returned from NEWPROCESS (see the information on process control in the Guardian Programmer’s Guide) HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 104 Libraries and Utility Routines Saved Message Utility (SMU) Routines Saved Message Utility (SMU) Routines This topic explains the individual Saved Message Utility (SMU) routines in the COBOLLIB file, which are: • • • • • • • • • • • • • • • ALTERPARAMTEXT CHECKLOGICALNAME CHECKMESSAGE DELETEASSIGN DELETEPARAM DELETESTARTUP GETASSIGNTEXT GETASSIGNVALUE GETBACKUPCPU GETPARAMTEXT GETSTARTUPTEXT PUTASSIGNTEXT PUTASSIGNVALUE PUTPARAMTEXT PUTSTARTUPTEXT Note. The presence of the keyword TAL in an ENTER statement causes COBOL to use the TAL protocol when passing the ENTER statement’s parameters to a routine. Most of these routines require a protocol different from that used for normal TAL procedures. The keyword TAL must not follow the ENTER verb in statements used to access these routines. A reminder of this requirement is included in each routine description to which it applies. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 105 Libraries and Utility Routines ALTERPARAMTEXT ALTERPARAMTEXT Use the ALTERPARAMTEXT routine to create or replace a parameter value for the specified parameter name in the saved PARAM message with text from a string variable. Unlike the PUTPARAMTEXT routine, ALTERPARAMTEXT provides for parameter values with trailing spaces. The general form of the ENTER statement to use ALTERPARAMTEXT follows. ns ENTER OF ns ALTERPARAMTEXT " " library-reference USING portion GIVING result text cplist size VST351.vsd Note. ALTERPARAMTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of ALTERPARAMTEXT. portion is an alphanumeric data item that supplies the identifier for the particular part of the message to be changed. The identifier must be a parameter name defined for the PARAM message. The first unused character position of portion, if any, must be a space. Example: 03 PORTION PIC X(30) VALUE "POSTINGDATE". text is an alphanumeric data item from which the parameter’s new value is obtained. Example: 03 TEXT-VALUE PIC X(120) VALUE "910401". HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 106 Libraries and Utility Routines ALTERPARAMTEXT cplist is a checkpoint list in which the routine records the changes to the message storage data space. Example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cplist can contain. In the CRE, the maximum number of elements that cplist can contain is the initial value of MAX-COUNT divided by 2.5. The cplist in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 03 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. size is the number of characters from text to be used as the new parameter value. size can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. The value must evaluate to a nonnegative integer not greater than 255. Example: 05 TEXT-SIZE PIC 9999 COMPUTATIONAL. result is a DISPLAY or COMPUTATIONAL numeric data item that is assigned the result returned by ALTERPARAMTEXT. Example: 05 RESULT PIC S9999 COMPUTATIONAL. ALTERPARAMTEXT operates on the saved PARAM message. The program must have included a SAVE directive to save the message. Altering the saved PARAM message has no effect on the current process. Any DEBUG, SWITCH-nn, NONSTOP, or other named parameters are permanently established for a given process by the initialization code that the process executes before the first statement of the COBOL program. Any process initiated by the current process inherits the modified PARAM message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 107 Libraries and Utility Routines CHECKLOGICALNAME ALTERPARAMTEXT returns one of these integer values to report the routine’s success or failure: Value Meaning 0 or greater A nonnegative value, equal to the number of characters in the new parameter value, indicates that size characters of text value is assigned as the new parameter value. -1 Failure due to a logic error. The message is unchanged. These are possible logic errors: • • • • The portion identifier is not correct. The size value is negative or exceeds 255 characters. The total length of the new PARAM message exceeds the maximum. The contents of the checkpoint list parameter are inconsistent. -2 Insufficient checkpoint list space is available to complete the operation. The message is unchanged. -3 Insufficient storage space to complete the operation. The message is unchanged. CHECKLOGICALNAME The CHECKLOGICALNAME routine checks whether a saved ASSIGN message with the given logical file name exists. The general form of the ENTER statement to use CHECKLOGICALNAME is: " ENTER OF ns ns CHECKLOGICALNAME " library-reference USING logical-name GIVING result VST352.vsd Note. CHECKLOGICALNAME uses a protocol different from that used by normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of CHECKLOGICALNAME. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 108 Libraries and Utility Routines CHECKLOGICALNAME logical-name file-name program-unit . * VST639.vsd program-unit is an alphanumeric data item that specifies the name of the program unit. file-name is an alphanumeric data item that specifies the logical file name. programunit and file-name together, or file-name alone, compose the logical file name. The logical file name can have a maximum of 63 characters (including the period). Any trailing spaces are ignored. Example: 02 LOGICAL-NAME PIC X(64). * means that the file assignment applies to all programs in the object file. result is either a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by CHECKLOGICALNAME. Example: 03 RESULT PIC S9999 COMPUTATIONAL. CHECKLOGICALNAME operates on the saved ASSIGN messages. The program must have included a SAVE directive to save the message. CHECKLOGICALNAME returns one of these integer values to report whether the requested message exists: • • • A 0 indicates that no saved ASSIGN message contains a matching logical file name text. A positive value is the message number of the saved ASSIGN message having a logical file name text that matches the one supplied. A negative value is the negative message number of the saved ASSIGN message having a logical file name text that conflicts with the one supplied. The names can conflict when only one is qualified or when one is qualified by an asterisk (*) and the other is qualified by a program name. If there is more than one conflicting saved ASSIGN message, the message number of the first ASSIGN message located is returned as a negative value. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 109 Libraries and Utility Routines CHECKMESSAGE CHECKMESSAGE The CHECKMESSAGE routine determines whether a specific message exists or reports the greatest message number of the saved ASSIGN messages. CHECKMESSAGE operates on the saved messages. The program must have included a SAVE directive to save the message. The general form of the ENTER statement to use CHECKMESSAGE is: ns ENTER ns CHECKMESSAGE " " TAL OF library-reference USING message-number GIVING result VST353.vsd library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of CHECKMESSAGE. message-number identifies a specific message. message-number can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. The value for message-number must be -3, -1, 0, or a nonnegative integer. The values of message-number have these meanings: Value of message-number Meaning -3 Checks for the presence of a saved PARAM message -1 Checks for the presence of a saved startup message 0 Requests the greatest message number in the set of saved ASSIGN messages Nonnegative integer Checks for the presence of a saved ASSIGN message with that message number Because each saved ASSIGN message is identified by a positive integer, message-number refers to the integer value of the specific message. The set of numbers associated with the ASSIGN messages are integers from 1 to N, where N is normally the number of ASSIGN messages saved during the initial process creation. Example: 03 MESSAGE-NUMBER PIC S9999 COMPUTATIONAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 110 Libraries and Utility Routines DELETEASSIGN result is either a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by CHECKMESSAGE. Example: 08 RESULT PIC S9999 COMPUTATIONAL. Under these conditions, result has these values: Condition Value of result Value of message-number is not 0 and requested message exists Value of message-number Value of message-number is not 0 and requested message does not exist 0 Value of message-number is 0 and no saved ASSIGN messages exist. 0 All others Nonzero integer value associated with the highest numbered saved ASSIGN message DELETEASSIGN The DELETEASSIGN routine deletes either specific parts of a saved ASSIGN message or an entire saved ASSIGN message. The general form of the ENTER statement to use DELETEASSIGN is: " ENTER OF ns ns DELETEASSIGN " library-reference USING portion GIVING result cplist message-number VST360.vsd Note. DELETEASSIGN uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of DELETEASSIGN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 111 Libraries and Utility Routines DELETEASSIGN portion is an alphanumeric data item that supplies the identifier for the particular part of the saved message to be deleted. The identifier must be one defined for the ASSIGN message (see Table 13-13). The first unused character position of portion, if any, must be a space. Any message part except the LOGICALNAME can be deleted individually. Example: 03 PORTION PIC X(30) VALUE "TANDEMNAME". There is a special portion identifier, *ALL*, accepted by this routine. The *ALL* identifier directs the DELETEASSIGN routine to delete the entire saved ASSIGN message. cplist is a checkpoint list in which the routine records the changes to the message storage data space. Example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cplist can contain. In the CRE, the maximum number of elements that cplist can contain is the initial value of MAX-COUNT divided by 2.5. The cplist in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 08 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 112 Libraries and Utility Routines DELETEASSIGN message-number identifies a specific saved ASSIGN message. message-number can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. The value must evaluate to a positive integer. Example: 14 MESSAGE-NUMBER PIC S9999 COMPUTATIONAL. Because each saved ASSIGN message is identified by a positive integer, message-number refers to the integer value of the specific message. The set of numbers associated with the saved ASSIGN messages are integers from 1 to N, where N is normally the number of ASSIGN messages saved during the initial process creation. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by DELETEASSIGN. Example: 02 RESULT PIC S9999 COMPUTATIONAL. DELETEASSIGN operates on the saved ASSIGN messages. The program must have included a SAVE directive to save the message. Deleting the saved ASSIGN message has no effect on the current process. Any file assignments are permanently established for a given process by the initialization code that the process executes before the first statement of the COBOL program. Any process initiated by the current process after the execution of the DELETEASSIGN routine lacks the corresponding ASSIGN message. DELETEASSIGN returns an integer value that indicates the outcome of this operation. The integer values and their meanings are: Value Meaning 0 The specified message or message portion is deleted. -1 Failure due to a logic error; nothing is deleted. These are possible logic errors: • • -2 The portion identifier is not correct or does not identify a part of the ASSIGN message that can be deleted. The contents of the checkpoint list parameter are inconsistent. Insufficient checkpoint list space is available to complete the deletion. The message is unchanged. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 113 Libraries and Utility Routines DELETEPARAM DELETEPARAM The DELETEPARAM routine deletes either specific parts of a PARAM message or the entire PARAM message. The general form of the ENTER statement to use DELETEPARAM is: ns ENTER OF ns DELETEPARAM " " library-reference USING portion GIVING result cplist VST361.vsd Note. DELETEPARAM uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of DELETEPARAM. portion is an alphanumeric data item that supplies the identifier for the particular part of the message to be deleted. The identifier must be a parameter name defined for the PARAM message. The first unused character position of portion, if any, must be a space. Example: 21 PORTION PIC X(30) VALUE "MALEFACTOR". There is a special portion identifier, *ALL*, accepted by DELETEPARAM. The *ALL* identifier directs the DELETEPARAM routine to delete the entire PARAM message. cplist is a checkpoint list in which the routine records the changes to the message storage data space. Example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 114 Libraries and Utility Routines DELETEPARAM The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cplist can contain. In the CRE, the maximum number of elements that cplist can contain is the initial value of MAX-COUNT divided by 2.5. The cplist in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 06 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by DELETEPARAM. Example: 03 RESULT PIC S9999 COMPUTATIONAL. DELETEPARAM operates on the saved PARAM message. The program must have included a SAVE directive to save the message. Deleting all or part of the saved PARAM message has no effect on the current process. Any DEBUG, SWITCH-nn, NONSTOP, or other named parameters are permanently established for a given process by the initialization code that the process executes before the first statement of the COBOL program. Any process initiated by the current process after the execution of the DELETEPARAM routine lacks all or part of the PARAM message. DELETEPARAM returns an integer value that indicates the outcome of this operation. The integer values and their meanings are: Value Meaning 0 The specified message or message portion is deleted. -1 Failure due to a logic error; nothing is deleted. These are possible logic errors: -2 • • The portion identifier is not correct. The contents of the checkpoint list parameter are inconsistent. Insufficient checkpoint list space is available to complete the deletion. The message is unchanged. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 115 Libraries and Utility Routines DELETESTARTUP DELETESTARTUP The DELETESTARTUP routine deletes an entire startup message. The general form of the ENTER statement to use DELETESTARTUP is: ns ENTER OF ns DELETESTARTUP " " library-reference USING portion GIVING result cplist VST362.vsd Note. DELETESTARTUP uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of DELETESTARTUP. portion is an alphanumeric data item that supplies the identifier for the particular part of the message to be deleted. For DELETESTARTUP this must be the special portion identifier *ALL*. The first unused character position of portion, if any, must be a space. Example: 05 PORTION PIC X(30) VALUE "*ALL*". cplist is a checkpoint list in which the routine records the changes to the message storage data space. Example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 116 Libraries and Utility Routines DELETESTARTUP In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cplist can contain. In the CRE, the maximum number of elements that cplist can contain is the initial value of MAX-COUNT divided by 2.5. The cplist in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 04 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by DELETESTARTUP. Example: 04 RESULT PIC S9999 COMPUTATIONAL. DELETESTARTUP operates on the entire saved startup message. The program must have included a SAVE directive to save the message. Deleting the saved startup message has no effect on the current process. The IN and OUT files, the other run-command options, and any command-line parameters are permanently established for a given process by the initialization code that the process executes before the first statement of the COBOL program. Any process initiated by the current process after the execution of the DELETESTARTUP routine does not receive a startup message. DELETESTARTUP returns an integer value that indicates the outcome of this operation. The integer values and their meanings are: Value Meaning 0 The specified message or message portion is deleted. -1 Failure due to a logic error; nothing is deleted. These are possible logic errors: -2 • • The portion identifier is not correct. The contents of the checkpoint list parameter are inconsistent. Insufficient checkpoint list space is available to complete the deletion. The message is unchanged. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 117 Libraries and Utility Routines GETASSIGNTEXT GETASSIGNTEXT The GETASSIGNTEXT routine gets part of an ASSIGN message as text and assigns it to a string variable. The general form of the ENTER statement to use GETASSIGNTEXT is: ns ENTER OF ns GETASSIGNTEXT " " library-reference USING portion GIVING result text message-number VST363.vsd Note. GETASSIGNTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of GETASSIGNTEXT. portion is an alphanumeric data item that supplies the identifier for the particular text part of the message to be retrieved. The identifier must be one defined for the ASSIGN message (see Table 13-13). The first unused character position of portion, if any, must be a space. Example: 06 PORTION PIC X(30) VALUE "LOGICALNAME". There is a special portion identifier, *ALL*, accepted by this routine. The *ALL* identifier indicates that the routine must get the entire ASSIGN message. The maximum size of the ASSIGN message is 108 characters. If you use a smaller parameter, the routine truncates the message on the right. If you use a larger parameter, the routine pads it on the right with spaces. text is an alphanumeric data item into which the retrieved text is placed. If this data item is described with a JUSTIFIED clause, that clause is ignored. If the variable and the retrieved text differ in length, the retrieved text is truncated or extended with spaces as required. Example: 05 TEXT-VALUE PIC X(120). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 118 Libraries and Utility Routines GETASSIGNTEXT The text returned from a specific part of an ASSIGN message is: LOGICALNAME The text contains the program unit name and the logical file name, formatted like this, with a maximum of 63 characters: programunit.filename If the logical name does not include the program unit name, the text contains only this, with no qualifier: filename TANDEMNAME The text is the file-system file name and can have a maximum of 34 characters. The file name can be all spaces. Note. The text parameter must be declared as alphanumeric. Binder cannot detect the nuances between the various forms of byte-addressed COBOL data (such as numeric or alphanumeric edited data items that are not COMPUTATIONAL). The utility stores the characters it receives into the data item specified by text, ignoring COBOL MOVE rules. message-number identifies a specific ASSIGN message. message-number can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. The value must evaluate to a positive integer. Example: 03 MESSAGE-NUMBER PIC S9999 COMPUTATIONAL. Because each saved ASSIGN message is identified by a positive integer, message-number refers to the integer value of the specific message. The set of numbers associated with the ASSIGN messages are integers from 1 to N, where N is normally the number of ASSIGN messages saved during the initial process creation. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the text returned by GETASSIGNTEXT. Example: 03 RESULT PIC S9999 COMPUTATIONAL. GETASSIGNTEXT operates on the saved ASSIGN messages. The program must have included a SAVE directive to save the message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 119 Libraries and Utility Routines GETASSIGNVALUE GETASSIGNTEXT returns an integer value that indicates the outcome of this operation. The integer values and their meanings are: Value Meaning 0 or greater A string of value characters, before truncation or padding, is assigned to text. If the file-system file name is all spaces and the TANDEMNAME is requested, a 0 is returned. -1 Failure due to a logic error; nothing is assigned to text. These are possible logic errors: • • • The message number is not a positive integer. The specified message does not exist. The portion identifier is not correct, does not identify the defined text part of an ASSIGN message, or identifies a part that does not exist in the specified message. GETASSIGNVALUE The GETASSIGNVALUE routine retrieves a specified part of an ASSIGN message as an integer and assigns it to a numeric variable. The general form of the ENTER statement to use GETASSIGNVALUE is: ns ENTER OF ns GETASSIGNVALUE " " library-reference USING portion GIVING result val message-number VST364.vsd Note. GETASSIGNVALUE uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of GETASSIGNVALUE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 120 Libraries and Utility Routines GETASSIGNVALUE portion is an alphanumeric data item that supplies the identifier for the particular integer part of the message to be retrieved. The identifier must be one defined for the ASSIGN message (see Table 13-13). The first unused character position of portion, if any, must be a space. Example: 05 PORTION PIC X(30) VALUE "SECEXT". val is a numeric data item into which the retrieved value is placed. This data item must be COMPUTATIONAL and described with one to four nines. Example: 04 VAL PIC S9999 COMPUTATIONAL. message-number identifies a specific ASSIGN message. message-number can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. The value must evaluate to a positive integer. Example: 08 MESSAGE-NUMBER PIC S9999 COMPUTATIONAL. Because each saved ASSIGN message is identified by a positive integer, message-number refers to the integer value of the specific message. The set of numbers associated with the ASSIGN messages are integers from 1 to N, where N is normally the number of ASSIGN messages saved during the initial process creation. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by GETASSIGNVALUE. Example: 05 RESULT PIC S9999 COMPUTATIONAL. GETASSIGNVALUE operates on the saved ASSIGN messages. The program must have included a SAVE directive to save the message. GETASSIGNVALUE returns an integer value that indicates the outcome of this operation. The integer values and their meanings are: Value Meaning 0 The specified portion value was assigned to val. -1 Failure due to a logic error; nothing is assigned to val. These are possible logic errors: • • • The message number is not a positive integer. The specified message does not exist. The portion identifier is not correct. It does not identify a defined integer part of an ASSIGN message, or it identifies a part that does not exist in the specified message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 121 Libraries and Utility Routines GETBACKUPCPU GETBACKUPCPU The GETBACKUPCPU routine retrieves a backup processor number from the PARAM message of a COBOL program. Its operation depends on the existence of a saved PARAM message containing the parameter name BACKUPCPU with a digit string parameter value. GETBACKUPCPU is especially intended for TS/MP users. The general form of the ENTER statement to use GETBACKUPCPU is: ns ENTER " ns GETBACKUPCPU " TAL OF library-reference GIVING result VST365.vsd library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other loadfile containing an object copy of GETBACKUPCPU. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by GETBACKUPCPU. Example: 06 RESULT PIC S9999 COMPUTATIONAL. GETBACKUPCPU operates on the saved PARAM message. The program must have included a SAVE directive to save the message. GETBACKUPCPU returns an integer value that indicates the outcome of this operation. If a BACKUPCPU parameter exists and contains an integer string value in the range 0 through 99, that value is returned; otherwise, the integer value 99 is returned. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 122 Libraries and Utility Routines GETPARAMTEXT GETPARAMTEXT The GETPARAMTEXT routine gets a specified part of the PARAM message as text and assigns it to a string variable. The general form of the ENTER statement to use GETPARAMTEXT is: ns ENTER OF ns GETPARAMTEXT " " library-reference USING portion GIVING result text VST366.vsd Note. GETPARAMTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of GETPARAMTEXT. portion is an alphanumeric data item that supplies the identifier for the particular part of the message to be retrieved. The identifier must be a parameter name defined for the PARAM message. The first unused character position of portion, if any, must be a space. Example: 04 PORTION PIC X(30) VALUE "SITE". There is a special portion identifier, *ALL*, accepted by this routine. The *ALL* identifier indicates that the routine must get the entire PARAM message. The maximum size of the PARAM message is 1028 characters. If you use a smaller parameter, the routine truncates the message on the right. If you use a larger parameter, the routine pads it on the right with spaces. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 123 Libraries and Utility Routines GETPARAMTEXT text is the alphanumeric data item in which the retrieved text is placed. If this data item is described with a JUSTIFIED clause, that clause is ignored. If the variable and the retrieved text differ in length, the retrieved text is truncated or extended with spaces as required. Example: 13 TEXT-VALUE PIC X(120). The text returned from a specific PARAM message parameter is the parameter value associated with that parameter name. It can have a maximum of 255 characters. Note. The text parameter MUST be declared as alphanumeric. Binder cannot detect the nuances between the various forms of byte-addressed COBOL data (such as numeric or alphanumeric edited data that is not COMPUTATIONAL). The utility stores the characters it receives into the data item specified by text, ignoring COBOL MOVE rules. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by GETPARAMTEXT. Example: 04 RESULT PIC S9999 COMPUTATIONAL. GETPARAMTEXT operates on the saved PARAM message. The program must have included a SAVE directive to save the message. GETPARAMTEXT returns an integer value that indicates the outcome of this operation. The integer values and their meanings are: Value Meaning 0 or greater A string of value characters, before truncation or padding, is assigned to text. If the parameter value is a null string, a 0 is returned. -1 Failure due to a logic error; nothing is assigned to text. These are possible logic errors: • • The PARAM message does not exist. The portion identifier is not correct or identifies a parameter that does not exist in the PARAM message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 124 Libraries and Utility Routines GETSTARTUPTEXT GETSTARTUPTEXT The GETSTARTUPTEXT routine gets a specified part of the startup message as text and assign it to a string variable. The general form of the ENTER statement to use GETSTARTUPTEXT is: ns ENTER OF ns GETSTARTUPTEXT " " library-reference USING portion GIVING result text VST367.vsd Note. The ENTER verb must not be followed by the keyword TAL, because GETSTARTUPTEXT uses a protocol different from that of normal TAL procedures. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of GETSTARTUPTEXT. portion is an alphanumeric data item that supplies the identifier for the particular part of the message to be retrieved. The identifier must be one defined for the startup message (see Table 13-14). The first unused character position of portion, if any, must be a space. Example: 02 PORTION PIC X(30) VALUE "OUT". text is an alphanumeric data item into which the retrieved text is placed. If this data item is described with a JUSTIFIED clause, that clause is ignored. If the variable and the retrieved text differ in length, the retrieved text is truncated or extended with spaces as required. Example: 04 TEXT-VALUE PIC X(120). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 125 Libraries and Utility Routines GETSTARTUPTEXT The text values returned from specific startup message parts are: VOLUME The text contains the default system, volume, and subvolume names, formatted like this, with a maximum of 25 characters: \system.$volume.subvol If the volume part does not include the system name component, the text contains only this, with no system qualifier: $volume.subvol IN The text is the file system name of the input file and can have a maximum of 35 characters. The file name can be all spaces. OUT The text is the file system name of the output file name and can have a maximum of 35 characters. The file name can be all spaces. STRING The text is the startup message’s parameter string, not including trailing null characters, and can have a maximum of 526 characters. Note. The text parameter MUST be declared as alphanumeric. Binder cannot detect the nuances between the various forms of byte-addressed COBOL data (such as numeric or alphanumeric edited data that is not COMPUTATIONAL). The utility stores the characters it receives into the data item specified by text, ignoring COBOL MOVE rules. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by GETSTARTUPTEXT. Example: 77 RESULT PIC S9999 COMPUTATIONAL. GETSTARTUPTEXT operates on the saved startup message. The program must have included a SAVE directive to save the message. GETSTARTUPTEXT returns an integer value that indicates the outcome of this operation. The integer values are interpreted: Value Meaning 0 or greater A string of value characters, before truncation or padding, is assigned to text. If the file system name of the file is all spaces, a 0 is returned for IN or OUT. If the value is all spaces or a null string, a 0 is returned for STRING. -1 Failure due to a logic error; nothing is assigned to text. These are possible logic errors: • • The startup message does not exist. The portion identifier is not correct or does not identify a defined part of the startup message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 126 Libraries and Utility Routines PUTASSIGNTEXT PUTASSIGNTEXT The PUTASSIGNTEXT routine either creates or replaces a specified part of an ASSIGN message with text obtained from a string variable. The general form of the ENTER statement to use PUTASSIGNTEXT is: ns ENTER OF ns PUTASSIGNTEXT " " library-reference USING portion text cplist message-number GIVING result VST368.vsd Note. PUTASSIGNTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of PUTASSIGNTEXT. portion is an alphanumeric data item that supplies the identifier for the particular text part of the message to be changed. The identifier must be one defined for the ASSIGN message (see Table 13-13). The first unused character position of portion, if any, must be a space. Example: 03 PORTION PIC X(30) "TANDEMNAME". text is an alphanumeric data item containing the new value of the specified message part. Any trailing spaces are ignored. Example: 07 TEXT-VALUE PIC X(120). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 127 Libraries and Utility Routines PUTASSIGNTEXT Appropriate text values for ASSIGN message parts are LOGICALNAME The text contains the program unit name and the logical file name, formatted like this, with a maximum of 63 characters: programunit.filename If the logical name does not include the program unit name, the text contains only this, with no qualifier: filename TANDEMNAME The text is the file-system file name and can have a maximum of 35 characters. The file name can be all spaces. cplist is a checkpoint list in which the routine records the changes to the message storage data space. Example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cplist can contain. In the CRE, the maximum number of elements that cplist can contain is the initial value of MAX-COUNT divided by 2.5. The cplist in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 03 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. message-number identifies a specific ASSIGN message. message-number can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. The value must evaluate to a positive integer. Example: 05 MESSAGE-NUMBER PIC S9999 COMPUTATIONAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 128 Libraries and Utility Routines PUTASSIGNTEXT Because each saved ASSIGN message is identified by a positive integer, message-number refers to the integer value of the specific message. The set of numbers associated with the ASSIGN messages are integers from 1 to N, where N is normally the number of ASSIGN messages saved during the initial process creation. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by PUTASSIGNTEXT. Example: 04 RESULT PIC S9999 COMPUTATIONAL. PUTASSIGNTEXT operates on the saved ASSIGN messages. The program must have included a SAVE directive to save the message. Changing a saved ASSIGN message has no effect on the current process. Any file assignments (except for dynamic assignments, as explained under COBOLASSIGN) are permanently established for a given process by the initialization code that the process executes before the first statement of the COBOL program. Any process initiated by the current process after execution of the PUTASSIGNTEXT routine inherits the changed ASSIGN message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 129 Libraries and Utility Routines PUTASSIGNTEXT PUTASSIGNTEXT returns an integer value that indicates the outcome of this operation. If the specified ASSIGN message does not exist, the PUTASSIGNTEXT routine attempts to create one containing the supplied text portion and default values for all other message parts. If this operation fails, a -1, -2, or -3 value is returned. The integer values and their meanings are: Value Meaning 0 or greater A string of that many characters is assigned as the new message part value. A 0 is returned for TANDEMNAME if the file name supplied is all spaces. -1 Failure due to a logic error. The message is unchanged. These are possible logic errors: • • • • • • The portion identifier is not correct or does not identify a defined text part of the ASSIGN message. The text string is not acceptable because either the logical file name or the file system name of the file is incorrect. The message number is not a positive integer. The requested logical file name conflicts with the logical file name of another saved ASSIGN message. The contents of the checkpoint list parameter are inconsistent. The specified ASSIGN message does not exist, and the portion identifier is not LOGICALNAME -2 Insufficient checkpoint list space is available to complete the operation. The message is unchanged. -3 Insufficient stack space to create or replace message. The message is unchanged. Moving large data items from the Working-Storage Section to the Extended-Storage Section, either manually or with the LARGEDATA directive, might solve the problem. The ASSIGN message creation is successful if both message space and cplist space are available, the requested portion is the logical name, and the requested logical file name does not conflict with that of another saved ASSIGN message. All other parts are marked “not present in this message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 130 Libraries and Utility Routines PUTASSIGNVALUE PUTASSIGNVALUE The PUTASSIGNVALUE routine either creates or replaces a specified part of an ASSIGN message with the value obtained from an integer variable. The general form of the ENTER statement to use PUTASSIGNVALUE is: " ENTER OF ns ns PUTASSIGNVALUE " library-reference USING portion val cplist message-number GIVING result VST369.vsd Note. PUTASSIGNVALUE uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other loadfile containing an object copy of PUTASSIGNVALUE. portion is an alphanumeric data item that supplies the identifier for the particular integer part of the message to be changed. The identifier must be one defined for the ASSIGN message (see Table 13-13). The first unused character position of portion, if any, must be a space. Example: 06 PORTION PIC X(30) VALUE "BLKSIZE". val is the new value of the message part. val can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. The value must evaluate to an integer consistent with the message part to be created or replaced. Example: 07 VAL PIC S9999 COMPUTATIONAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 131 Libraries and Utility Routines PUTASSIGNVALUE cplist is a checkpoint list in which the routine records the changes to the message storage data space. Example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cplist can contain. In the CRE, the maximum number of elements that cplist can contain is the initial value of MAX-COUNT divided by 2.5. The cplist in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 77 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. message-number identifies a specific ASSIGN message. message-number can be a DISPLAY or COMPUTATIONAL numeric data item, a numeric literal, or an expression enclosed in parentheses. The value must evaluate to a positive integer. Example: 22 MESSAGE-NUMBER PIC S9999 COMPUTATIONAL. Because each saved ASSIGN message is identified by a positive integer, message-number refers to the integer value of the specific message. The set of numbers associated with the ASSIGN messages are integers from 1 to N, where N is normally the number of ASSIGN messages saved during the initial process creation. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by PUTASSIGNVALUE. Example: 05 RESULT PIC S9999 COMPUTATIONAL. PUTASSIGNVALUE operates on the saved ASSIGN messages. The program must have included a SAVE directive to save the message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 132 Libraries and Utility Routines PUTPARAMTEXT Changing a saved ASSIGN message has no effect on the current process. Any file assignments (except for dynamic assignments, as explained under COBOLASSIGN) are permanently established for a given process by the initialization code that the process executes before the first statement of the COBOL program. Any process initiated by the current process after execution of PUTASSIGNVALUE routine inherits the changed ASSIGN message. PUTASSIGNVALUE returns an integer value that indicates the outcome of this operation. The integer values and their meanings are: Value Meaning 0 Value of val is assigned as the new value of the requested message part. -1 Failure due to a logic error. Nothing is changed. These are possible logic errors: • • • • The portion identifier is not correct or does not identify a defined text part of the ASSIGN message. The integer value supplied is not acceptable for the specified part of the ASSIGN message. The message number is not a positive integer. The specified message does not exist. A nonexistent ASSIGN message must be created by the PUTASSIGNTEXT routine with the specified part of the logical name. -2 Insufficient checkpoint list space is available to complete the operation. The message is unchanged. -3 Insufficient stack space to create or replace message. The message is unchanged. Moving large data items from the Working-Storage Section to the Extended-Storage Section, either manually or with the LARGEDATA directive, might solve the problem. PUTPARAMTEXT The PUTPARAMTEXT routine either creates or replaces a specified part of the PARAM message with text obtained from a string variable. The general form of the ENTER statement to use PUTPARAMTEXT is: ns ENTER " OF ns PUTPARAMTEXT " library-reference USING portion GIVING result text cplist VST370.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 133 Libraries and Utility Routines PUTPARAMTEXT Note. PUTPARAMTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of PUTPARAMTEXT. portion is an alphanumeric data item that supplies the identifier for the particular part of the message to be changed. The identifier must be a parameter name defined for the PARAM message. The first unused character position of portion, if any, must be a space. Example: 04 PORTION PIC X(30) VALUE "CONTINENT". text is an alphanumeric data item containing the new value for the parameter. Any trailing spaces are ignored. Example: 01 TEXT-VALUE PIC X(120) VALUE "ANTARCTICA". cplist is a checkpoint list in which the routine records the changes to the message storage data space. Example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cplist can contain. In the CRE, the maximum number of elements that cplist can contain is the initial value of MAX-COUNT divided by 2.5. The cplist in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 04 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 134 Libraries and Utility Routines PUTPARAMTEXT result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by PUTPARAMTEXT. Example: 04 RESULT PIC S9999 COMPUTATIONAL. PUTPARAMTEXT operates on the saved PARAM message. The program must have included a SAVE directive to save the message. Changing the saved PARAM message has no effect on the current process. Any DEBUG, SWITCH-nn, NONSTOP, or other named parameters are permanently established for a given process by the initialization code that the process executes before the first statement of the COBOL program. Any process initiated by the current process after execution of the PUTPARAMTEXT routine inherits the modified PARAM message. PUTPARAMTEXT returns an integer value that indicates the outcome of this operation. If the PARAM message does not exist, the PUTPARAMTEXT routine attempts to create one containing the supplied parameter name and value. If this operation fails, a -1, -2, or -3 value is returned. The integer values are interpreted: Value Meaning 0 or positive integer A string of value characters is assigned as the new parameter value. If the string is all spaces, a 0 is returned. -1 Failure due to a logic error. Nothing is changed. These are possible logic errors: • • • • The portion identifier is not correct. The new parameter value string exceeds 255 characters. The total length of the new PARAM message exceeds the maximum. The contents of the checkpoint list parameter are inconsistent. -2 Insufficient checkpoint list space is available to complete the operation. The message does not change. -3 Insufficient stack space to create or replace message. The message is unchanged. Moving large data items from the Working-Storage Section to the Extended-Storage Section, either manually or with the LARGEDATA directive, might solve the problem. The PARAM message creation is successful if both message space and cplist space are available, and the new message contains only the parameter name and value supplied to PUTPARAMTEXT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 135 Libraries and Utility Routines PUTSTARTUPTEXT PUTSTARTUPTEXT The PUTSTARTUPTEXT routine either creates or replaces a specified part of the startup message with text obtained from a string variable. The general form of the ENTER statement to use PUTSTARTUPTEXT is: ns ENTER OF ns PUTSTARTUPTEXT " " library-reference USING portion GIVING result text cplist VST371.vsd Note. PUTSTARTUPTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. library-reference is a mnemonic-name associated in the SPECIAL-NAMES paragraph with either $SYSTEM.SYSTEM.COBOLLIB or some other object file containing an object copy of PUTSTARTUPTEXT. portion is an alphanumeric data item that supplies the identifier for the particular part of the message to be changed. The identifier must be one defined for the startup message (see Table 13-14). The first unused character position of portion, if any, must be a space. Example: 03 PORTION PIC X(30) VALUE "VOLUME". text is an alphanumeric data item containing the new value for the specified message part. Any trailing spaces are ignored. Example: 04 TEXT-VALUE PIC X(120). HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 136 Libraries and Utility Routines PUTSTARTUPTEXT Appropriate text values for startup message parts are: VOLUME The text is the new default system, volume, and subvolume names, formatted like this, with a maximum of 26 characters: \system.$volume.subvol If the new volume part does not include the system name component, the text is just this, with no system qualifier. $volume.subvol IN The text is the file system name of the new input file and can have a maximum of 35 characters. The file name can be all spaces. OUT The text is the file system name of the new output file and can have a maximum of 35 characters. The file name can be all spaces. STRING The text is the new message parameter string, not including trailing null characters, and can have a maximum of 526 characters. cplist is a checkpoint list in which the routine records the changes to the message storage data space. Example: 01 CP-LIST-1. 05 MAX-COUNT 05 CURRENT-COUNT 05 ELEMENT PIC 9999 PIC 9999 PIC 9(9) COMP COMP COMP VALUE IS 100. VALUE IS 0. OCCURS 100 TIMES. The initial value of MAX-COUNT must be the same as the number of occurrences of ELEMENT. In the non-CRE environment, the initial value of MAX-COUNT is the maximum number of elements that cplist can contain. In the CRE, the maximum number of elements that cplist can contain is the initial value of MAX-COUNT divided by 2.5. The cplist in the preceding example can contain 100 elements in the non-CRE environment, but only 40 in the CRE. The required number of table elements depends on the number of operations the list must record. The worst-case situation uses six elements. A complete checkpoint list is required only when a program has a backup that must be kept current. When a record of changes is not required, a null checkpoint list can be used. This is an example description: 08 CP-LIST-1 PIC 9(9) COMP VALUE IS 0. result is a DISPLAY or COMPUTATIONAL numeric data item assigned the result returned by PUTSTARTUPTEXT. Example: 04 RESULT PIC S9999 COMPUTATIONAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 137 Libraries and Utility Routines PUTSTARTUPTEXT PUTSTARTUPTEXT operates on the saved startup message. The program must have included a SAVE directive to save the message. Changing the saved startup message has no effect on the current process. The IN and OUT files, the other run-command options, and any command-line parameters are permanently established for a given process by the initialization code that the process executes before the first statement of the COBOL program. Any process initiated by the current process after execution of the PUTSTARTUPTEXT routine receives the changed startup message. PUTSTARTUPTEXT returns an integer value that indicates the outcome of this operation. If the startup message does not exist, PUTSTARTUPTEXT attempts to create one containing the requested text portion and default values for all other message parts. If this operation fails, a -1, -2, or -3 value is returned. The integer values and their meanings are: Value Meaning 0 or greater A string of value characters is assigned as the new message part value. If the file name supplied is all spaces, a 0 is returned for IN or OUT. If the value supplied is all spaces, a 0 is returned for STRING. -1 Failure due to a logic error. The message is unchanged. These are possible logic errors: • • • The portion identifier is not correct or does not identify a defined text part of the startup message The text string value is not acceptable: there is an illegal system, volume, or subvolume name; an illegal file name; or a message parameter string that exceeds 526 characters. The contents of the checkpoint list parameter are inconsistent. -2 Insufficient checkpoint list space is available to complete the operation. The message does not change. -3 Insufficient stack space to create or replace message. The message is unchanged. Moving large data items from the Working-Storage Section to the Extended-Storage Section, either manually or with the LARGEDATA directive, might solve the problem. The startup message creation is successful if both message space and cplist space are available, and the new message contains the message part requested. All other message parts are set to their default values. The default values for VOLUME, IN, and OUT are taken from those of the current program. The default value for the message parameter string is a null string. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 138 Libraries and Utility Routines Guardian Environment Level 3 Spooling Routines Guardian Environment Level 3 Spooling Routines Before the CBL85UTL file included the routines COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_, the Guardian environment routines in Table 13-19 were used for level 3 spooling. They were called with the ENTER verb. Table 13-19. Guardian Environment Level 3 Spooling Routines Routine Action CLOSE Closes the spooler collector OPEN Opens the spooler collector SPOOLCONTROL Handles VFU channel skipping SPOOLCONTROLBUF Handles the loading of programmable VFU for the model 5220 printer SPOOLEND Signals the end of a spooler job and can change attributes before a new spooler job starts without closing and reopening the spooler collector SPOOLSETMODE Sets automatic perforation skipping, system spacing control, baud rate, form length, vertical tabs, automatic-answer or controlanswer mode, horizontal pitch, pre- or post-spacing, get device status, or reset to configured values SPOOLSTART Establishes the Level 3 buffer, location name, form name, report name, number of copies, page size, and attributes such as HOLD and PRIORITY SPOOLWRITE Writes text to the spooler For information on these routines, see the Guardian Procedure Calls Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 139 Libraries and Utility Routines Guardian Environment Level 3 Spooling Routines HP COBOL Manual for TNS and TNS/R Programs —522555-006 13- 140 14 Intrinsic Functions An intrinsic function is a function that your program can use, but does not need to declare. It returns a value that is computed at the time of reference during the execution of the object program. Like an identifier, an intrinsic function has a class and category, and you can use an intrinsic function wherever you can use an identifier of the same class and category as a sending data item. An intrinsic function call, which has the format FUNCTION function_name (arguments) is considered an identifier. For example, this is allowed: MOVE FUNCTION NUMVAL (STRING-ITEM) TO NUM-ITEM. You cannot use an intrinsic function as a receiving data item (in a CALL statement, for example). (For explanations of class and category, see Data Levels, Classes, and Categories.) Topics: • • • Intrinsic Function Types Argument Types The intrinsic functions themselves in alphabetic order: ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ACOS Function ANNUITY Function ASIN Function ATAN Function CHAR Function COS Function CURRENT-DATE Function DATE-OF-INTEGER Function DAY-OF-INTEGER Function FACTORIAL Function INTEGER Function INTEGER-OF-DATE Function INTEGER-OF-DAY Function INTEGER-PART Function LENGTH Function HP COBOL Manual for TNS and TNS/R Programs —522555-006 14- 1 Intrinsic Functions ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° LOG Function LOG10 Function LOWER-CASE Function MAX Function MEAN Function MEDIAN Function MIDRANGE Function MIN Function MOD Function NUMVAL Function NUMVAL-C Function ORD Function ORD-MAX Function ORD-MIN Function PRESENT-VALUE Function RANDOM Function RANGE Function REM Function REVERSE Function SIN Function SQRT Function STANDARD-DEVIATION Function SUM Function TAN Function UPPER-CASE Function VARIANCE Function WHEN-COMPILED Function HP COBOL Manual for TNS and TNS/R Programs —522555-006 14- 2 Intrinsic Functions Intrinsic Function Types Intrinsic Function Types The type of an intrinsic function is the type of the value it returns. An intrinsic function can be: • • • • Alphanumeric Intrinsic Functions Numeric Intrinsic Functions Integer Intrinsic Functions Variable-Type Intrinsic Functions You can use an integer function wherever you can use a numeric operand, but you cannot use a numeric function where an integer operand is required, even if a particular reference to the numeric function returns an integer value. You can nest intrinsic functions; that is, you can use one intrinsic function as the argument of another. The function that is used as the argument must be of the type required for that argument. For example, FUNCTION MAX ( FUNCTION INTEGER(X) FUNCTION INTEGER-PART(X) ) is allowed because the functions INTEGER and INTEGER-PART are integer functions and the function MAX accepts integer arguments. FUNCTION UPPER-CASE ( FUNCTION FACTORIAL(5) ) is not allowed because the function FACTORIAL is an integer function and the function UPPER-CASE requires an alphanumeric argument. Alphanumeric Intrinsic Functions An alphanumeric intrinsic function returns an alphanumeric value (a string of one or more alphanumeric characters). Table 14-1. Alphanumeric Intrinsic Functions Function Name Value Returned CHAR Function Character in specified position of program collating sequence CURRENT-DATE Function Current date and time and difference from Greenwich mean time LOWER-CASE Function Its argument with all letters set to lowercase REVERSE Function Its argument with characters in reverse order UPPER-CASE Function Its argument with all letters set to uppercase WHEN-COMPILED Function Date and time when program was compiled HP COBOL Manual for TNS and TNS/R Programs —522555-006 14- 3 Intrinsic Functions Numeric Intrinsic Functions Numeric Intrinsic Functions A numeric intrinsic function returns a numeric value. Table 14-2. Numeric Intrinsic Functions Function Name Value Returned ACOS Function Arccosine of argument ANNUITY Function Ratio of annuity paid for a specified number of periods at a specified interest rate to initial investment of one ASIN Function Arcsine of argument ATAN Function Arctangent of argument COS Function Cosine of argument LOG Function Natural logarithm of argument LOG10 Function Logarithm to base 10 of argument MEAN Function Arithmetic mean of arguments MEDIAN Function Median of arguments MIDRANGE Function Midrange of arguments NUMVAL Function Numeric value of simple numeric string NUMVAL-C Function Numeric value of numeric string with optional commas and currency sign PRESENT-VALUE Function Present value of a specified series of future period-end amounts at a specified discount rate RANDOM Function Pseudorandom number REM Function Remainder when one argument is divided by the other SIN Function Sine of argument SQRT Function Square root of argument STANDARD-DEVIATION Function Standard deviation of arguments TAN Function Tangent of argument VARIANCE Function Variance of arguments HP COBOL Manual for TNS and TNS/R Programs —522555-006 14- 4 Intrinsic Functions Integer Intrinsic Functions Integer Intrinsic Functions An integer intrinsic function returns an integer value. Table 14-3. Integer Intrinsic Functions Function Name Value Returned DATE-OF-INTEGER Function Standard date equivalent of integer date (YYYYMMDD )* DAY-OF-INTEGER Function Julian date equivalent of integer date (YYYYDDD )* FACTORIAL Function Factorial of argument INTEGER Function Greatest integer not greater than argument INTEGER-OF-DATE Function Integer date equivalent of standard date (YYYYMMDD )* INTEGER-OF-DAY Function Integer date equivalent of Julian date (YYYYDDD )* INTEGER-PART Function Integer part of argument LENGTH Function Length of argument MOD Function First argument modulo second argument ORD Function Ordinal position of argument in program collating sequence ORD-MAX Function Ordinal position of maximum argument ORD-MIN Function Ordinal position of minimum argument * Date conversion functions use the Gregorian calendar. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14- 5 Intrinsic Functions Variable-Type Intrinsic Functions Variable-Type Intrinsic Functions The type of some intrinsic functions depends on the type(s) of its arguments. Table 14-4. Variable-Type Intrinsic Functions Function Name Value Returned MAX Function Value of maximum argument MIN Function Value of minimum argument RANGE Function Value of maximum argument minus value of minimum argument SUM Function Sum of arguments Table 14-5. How Argument Type Determines Variable-Type Intrinsic Function Type Argument Type Function Type Alphabetic Alphanumeric Alphanumeric Alphanumeric Integer Integer Numeric (some can be integer) Numeric Note. Not every function in Table 14-4 can have arguments of every type in Table 14-5. For valid argument types for a particular function, see the description of that function later in this section. Argument Types Table 14-6 lists the types of arguments that intrinsic functions can have, tells you what you must specify for an argument of each type, and tells you what is used in determining the function’s value. Note. Not every intrinsic function can have arguments of every type in Table 14-6. For valid argument types for a particular function, see the description of that function later in this section. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14- 6 Intrinsic Functions Argument Types Table 14-6. Argument Types Argument Type What You Must Specify What is Used in Determining the Function’s Value Numeric Arithmetic expression Value of arithmetic expression, including operational sign Integer Arithmetic expression that always results in integer value Value of arithmetic expression, including operational sign Alphabetic Elementary data item of the class alphabetic, or nonnumeric literal containing only alphabetic characters Value of argument and possibly its size Alphanumeric Data item of the class alphabetic or alphanumeric, or nonnumeric literal Value of argument and possibly its size An arithmetic expression used as an argument can include subscripts, and any subscript can be the keyword ALL. When ALL is a subscript, the effect is as if each table element associated with that subscript position were specified. The order of the implicit specification of each occurrence is from left to right. The leftmost specification is the identifier with each subscript specified by the word ALL replaced by one. The next specification is the same identifier with the rightmost subscript specified by the word ALL incremented by one. This process continues with the rightmost ALL subscript being incremented by one for each implicit specification until the rightmost ALL subscript has been incremented through its range of values. If there are additional ALL subscripts, the ALL subscript immediately to the left of the rightmost ALL subscript is incremented by one, the rightmost ALL subscript is set to one, and the process of varying the rightmost ALL subscript is repeated. The ALL subscript to the left of the rightmost ALL subscript is incremented by one through its range of values. For each additional ALL subscript, this process is repeated until the leftmost ALL subscript has been incremented by one through its range of values. If the ALL subscript is associated with an OCCURS DEPENDING clause, the object of the OCCURS DEPENDING clause determines the range of values. The evaluation of an ALL subscript must result in at least one argument, or the result of the reference to the function-identifier is undefined. An invalid argument causes a run-time error. In the non-CRE environment, it is error 130 (“Invalid function parameter”). In the CRE, it is error 40 (“Invalid function parameter”). If you are executing an old object file on a newer system, the error might be “Corrupted environment.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 14- 7 Intrinsic Functions ACOS Function ACOS Function ACOS, a numeric function, returns a value in radians that approximates the arccosine of its argument. FUNCTION ACOS ( argument ) VST421.vsd argument is a numeric argument whose value is in the range -1 to +1. The returned value approximates the arccosine of the value of argument. It is a floating-point number in the range zero to pi. It has no implied decimal point and is precise to approximately 14 digits. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-1. ACOS Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION ACOS DISPLAY A. MOVE FUNCTION ACOS DISPLAY A. MOVE FUNCTION ACOS DISPLAY A. MOVE FUNCTION ACOS DISPLAY A. MOVE FUNCTION ACOS DISPLAY A. (-1) TO A. (.25) TO A. (.5) TO A. (.75) TO A. (1) TO A. Output: 3.14 1.31 1.04 0.72 0.00 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14- 8 Intrinsic Functions ANNUITY Function ANNUITY Function ANNUITY, a numeric function, returns a value that approximates the ratio of an annuity paid at the end of each period for a specified number of periods at a specified interest rate to an initial investment of one. Interest is applied at the end of the period, before the payment (annuity immediate). FUNCTION ( ANNUITY interest-rate number-of-periods ) VST422.vsd interest-rate is a numeric argument whose value is greater than or equal to zero. number-of-periods is a positive integer. When the value of interest-rate is zero, the returned value is approximately: ----------------1 ----------------number-of-periods When the value of interest-rate is not zero, the returned value is approximately: interest-rate -------------------------------------------------------------------------------------------------------– number-of-periods + interest-rate) Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14- 9 Intrinsic Functions ANNUITY Function Example 14-2. ANNUITY Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE 9V99. PROCEDURE DIVISION. MOVE FUNCTION ANNUITY DISPLAY A. MOVE FUNCTION ANNUITY DISPLAY A. MOVE FUNCTION ANNUITY DISPLAY A. MOVE FUNCTION ANNUITY DISPLAY A. MOVE FUNCTION ANNUITY DISPLAY A. (1 12) TO A. (1 6) TO A. (2 6) TO A. (5 2) TO A. (0 5) TO A. Output: 1.00 1.01 2.00 5.14 0.20 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -10 Intrinsic Functions ASIN Function ASIN Function ASIN, a numeric function, returns a value in radians that approximates the arcsine of its argument. FUNCTION ASIN ( argument ) VST423.vsd argument is a numeric argument whose value is in the range -1 to +1. The returned value approximates the arcsine of the value of argument. It is a floatingpoint number in the range -pi/2 to +pi/2. It has no implied decimal point and is precise to approximately 14 digits. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-3. ASIN Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION ASIN DISPLAY A. MOVE FUNCTION ASIN DISPLAY A. MOVE FUNCTION ASIN DISPLAY A. MOVE FUNCTION ASIN DISPLAY A. MOVE FUNCTION ASIN DISPLAY A. (-1) TO A. (.25) TO A. (.5) TO A. (.75) TO A. (1) TO A. Output: -1.57 0.25 0.52 0.84 1.57 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -11 Intrinsic Functions ATAN Function ATAN Function ATAN, a numeric function, returns a value in radians that approximates the arctangent of its argument. FUNCTION ATAN ( argument ) VST424.vsd argument is a numeric argument. The returned value approximates the arctangent of the value of argument. It is a floating-point number in the range -pi/2 to +pi/2, excluding the endpoints. It has no implied decimal point and is precise to approximately 14 digits. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-4. ATAN Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION ATAN DISPLAY A. MOVE FUNCTION ATAN DISPLAY A. MOVE FUNCTION ATAN DISPLAY A. MOVE FUNCTION ATAN DISPLAY A. MOVE FUNCTION ATAN DISPLAY A. (-10) TO A. (0) TO A. (.25) TO A. (15.5) TO A. (45) TO A. Output: -1.47 0.00 0.24 1.50 1.54 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -12 Intrinsic Functions CHAR Function CHAR Function CHAR, an alphanumeric function, returns a character whose ordinal number in the program collating sequence is the value of its argument. FUNCTION CHAR ( argument ) VST425.vsd argument is an integer greater than zero and less than or equal to n, where n is the number of positions in the program collating sequence. If more than one character has the same position in the program collating sequence, the returned character is the first character that the ALPHABET clause specifies for that character position. If the current program collating sequence was not specified by an ALPHABET clause, HP COBOL uses the ASCII program collating sequence. Example 14-5. CHAR Function Without ALPHABET Clause Code: DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION CHAR CHAR CHAR CHAR CHAR (36) (43) (54) (69) (99) Output: # * 5 D b HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -13 Intrinsic Functions CHAR Function Example 14-6. CHAR Function With ALPHABET Clause Code: ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES. ALPHABET CAPITAL-LETTERS IS 66 THRU 91. SOURCE-COMPUTER. ABD. OBJECT-COMPUTER. ABD PROGRAM COLLATING SEQUENCE IS CAPITAL-LETTERS. PROCEDURE Startt. DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DIVISION. FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION CHAR CHAR CHAR CHAR CHAR (1) (2) (13) (20) (25) Output: A B M T Y HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -14 Intrinsic Functions COS Function COS Function COS, a numeric function, returns a value that approximates the cosine of the angle or arc (in radians) specified by its argument. FUNCTION COS ( argument ) VST426.vsd argument is a numeric argument. The returned value approximates the cosine of the value of argument. It is a floatingpoint number in the range -1 to +1. It has no implied decimal point and is precise to approximately 14 digits. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-7. COS Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION COS DISPLAY A. MOVE FUNCTION COS DISPLAY A. MOVE FUNCTION COS DISPLAY A. MOVE FUNCTION COS DISPLAY A. MOVE FUNCTION COS DISPLAY A. (-10) TO A. (0) TO A. (.25) TO A. (15.5) TO A. (45) TO A. Output: -0.83 1.00 0.96 -0.97 0.52 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -15 Intrinsic Functions CURRENT-DATE Function CURRENT-DATE Function CURRENT-DATE, an alphanumeric function, returns a 21-character string that represents the calendar date, time of day, and local time differential factor provided by the operating environment. FUNCTION CURRENT-DATE VST427.vsd The returned value represents the current date this way (where character position 1 is the leftmost character position): Character Positions Date Part Represented Represented by 1-4 Year in Gregorian calendar Four digits 5-6 Month of the year Two digits in the range 01 through 12 7-8 Day of the month Two digits in the range 01 through 31 9-10 Hours past midnight Two digits in the range 00 through 23 11-12 Minutes past the hour Two digits in the range 00 through 59 13-14 Seconds past the minute Two digits in the range 00 through 59 15-16 Hundredths of seconds past the second Two digits in the range 00 through 99 17 Relationship to Greenwich mean time Minus (-) if the reported time is behind Greenwich mean time, plus (+) if it is the same as or ahead of Greenwich mean time 18-19 Hours behind or ahead of Greenwich mean time If character position 17 is minus (-), two digits in the range 00 through 12; if character position 17 is plus (+), two digits in the range 00 through 13 20-21 Additional minutes from Greenwich mean time Two digits in the range 00 through 59 Example 14-8. CURRENT-DATE Function Code: DISPLAY FUNCTION CURRENT-DATE Output: 1997041116522224-0700 The date in Example 14-8 is April 11, 1997 (19970411). The time is 16:52:22.24 or 4:52:22.24 PM (16522224), which is 7 hours behind Greenwich mean time (-0700). HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -16 Intrinsic Functions DATE-OF-INTEGER Function DATE-OF-INTEGER Function DATE-OF-INTEGER, an integer function, converts a date in the Gregorian calendar from integer date form to standard date form (YYYYMMDD ). FUNCTION DATE-OF-INTEGER ( argument ) VST428.vsd argument is a positive integer that represents a number of days since December 31, 1600, in the Gregorian calendar. The returned value is of the form YYYYMMDD, where YYYY represents the year in the Gregorian calendar, MM represents the month of that year, and DD represents the day of that month. Example 14-9. DATE-OF-INTEGER Function Code: DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION DATE-OF-INTEGER DATE-OF-INTEGER DATE-OF-INTEGER DATE-OF-INTEGER DATE-OF-INTEGER (1) (365) (36500) (12345) (100000) Output: 16010101 16011231 17001207 16341019 18741016 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -17 Intrinsic Functions DAY-OF-INTEGER Function DAY-OF-INTEGER Function DAY-OF-INTEGER, an integer function, converts a date in the Gregorian calendar from integer date form to Julian date form (YYYYDDD ). FUNCTION DAY-OF-INTEGER ( argument ) VST429.vsd argument is a positive integer that represents a number of days since December 31, 1600, in the Gregorian calendar. The returned value is of the form YYYYDDD, where YYYY represents the year in the Gregorian calendar and DDD represents the day of that year. Example 14-10. DAY-OF-INTEGER Function Code: DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION DAY-OF-INTEGER DAY-OF-INTEGER DAY-OF-INTEGER DAY-OF-INTEGER DAY-OF-INTEGER (1) (365) (36500) (12345) (100000) Output: 1601001 1601365 1700341 1634292 1874289 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -18 Intrinsic Functions FACTORIAL Function FACTORIAL Function FACTORIAL, an integer function, returns the factorial of its argument. FUNCTION FACTORIAL ( argument ) VST430.vsd argument is an integer greater than or equal to zero. When argument is zero, the returned value is 1; when argument is positive, the returned value is its factorial. Example 14-11. FACTORIAL Function Code: DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION FACTORIAL FACTORIAL FACTORIAL FACTORIAL FACTORIAL (0) (1) (4) (6) (10) Output: 0000000000000000001 0000000000000000001 0000000000000000024 0000000000000000720 0000000000003628800 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -19 Intrinsic Functions INTEGER Function INTEGER Function INTEGER, an integer function, returns the greatest integer that is less than or equal to its argument. FUNCTION INTEGER ( argument ) VST431.vsd argument is a numeric argument. The returned value is the greatest integer that is less than or equal to the value of argument. Example 14-12. INTEGER Function Code: DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION INTEGER INTEGER INTEGER INTEGER (-3.5) (-3) (3) (3.5) Output: -4 -3 3 3 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -20 Intrinsic Functions INTEGER-OF-DATE Function INTEGER-OF-DATE Function INTEGER-OF-DATE, an integer function, converts a date in the Gregorian calendar from standard date form (YYYYMMDD ) to integer date form. FUNCTION INTEGER-OF-DATE ( argument ) VST432.vsd argument is an integer of the form YYYYMMDD, whose value is calculated from the equation (YYYY * 10,000) + (MM * 100) + DD where: Factor Date Part Represented Represented by YYYY Year in Gregorian calendar Integer in the range 1,601 through 9,999 MM Month of the year Integer in the range 1 through 12 DD Day of the month Integer in the range 1 through 31 that is a valid day for the month specified by MM The returned value is an integer that is the number of days that the date represented by argument succeeds December 31, 1600, in the Gregorian calendar. Example 14-13. INTEGER-OF-DATE Function Code: DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION INTEGER-OF-DATE INTEGER-OF-DATE INTEGER-OF-DATE INTEGER-OF-DATE INTEGER-OF-DATE (16010101) (16011231) (17001207) (16341019) (18741016) Output: 00000001 00000365 00036500 00012345 00100000 Example 14-14 uses the INTEGER-OF-DATE and REM functions to find the day of the week for dates in standard date form (YYYYMMDD). For a description of the REM function, see REM Function. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -21 Intrinsic Functions INTEGER-OF-DATE Function Example 14-14. INTEGER-OF-DATE Function Code: ?ENV COMMON IDENTIFICATION DIVISION. PROGRAM-ID. TESTT. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. ABD. OBJECT-COMPUTER. ABD. DATA DIVISION. WORKING-STORAGE SECTION. 01 D PICTURE 9 USAGE COMPUTATIONAL. 01 STD-DATE PICTURE 9(8) USAGE COMPUTATIONAL. PROCEDURE DIVISION. STARTT. PERFORM VARYING STD-DATE FROM 19970618 BY 1 UNTIL STD-DATE > 19970624 DISPLAY STD-DATE MOVE FUNCTION REM (FUNCTION INTEGER-OF-DATE (STD-DATE) 7) TO D IF D = 0 THEN DISPLAY " SUNDAY" ELSE IF D = 1 THEN DISPLAY " MONDAY" ELSE IF D = 2 THEN DISPLAY " TUESDAY" ELSE IF D = 3 THEN DISPLAY " WEDNESDAY" ELSE IF D = 4 THEN DISPLAY " THURSDAY" ELSE IF D = 5 THEN DISPLAY " FRIDAY" ELSE IF D = 6 THEN DISPLAY " SATURDAY" END-IF END-IF END-IF END-IF END-IF END-IF END-IF END-PERFORM. STOP RUN. Output: 19970618 WEDNESDAY 19970619 THURSDAY 19970620 FRIDAY 19970621 SATURDAY 19970622 SUNDAY 19970623 MONDAY 19970624 TUESDAY HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -22 Intrinsic Functions INTEGER-OF-DAY Function INTEGER-OF-DAY Function INTEGER-OF-DAY, an integer function, converts a date in the Gregorian calendar from Julian date form (YYYYDDD ) to integer date form. FUNCTION INTEGER-OF-DAY ( ) argument VST433.vsd argument is an integer of the form YYYYDDD, whose value is calculated from the equation (YYYY * 1000) + DD where: Factor Date Part Represented Represented by YYYY Year in Gregorian calendar Integer in the range 1,601 through 9,999 DD Day of the year Integer in the range 1 through 366 that is a valid day for the year specified by YYYY The returned value is an integer that is the number of days that the date represented by argument succeeds December 31, 1600, in the Gregorian calendar. Example 14-15. INTEGER-OF-DAY Function Code: DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION INTEGER-OF-DAY INTEGER-OF-DAY INTEGER-OF-DAY INTEGER-OF-DAY INTEGER-OF-DAY (1601001) (1601365) (1700341) (1634292) (1874289) Output: 00000001 00000365 00036500 00012345 00100000 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -23 Intrinsic Functions INTEGER-PART Function INTEGER-PART Function INTEGER-PART, an integer function, returns the integer part of its argument. FUNCTION INTEGER-PART ( ) argument VST434.vsd argument is a numeric argument. The returned value is determined as shown in this table: Value of argument Returned Value Zero Zero Positive Greatest integer less than or equal to the value of argument Negative Least integer greater than or equal to the value of argument Example 14-16. INTEGER-PART Function Code: DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION INTEGER-PART INTEGER-PART INTEGER-PART INTEGER-PART INTEGER-PART (-1.5) (-1) (0) (1) (1.5) Output: -1 -1 0 1 1 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -24 Intrinsic Functions LENGTH Function LENGTH Function LENGTH, an integer function, returns the length of its argument (the number of character positions it has, regardless of its current value). FUNCTION LENGTH ( argument ) VST435.vsd argument is a nonnumeric literal or data item of any class or category. The returned value is determined as shown in this table. It includes any implicit FILLER characters. argument Returned Value nonnumeric literal or elementary data item or data structure that does not contain a variable occurrence data item Length of the value of argument. data structure containing a variable occurrence data item Length of the current value of the data item specified in the DEPENDING phrase of the OCCURS clause for the variable occurrence data item. The current value is determined as if the data item were a sending data item. Example 14-17. LENGTH Function Code: 01 STUFF-1 PIC XXXX. 01 STUFF-2 PIC 9999. MOVE "AB" TO STUFF-1. MOVE 12 TO STUFF-2. DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION LENGTH(STUFF-1). STUFF-2. FUNCTION LENGTH(STUFF-2). FUNCTION LENGTH("ABC"). Output: 4 0012 4 3 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -25 Intrinsic Functions LOG Function LOG Function LOG, a numeric function, returns a value that approximates the logarithm to the base e (natural logarithm) of its argument. FUNCTION LOG ( argument ) VST436.vsd argument is a numeric argument greater than zero. The returned value is approximately the logarithm to the base e of the value of argument. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-18. LOG Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION LOG (1) DISPLAY A. MOVE FUNCTION LOG (10) DISPLAY A. MOVE FUNCTION LOG (100) DISPLAY A. MOVE FUNCTION LOG (1000) DISPLAY A. MOVE FUNCTION LOG (10000) DISPLAY A. TO A. TO A. TO A. TO A. TO A. Output: 0.00 2.30 4.60 6.90 9.21 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -26 Intrinsic Functions LOG10 Function LOG10 Function LOG10, a numeric function, returns a value that approximates the logarithm to the base 10 of its argument. FUNCTION LOG10 ( argument ) VST437.vsd argument is a numeric argument greater than zero. The returned value is approximately the logarithm to the base 10 of the value of argument. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-19. LOG10 Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION LOG10 DISPLAY A. MOVE FUNCTION LOG10 DISPLAY A. MOVE FUNCTION LOG10 DISPLAY A. MOVE FUNCTION LOG10 DISPLAY A. MOVE FUNCTION LOG10 DISPLAY A. (1) TO A. (10) TO A. (100) TO A. (1000) TO A. (10000) TO A. Output: 0.00 1.00 2.00 3.00 4.00 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -27 Intrinsic Functions LOWER-CASE Function LOWER-CASE Function LOWER-CASE, an alphanumeric function, returns a character-string that is the same as its argument, except that each uppercase letter is replaced by the corresponding lowercase letter. FUNCTION LOWER-CASE ( string ) VST438.vsd string is an alphabetic or alphanumeric string at least one character in length. The returned value is the same as the value of string, except that each uppercase letter is replaced by the corresponding lowercase letter. If the value of string contains no uppercase letters, or if an ALPHABET clause specifies a collating sequence that contains no lowercase letters, the returned value is the same as the value of string. Example 14-20. LOWER-CASE Function Code: DISPLAY FUNCTION LOWER-CASE ("HEWLETT-PACKARD COMPANY 2003") DISPLAY FUNCTION LOWER-CASE ("Hewlett-packard Company 2003") DISPLAY FUNCTION LOWER-CASE ("hewlett-packard company 2003") Output: hewlett-packard company 2003 hewlett-packard company 2003 hewlett-packard company 2003 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -28 Intrinsic Functions MAX Function MAX Function MAX is a function that returns the value of its maximum argument. Its type depends on the type of its arguments, as this table shows: Argument Type Function Type Alphabetic Alphanumeric Alphanumeric Alphanumeric Integer Integer Numeric (some can be integer) Numeric FUNCTION MAX ( ) argument VST439.vsd argument is an alphabetic, alphanumeric, integer, or numeric argument. If you specify more than one argument, they must all be of the same class. Integer and numeric arguments can be mixed, because integers are of the class numeric. argument can be an array; for example, FUNCTION MAX (ARRAY1(ALL)) returns the largest element of the array ARRAY1. The returned value is the argument with the greatest value (according to the rules for evaluating simple conditions). If the function type is alphanumeric, the size of the returned value is the same as that of the argument with the greatest value. If two arguments have the same greatest value, the value of the leftmost argument is returned. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -29 Intrinsic Functions MAX Function Example 14-21. MAX Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY. 05 PICTURE 9(1) VALUE 4. 05 PICTURE 9(1) VALUE 9. 05 PICTURE 9(1) VALUE 3. 05 PICTURE 9(1) VALUE 7. 05 PICTURE 9(1) VALUE 5 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9(1). 01 ALPHABETIC-ARRAY. 05 PICTURE X(5) VALUE "dog". 05 PICTURE X(5) VALUE "cat". 05 PICTURE X(5) VALUE "horse". 05 PICTURE X(5) VALUE "sheep". 05 PICTURE X(5) VALUE "goat". 01 ALPHA-ARRAY REDEFINES ALPHABETIC-ARRAY. 05 ALPHA OCCURS 5 TIMES PICTURE X(5). PROCEDURE ... DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DIVISION. FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION MAX MAX MAX MAX MAX (NUM(ALL)) (ALPHA(ALL)) (NUM(1) NUM(4)) (ALPHA(3) "bird" "fish") (3.4 5 6.2 9) Output: 9 sheep 7 horse 9.0 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -30 Intrinsic Functions MEAN Function MEAN Function MEAN, a numeric function, returns the arithmetic mean (average) of its arguments. FUNCTION MEAN ( argument ) VST440.vsd argument is a numeric argument. argument can be an array; for example, FUNCTION MEAN (ARRAY1(ALL)) returns the arithmetic mean of the elements of the array ARRAY1. The returned value is the arithmetic mean (average) of the argument series; that is n ∑ argument i =-1-----------------i-n where n is the number of arguments. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -31 Intrinsic Functions MEDIAN Function Example 14-22. MEAN Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY. 05 PICTURE 9(1) VALUE 4. 05 PICTURE 9(1) VALUE 9. 05 PICTURE 9(1) VALUE 3. 05 PICTURE 9(1) VALUE 7. 05 PICTURE 9(1) VALUE 5 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9(1). 01 A PICTURE S9V9. PROCEDURE DIVISION. MOVE FUNCTION MEAN (NUM(ALL)) TO A. DISPLAY A. MOVE FUNCTION MEAN (NUM(1) NUM(3) NUM(5)) TO A. DISPLAY A. MOVE FUNCTION MEAN (3.4 5 6.2 9) TO A. DISPLAY A. Output: 5.6 4.0 5.9 MEDIAN Function MEDIAN, a numeric function, returns the value that would be the middle value in a list formed by sorting its arguments numerically. FUNCTION MEDIAN ( argument ) VST441.vsd argument is a numeric argument. argument can be an array; for example, FUNCTION MEDIAN (ARRAY1(ALL)) returns the median element of the array ARRAY1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -32 Intrinsic Functions MEDIAN Function The returned value is the value that would be in the middle of the list if the arguments were sorted numerically (according to the rules for comparing simple conditions). If there are an odd number of arguments, at least half of them are less than or equal to the returned value, and at least half of them are greater than or equal to the returned value. If there are an even number of arguments, the returned value is the arithmetic mean of the two middle arguments. (For the definition of arithmetic mean, see MEAN Function). Example 14-23. MEDIAN Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY. 05 PICTURE 9(1) VALUE 4. 05 PICTURE 9(1) VALUE 9. 05 PICTURE 9(1) VALUE 3. 05 PICTURE 9(1) VALUE 7. 05 PICTURE 9(1) VALUE 5 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9(1). 01 A PICTURE S9V9. PROCEDURE DIVISION. MOVE FUNCTION MEDIAN DISPLAY A. MOVE FUNCTION MEDIAN DISPLAY A. MOVE FUNCTION MEDIAN DISPLAY A. MOVE FUNCTION MEDIAN DISPLAY A. (NUM(ALL)) TO A. (NUM(1) NUM(3) NUM(5)) TO A. (4 1 7 5 2 3 6) TO A. (4 1 6 5 2 3) TO A. Output: 5.0 4.0 4.0 3.5 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -33 Intrinsic Functions MIDRANGE Function MIDRANGE Function MIDRANGE, a numeric function, returns the arithmetic mean (average) of its minimum and maximum arguments. FUNCTION MIDRANGE ( argument ) VST442.vsd argument is a numeric argument. argument can be an array; for example, FUNCTION MIDRANGE (ARRAY1(ALL)) returns the arithmetic mean of the minimum and maximum elements of the array ARRAY1. The returned value is the arithmetic mean (average) of the least argument and the greatest argument (according to the rules for comparing simple conditions). Example 14-24. MIDRANGE Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY. 05 PICTURE 9(1) VALUE 4. 05 PICTURE 9(1) VALUE 9. 05 PICTURE 9(1) VALUE 3. 05 PICTURE 9(1) VALUE 7. 05 PICTURE 9(1) VALUE 5 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9(1). 01 A PICTURE S9V9. PROCEDURE DIVISION. MOVE FUNCTION MIDRANGE (NUM(ALL)) TO A. DISPLAY A. MOVE FUNCTION MIDRANGE (NUM(1) NUM(3) NUM(5)) TO A. DISPLAY A. MOVE FUNCTION MIDRANGE (8 1 3 6) TO A. DISPLAY A. Output: 6.0 4.0 4.5 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -34 Intrinsic Functions MIN Function MIN Function MIN is a function that returns the value of its minimum argument. Its type depends on the type of its arguments, as this table shows: Argument Type Function Type Alphabetic Alphanumeric Alphanumeric Alphanumeric Integer Integer Numeric (some can be integer) Numeric FUNCTION MIN ( ) argument VST443.vsd argument is an alphabetic, alphanumeric, integer, or numeric argument. If you specify more than one argument, they must all be of the same class. Integer and numeric arguments can be mixed, because integers are of the class numeric. argument can be an array; for example, FUNCTION MIN (ARRAY1(ALL)) returns the smallest element of the array ARRAY1. The returned value is the argument with the least value (according to the rules for evaluating simple conditions). If the function type is alphanumeric, the size of the returned value is the same as that of the argument with the least value. If two arguments have the same least value, the value of the leftmost argument is returned. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -35 Intrinsic Functions MIN Function Example 14-25. MIN Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY. 05 PICTURE 9(1) VALUE 4. 05 PICTURE 9(1) VALUE 9. 05 PICTURE 9(1) VALUE 3. 05 PICTURE 9(1) VALUE 7. 05 PICTURE 9(1) VALUE 5 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9(1). 01 ALPHABETIC-ARRAY. 05 PICTURE X(5) VALUE "dog". 05 PICTURE X(5) VALUE "cat". 05 PICTURE X(5) VALUE "horse". 05 PICTURE X(5) VALUE "sheep". 05 PICTURE X(5) VALUE "goat". 01 ALPHA-ARRAY REDEFINES ALPHABETIC-ARRAY. 05 ALPHA OCCURS 5 TIMES PICTURE X(5). PROCEDURE DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DIVISION. FUNCTION MIN FUNCTION MIN FUNCTION MIN FUNCTION MIN FUNCTION MIN (NUM(ALL)) (ALPHA(ALL)) (NUM(1) NUM(4)) (ALPHA(3) "bird" "fish") (3.4 5 6.2 9) Output: 3 cat 4 bird 3.4 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -36 Intrinsic Functions MOD Function MOD Function MOD, an integer function, returns the value that is argument-1 modulo argument-2. FUNCTION MOD ( argument-1 argument-2 ) VST444.vsd argument-1 is an integer. argument-2 is a nonzero integer. The returned value is argument-1 modulo argument-2, which is defined: argument-1 argument-1 – argument-2 × FUNCTION INTEGER --------------------- argument-2 Example 14-26. MOD Function Code: DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION MOD MOD MOD MOD (11 5) (-11 5) (11 -5) (-11 -5) Output: 00001 00004 -00004 -00001 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -37 Intrinsic Functions NUMVAL Function NUMVAL Function NUMVAL, a numeric function, returns the numeric value represented by its argument, which is a character-string. NUMVAL ignores leading and trailing spaces. FUNCTION ( NUMVAL ) string VST445.vsd string " sp " number + - sp sp number + - sp CR DB VST446.vsd sp is a string of zero or more space characters. number digits ns . ns digits . ns digits VST447.vsd If the program contains the DECIMAL POINT COMMA phrase in the SPECIALNAMES paragraph, use a comma instead of a decimal point in number. digits is a string of one to 18 digits. The total number of digits in string cannot exceed 18. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -38 Intrinsic Functions NUMVAL Function The returned value is the numeric value represented by string. The format of the value depends on the size of string. If the length of string is fewer than 10 characters, the equivalent PICTURE is S9(n)V9(n-1), where n is the number of characters. Any size greater than 9 characters results in an equivalent PICTURE of S9(19)V9(18). This is a special internal item that cannot be expressed by the user. Using it is inefficient, so it is best to avoid using a string that is longer than 9 characters. If the NUMVAL function is moved to an alphanumeric item, the results might not be what is expected because of the implied PICTURE described previously. For string sizes greater than 10, the result is changed to S9(18). Example 14-27. NUMVAL Function Code: DATA DIVISION WORKING-STORAGE SECTION. 01 A PICTURE S99V99. PROCEDURE DIVISION. MOVE FUNCTION NUMVAL DISPLAY A. MOVE FUNCTION NUMVAL DISPLAY A. MOVE FUNCTION NUMVAL DISPLAY A. MOVE FUNCTION NUMVAL DISPLAY A. MOVE FUNCTION NUMVAL DISPLAY A. MOVE FUNCTION NUMVAL DISPLAY A. ("35") TO A. ("35.") TO A. ("35.75") TO A. (".35") TO A. (" (" - 35.75 35.75 ") TO A. CR") TO A. Output: 35.00 35.00 35.75 00.35 -35.75 -35.75 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -39 Intrinsic Functions NUMVAL-C Function NUMVAL-C Function NUMVAL-C, a numeric function, returns the numeric value of a specified characterstring, ignoring any currency sign or commas preceding the decimal point. FUNCTION ( NUMVAL-C ) value-1 value-2 currency-sign VST448.vsd value-1 spaces + spaces number currency-sign spaces spaces VST450.vsd value-2 spaces currency-sign spaces number spaces + - spaces CR DB VST385.vsd spaces is a string of zero or more space characters. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -40 Intrinsic Functions NUMVAL-C Function currency-sign is a nonnumeric literal or alphanumeric data item; a string of one or two characters that specifies the currency sign. The default is the currency sign specified for the program. number digits ns digits ns ns . ns digits . ns digits VST451.vsd If the program contains the DECIMAL POINT COMMA phrase in the SPECIALNAMES paragraph, use a comma instead of a decimal point in number. digits is a string of one to 18 digits. The total number of digits in string cannot exceed 18. The returned value is the numeric value represented by string. The format of the value depends on the size of string. If the length of string is fewer than 10 characters, the equivalent PICTURE is S9(n)V9(n-1), where n is the number of characters. Any size greater than 9 characters results in an equivalent PICTURE of S9(19)V9(18). This is a special internal item that cannot be expressed by the user. Using it is inefficient, so it is best to avoid using a string that is longer than 9 characters. If the NUMVAL-C function is moved to an alphanumeric item, the results might not be what is expected because of the implied PICTURE described previously. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -41 Intrinsic Functions NUMVAL-C Function Example 14-28. NUMVAL-C Function Code: DATA DIVISION WORKING-STORAGE SECTION. 01 A PICTURE S99V99. PROCEDURE DIVISION. MOVE FUNCTION NUMVAL-C DISPLAY A. MOVE FUNCTION NUMVAL-C DISPLAY A. MOVE FUNCTION NUMVAL-C DISPLAY A. MOVE FUNCTION NUMVAL-C DISPLAY A. MOVE FUNCTION NUMVAL-C DISPLAY A. MOVE FUNCTION NUMVAL-C DISPLAY A. MOVE FUNCTION NUMVAL-C DISPLAY A. ("35") TO A. ("$35") TO A. ("35$") TO A. ("35.75") TO A. (".35") TO A. (" (" - 35.75 35.75 ") TO A. CR") TO A. Output: 35.00 35.00 35.00 35.75 00.35 -35.75 -35.75 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -42 Intrinsic Functions ORD Function ORD Function ORD, an integer function, returns the ordinal number of its argument in the program collating sequence. FUNCTION ( ORD argument ) VST452.vsd argument is a one-character alphabetic or alphanumeric argument. The returned value is the ordinal number of argument in the program collating sequence. It is at least one. Example 14-29. ORD Function Code: DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION ORD ORD ORD ORD ("A") ("b") ("3") ("%") Output: 066 099 052 038 ORD-MAX Function ORD-MAX, an integer function, returns the ordinal number of its maximum argument. FUNCTION ORD-MAX ( argument ) VST435.vsd argument is an alphabetic, alphanumeric, integer, or numeric argument. If you specify more than one argument, they must all be of the same class. Integer and numeric arguments can be mixed, because integers are of the class numeric. argument can be an array; for example, FUNCTION ORD-MAX (ARRAY1(ALL)) returns the ordinal number of the largest element of the array ARRAY1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -43 Intrinsic Functions ORD-MAX Function The returned value is the ordinal number of the argument with the greatest value (according to the rules for evaluating simple conditions). If more than one argument has the same greatest value, the returned value is the ordinal number of the leftmost argument with that value. The returned value is at least one. Example 14-30. ORD-MAX Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY. 05 PICTURE 9(1) VALUE 4. 05 PICTURE 9(1) VALUE 9. 05 PICTURE 9(1) VALUE 3. 05 PICTURE 9(1) VALUE 7. 05 PICTURE 9(1) VALUE 5 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9(1). 01 ALPHABETIC-ARRAY. 05 PICTURE X(5) VALUE "dog". 05 PICTURE X(5) VALUE "cat". 05 PICTURE X(5) VALUE "horse". 05 PICTURE X(5) VALUE "sheep". 05 PICTURE X(5) VALUE "goat". 01 ALPHA-ARRAY REDEFINES ALPHABETIC-ARRAY. 05 ALPHA OCCURS 5 TIMES PICTURE X(5). PROCEDURE DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DIVISION. FUNCTION ORD-MAX FUNCTION ORD-MAX FUNCTION ORD-MAX FUNCTION ORD-MAX FUNCTION ORD-MAX (NUM(ALL)) (ALPHA(ALL)) (NUM(1) NUM(4)) (ALPHA(3) "bird" "fish") (3.4 5 6.2 9) Output: 0000000002 0000000004 0000000002 0000000001 0000000004 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -44 Intrinsic Functions ORD-MIN Function ORD-MIN Function ORD-MIN, an integer function, returns the ordinal number of its minimum argument. FUNCTION ORD-MIN ( argument ) VST454.vsd argument is an alphabetic, alphanumeric, integer, or numeric argument. If you specify more than one argument, they must all be of the same class. Integer and numeric arguments can be mixed, because integers are of the class numeric. argument can be an array; for example, FUNCTION ORD-MIN (ARRAY1(ALL)) returns the ordinal number of the smallest element of the array ARRAY1. The returned value is the ordinal number of the argument with the least value (according to the rules for evaluating simple conditions). If more than one argument has the same least value, the returned value is the ordinal number of the leftmost argument with that value. The returned value is at least one. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -45 Intrinsic Functions ORD-MIN Function Example 14-31. ORD-MIN Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY. 05 PICTURE 9(1) VALUE 4. 05 PICTURE 9(1) VALUE 9. 05 PICTURE 9(1) VALUE 3. 05 PICTURE 9(1) VALUE 7. 05 PICTURE 9(1) VALUE 5 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9(1). 01 ALPHABETIC-ARRAY. 05 PICTURE X(5) VALUE "dog". 05 PICTURE X(5) VALUE "cat". 05 PICTURE X(5) VALUE "horse". 05 PICTURE X(5) VALUE "sheep". 05 PICTURE X(5) VALUE "goat". 01 ALPHA-ARRAY REDEFINES ALPHABETIC-ARRAY. 05 ALPHA OCCURS 5 TIMES PICTURE X(5). PROCEDURE DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY DIVISION. FUNCTION ORD-MIN FUNCTION ORD-MIN FUNCTION ORD-MIN FUNCTION ORD-MIN FUNCTION ORD-MIN (NUM(ALL)) (ALPHA(ALL)) (NUM(1) NUM(4)) (ALPHA(3) "bird" "fish") (3.4 5 6.2 9) Output: 0000000003 0000000002 0000000001 0000000002 0000000001 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -46 Intrinsic Functions PRESENT-VALUE Function PRESENT-VALUE Function PRESENT-VALUE, a numeric function, returns a value that approximates the present value of a specified series of future period-end amounts at a specified discount rate. FUNCTION ( PRESENT-VALUE discount-rate period-end-amount ) VST455.vsd discount-rate is a numeric argument whose value is greater than -1. period-end-amount is a numeric argument. period-end-amount can be an array; for example, FUNCTION PRESENT-VALUE (DISCOUNT-RATE ARRAY1(ALL)) uses the elements of the array ARRAY1 as a series of numeric arguments. The returned value is approximately n period-end-amount i ∑ ----------------------------------i ( 1 + discount-rate ) i=1 where n is the number of period-end-amount s. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -47 Intrinsic Functions PRESENT-VALUE Function Example 14-32. PRESENT-VALUE Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY. 05 PICTURE 9V99 VALUE 0.05. 05 PICTURE 9V99 VALUE 1.15. 05 PICTURE 9V99 VALUE 2.50. 05 PICTURE 9V99 VALUE 3.75. 05 PICTURE 9V99 VALUE 4.55. 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 N OCCURS 5 TIMES PICTURE 9V99. 01 A PICTURE S99V99. PROCEDURE DIVISION. MOVE FUNCTION PRESENT-VALUE DISPLAY A. MOVE FUNCTION PRESENT-VALUE DISPLAY A. MOVE FUNCTION PRESENT-VALUE DISPLAY A. MOVE FUNCTION PRESENT-VALUE DISPLAY A. MOVE FUNCTION PRESENT-VALUE DISPLAY A. (0 NUM(ALL) TO A) TO A (1 NUM(ALL) TO A) TO A (2.5 NUM(ALL) TO A) TO A (0 3) TO A (1.5 3.6 7.8 4.9) TO A Output: 12.00 01.00 00.20 03.00 03.00 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -48 Intrinsic Functions RANDOM Function RANDOM Function RANDOM, a numeric function, returns a pseudorandom number from a rectangular distribution. FUNCTION RANDOM ( argument ) VST456.vsd argument is zero or a positive integer. The first time a run unit calls RANDOM, RANDOM generates a series of pseudorandom numbers and returns the first number in the series. If argument is specified, RANDOM uses the value of argument as the seed; if not, it uses the default seed, one. Each subsequent time that the run unit calls RANDOM without specifying argument, RANDOM returns the next pseudorandom number in the series. If the run unit calls RANDOM again and specifies argument, RANDOM generates a new series of pseudorandom numbers and returns the first number in the new series. The same value of argument always generates the same sequence of pseudorandom numbers. The returned value is always greater than or equal to 0 and less than 1. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-33. RANDOM Function Code: DISPLAY DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION FUNCTION RANDOM RANDOM RANDOM RANDOM RANDOM (0) (15) (253) (4067) (32767) Output: 0.000000000 0.707956564 0.007660018 0.886242720 0.792491424 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -49 Intrinsic Functions RANGE Function RANGE Function RANGE is a function that returns the difference between its maximum and minimum arguments. Its type depends on the type of its arguments, as this table shows: Argument Type Function Type Integer Integer Numeric (some can be integer) Numeric FUNCTION RANGE ( argument ) VST457.vsd argument is an integer or numeric argument. Integer and numeric arguments can be mixed, because integers are of the class numeric. argument can be an array; for example, FUNCTION RANGE (ARRAY1(ALL)) returns the difference between the largest and smallest elements of the array ARRAY1. The returned value is the value of the greatest argument minus the value of the least argument (where the greatest and least arguments are determined according to the rules for evaluating simple conditions). If two arguments have the same greatest value, the leftmost of the two is considered the greatest. If two arguments have the same least value, the leftmost of the two is considered the least. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -50 Intrinsic Functions RANGE Function Example 14-34. RANGE Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY. 05 PICTURE 9V99 VALUE 0.05. 05 PICTURE 9V99 VALUE 1.15. 05 PICTURE 9V99 VALUE 2.50. 05 PICTURE 9V99 VALUE 3.75. 05 PICTURE 9V99 VALUE 4.55. 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9V99. PROCEDURE DISPLAY DISPLAY DISPLAY DIVISION. FUNCTION RANGE (NUM(ALL)) FUNCTION RANGE (9 2 5 3.5) FUNCTION RANGE (1.5 3.6 7.8 4.9) Output: 4.50 7.0 6.3 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -51 Intrinsic Functions REM Function REM Function REM, a numeric function, returns the remainder that results from dividing its first argument by its second argument. FUNCTION REM ( dividend divisor ) VST458.vsd dividend is a numeric argument. divisor is a nonzero numeric argument. If ARRAY1 has only two elements, the first of which satisfies the requirements for dividend and the second of which satisfies the requirements of divisor, then FUNCTION REM (ARRAY1(ALL)) returns the remainder that results from dividing ARRAY1(1) by ARRAY1(2). The returned value is the remainder of dividend divided by divisor, which is defined: dividend - (divisor * FUNCTION INTEGER-PART (dividend / divisor)) Example 14-35. REM Function Code: DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION REM REM REM REM (11 5) (-11 5) (11 -5) (-11 -5) Output: 01 -01 01 -01 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -52 Intrinsic Functions REVERSE Function REVERSE Function REVERSE, an alphanumeric function, returns a string that is the same as its argument, except that the characters are in reverse order. FUNCTION REVERSE ( argument ) VST459.vsd argument is an alphabetic or alphanumeric argument at least one character in length. The returned value is the same as argument, except that the characters are in reverse order. That is, if argument has n characters, then the i th character of argument is the (n - i +1)th character of the returned value. Example 14-36. REVERSE Function Code: DISPLAY DISPLAY DISPLAY DISPLAY FUNCTION FUNCTION FUNCTION FUNCTION REVERSE REVERSE REVERSE REVERSE ("A") ("1234567") ("stressed") ("ABC 123") Output: A 7654321 desserts 321 CBA HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -53 Intrinsic Functions SIN Function SIN Function SIN, a numeric function, returns a value that approximates the sine of the angle or arc (in radians) specified by its argument. FUNCTION SIN ( argument ) VST460.vsd argument is a numeric argument. The returned value approximates the sine of the value of argument. It is a floatingpoint number in the range -1 to +1. It has no implied decimal point and is precise to approximately 14 digits. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-37. SIN Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION SIN DISPLAY A. MOVE FUNCTION SIN DISPLAY A. MOVE FUNCTION SIN DISPLAY A. MOVE FUNCTION SIN DISPLAY A. MOVE FUNCTION SIN DISPLAY A. (-10) TO A. (0) TO A. (.25) TO A. (15.5) TO A. (45) TO A. Output: 0.54 0.00 0.24 0.20 0.85 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -54 Intrinsic Functions SQRT Function SQRT Function SQRT, a numeric function, returns a value that approximates the square root of its argument. FUNCTION SQRT ( argument ) VST461.vsd argument is a numeric argument whose value is zero or positive. The returned value is approximately: argument Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-38. SQRT Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION SQRT DISPLAY A. MOVE FUNCTION SQRT DISPLAY A. MOVE FUNCTION SQRT DISPLAY A. MOVE FUNCTION SQRT DISPLAY A. MOVE FUNCTION SQRT DISPLAY A. (0) TO A. (25) TO A. (100) TO A. (47) TO A. (7.923) TO A. Output: 00.000 05.000 10.000 06.855 02.814 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -55 Intrinsic Functions STANDARD-DEVIATION Function STANDARD-DEVIATION Function STANDARD-DEVIATION, a numeric function, returns a value that approximates the standard deviation of its arguments. FUNCTION ( STANDARD-DEVIATION argument ) VST462.vsd argument is a numeric argument. argument can be an array; for example, FUNCTION STANDARD-DEVIATION (ARRAY1(ALL)) returns a value that approximates the standard deviation of the elements of the array ARRAY1. The returned value is the approximation of the standard deviation of the argument series. If there is only one argument, or if every argument is a variable occurrence data item and the total number of occurrences for all of them is one, the returned value is zero; otherwise, the returned value is approximately n ∑ ( argumenti – FUNCTION MEAN (argument 1,…, argumentn) ) 2 i =1 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- n where n is the number of arguments. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -56 Intrinsic Functions STANDARD-DEVIATION Function Example 14-39. STANDARD-DEVIATION Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY 05 PICTURE 9V99 VALUE 0.05. 05 PICTURE 9V99 VALUE 1.15. 05 PICTURE 9V99 VALUE 2.50. 05 PICTURE 9V99 VALUE 3.75. 05 PICTURE 9V99 VALUE 4.55. 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9V99. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION STANDARD-DEVIATION (NUM(ALL)) TO A. DISPLAY A. MOVE FUNCTION STANDARD-DEVIATION (9 2 5 3.5) TO A. DISPLAY A. MOVE FUNCTION STANDARD-DEVIATION (1.5 3.6 7.8 4.9) TO A. DISPLAY A. Output: 1.64 2.60 2.28 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -57 Intrinsic Functions SUM Function SUM Function SUM is a function that returns the sum of its arguments. Its type depends on the type of its arguments, as this table shows: Argument Type Function Type Integer Integer Numeric (some can be integer) Numeric FUNCTION SUM ( argument ) VST463.vsd argument is an integer or numeric argument. argument can be an array; for example, FUNCTION SUM (ARRAY1(ALL)) returns the sum of the elements of the array ARRAY1. The returned value is n ∑ argumenti i=1 where n is the number of arguments. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -58 Intrinsic Functions SUM Function Example 14-40. SUM Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY 05 PICTURE 9V99 VALUE 0.05. 05 PICTURE 9V99 VALUE 1.15. 05 PICTURE 9V99 VALUE 2.50. 05 PICTURE 9V99 VALUE 3.75. 05 PICTURE 9V99 VALUE 4.55. 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9V99. PROCEDURE DISPLAY DISPLAY DISPLAY DIVISION. FUNCTION SUM (NUM(ALL)) FUNCTION SUM (9 2 5 3) FUNCTION SUM (1.5 3.6 7.8 4.9) Output: 012.00 19 17.8 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -59 Intrinsic Functions TAN Function TAN Function TAN, a numeric function, returns a value that approximates the tangent of the angle or arc (in radians) specified by its argument. FUNCTION TAN ( argument ) VST464.vsd argument is a numeric argument. The returned value approximates the tangent of the value of argument. It is a floatingpoint number with no implied decimal point, precise to approximately 14 digits. Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. Example 14-41. TAN Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE S9V99. PROCEDURE DIVISION. MOVE FUNCTION ATAN DISPLAY A. MOVE FUNCTION ATAN DISPLAY A. MOVE FUNCTION ATAN DISPLAY A. MOVE FUNCTION ATAN DISPLAY A. MOVE FUNCTION ATAN DISPLAY A. (-10) TO A. (0) TO A. (.25) TO A. (15.5) TO A. (45) TO A. Output: -0.64 0.00 0.25 -0.21 1.61 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -60 Intrinsic Functions UPPER-CASE Function UPPER-CASE Function UPPER-CASE, an alphanumeric function, returns a character-string that is the same as its argument, except that each lowercase letter is replaced by the corresponding uppercase letter. FUNCTION UPPER-CASE ( string ) VST465.vsd string is an alphabetic or alphanumeric string at least one character in length. The returned value is the same as the value of string, except that each lowercase letter is replaced by the corresponding uppercase letter. If the value of string contains no lowercase letters, or if the ALPHABET clause specifies a collating sequence that contains no uppercase letters, the returned value is the same as the value of string. Example 14-42. UPPER-CASE Function Code: DISPLAY FUNCTION UPPER-CASE ("HEWLETT-PACKARD COMPANY 2003") DISPLAY FUNCTION UPPER-CASE ("Hewlett-packard Company 2003") DISPLAY FUNCTION UPPER-CASE ("hewlett-packard company 2003") Output: HEWLETT-PACKARD COMPANY 2003 HEWLETT-PACKARD COMPANY 2003 HEWLETT-PACKARD COMPANY 2003 HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -61 Intrinsic Functions VARIANCE Function VARIANCE Function VARIANCE, a numeric function, returns a value that approximates the variance of its arguments. FUNCTION VARIANCE ( argument ) VST466.vsd argument is a numeric argument. argument can be an array; for example, FUNCTION VARIANCE (ARRAY1(ALL)) returns a value that approximates the variance of the elements of the array ARRAY1. The returned value is the approximation of the variance of the argument series. If there is only one argument, or if every argument is a variable occurrence data item and the total number of occurrences for all of them is one, the returned value is zero; otherwise, the returned value is the square of the standard deviation of the argument series; that is: 2 n ∑ ( argumenti – FUNCTION MEAN (argument 1,…, argument n) ) 2 i-=-1------------------------------------------------------------------------------------------------n HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -62 Intrinsic Functions WHEN-COMPILED Function Example 14-43. VARIANCE Function Code: DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMERIC-ARRAY 05 PICTURE 9V99 VALUE 0.05. 05 PICTURE 9V99 VALUE 1.15. 05 PICTURE 9V99 VALUE 2.50. 05 PICTURE 9V99 VALUE 3.75. 05 PICTURE 9V99 VALUE 4.55. 01 NUM-ARRAY REDEFINES NUMERIC-ARRAY. 05 NUM OCCURS 5 TIMES PICTURE 9V99. 01 A PICTURE 9V99. PROCEDURE DIVISION. MOVE FUNCTION VARIANCE DISPLAY A.. MOVE FUNCTION VARIANCE DISPLAY A. MOVE FUNCTION VARIANCE DISPLAY A. MOVE FUNCTION VARIANCE DISPLAY A. (NUM(ALL)) TO A (9 2 5 3) TO A. (1.5 3.6 7.8 4.9) TO A. (5) TO A. Output: 2.70 7.18 5.21 0.00 WHEN-COMPILED Function WHEN-COMPILED, an alphanumeric function, returns a 21-character string that represents the date and time the program was compiled, according to the system on which the program was compiled. FUNCTION WHEN-COMPILED VST467.vsd The returned value is the date and time of compilation of the source program that calls the WHEN-COMPILED function. If the program is a contained program, the returned value is the date and time of the separately compiled program that contains it. HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -63 Intrinsic Functions WHEN-COMPILED Function The returned value represents the current date this way (where character position 1 is the leftmost character position): Character Positions Date Part Represented Represented by 1-4 Year in Gregorian calendar Four digits 5-6 Month of the year Two digits in the range 01 through 12 7-8 Day of the month Two digits in the range 01 through 31 9-10 Hours past midnight Two digits in the range 00 through 23 11-12 Minutes past the hour Two digits in the range 00 through 59 13-14 Seconds past the minute Two digits in the range 00 through 59 15-16 Hundredths of seconds past the second Two digits in the range 00 through 99 17 Relationship to Greenwich mean time Minus (-) if the reported time is behind Greenwich mean time, plus (+) if it is the same as or ahead of Greenwich mean time 18-19 Hours behind or ahead of Greenwich mean time If character position 17 is minus (-), two digits in the range 00 through 12; if character position 17 is plus (+), two digits in the range 00 through 13 20-21 Additional minutes from Greenwich mean time Two digits in the range 00 through 59 The returned value matches the compilation time and date on the listing and object code files (if they have it), but the representation and precision may differ. Example 14-44. WHEN-COMPILED Function Code: DISPLAY FUNCTION WHEN-COMPILED Output: 1997041516104953-0700 The date in Example 14-44 is April 15, 1997 (19970415). The time is 16:10:49.53 or 4:10:49.53 PM (16104953), which is 7 hours behind Greenwich mean time (-0700). HP COBOL Manual for TNS and TNS/R Programs —522555-006 14 -64 15 Debugging Tools This section briefly describes the HP debugging tools and refers you to appropriate sources for more information. Topics: • • • • Standard COBOL Debugging Tools Run-Time Debuggers CROSSREF Utility Program FIXERRS Macro Standard COBOL Debugging Tools COBOL offers two batch-oriented debugging tools: Tool Applies to ... Debugging Lines Individual source program lines Debugging Declaratives Sections to be called when your program calls a particular procedure or calls any procedure Debugging lines and debugging declaratives are compiled only if the source program includes a DEBUGGING MODE clause (see SOURCE-COMPUTER Paragraph); otherwise, they are handled as comments. Note. The code that the compiler generates when it compiles debugging lines and debugging declaratives is not the same as the code that it generates when it ignores them. The additional code that the compiler generates for the debugging lines and debugging declaratives can alter the alignment of data items and cause the program to behave differently. Debugging Lines You can put debugging lines anywhere in a source program. You usually use them to report values of data items at strategic points in the program. A debugging line has the letter D or d in the indicator area (column 1 in Tandem reference format, column 7 in ANSI reference format). If a debugging line contains a COPY statement, every line that the COPY statement introduces inherits the D or d in its indicator column. HP COBOL Manual for TNS and TNS/R Programs —522555-006 15- 1 Debugging Tools Standard COBOL Debugging Tools Debugging Declaratives Debugging declaratives are sections in the Declaratives Portion of the Procedure Division. A debugging declarative consists of a USE DEBUGGING statement followed by a procedure to be executed under the circumstances specified in the USE DEBUGGING statement. Note. The 1985 COBOL standard classifies USE DEBUGGING as obsolete, so you are advised not to use it, even in TNS HP COBOL programs. The NMCOBOL compiler does not recognize it. The circumstances under which a procedure in a debugging declarative can be called are: • • A particular procedure call Any procedure call Debugging declaratives are only executed if you execute a PARAM DEBUG ON command before executing your program (see Enabling Debugging Declaratives). When a program uses debugging declaratives, it can access the special register DEBUG-ITEM. Whenever control passes to a debugging declarative, the contents of DEBUG-ITEM reflect the status of the item that caused the declarative to be called. DEBUG-ITEM is a data structure that is defined as in Figure 15-1. Figure 15-1. Definition of the DEBUG-ITEM Special Register 01 DEBUG-ITEM. 05 DEBUG-LINE 05 FILLER 05 DEBUG-NAME 05 FILLER 05 DEBUG-SUB-1 PIC PIC PIC PIC PIC 05 05 FILLER DEBUG-SUB-2 PIC PIC 05 05 FILLER DEBUG-SUB-3 PIC PIC 05 05 FILLER DEBUG-CONTENTS PIC PIC X(6). X VALUE SPACE. X(30). X VALUE SPACE. S9999 SIGN IS LEADING SEPARATE CHARACTER. X VALUE SPACE. S9999 SIGN IS LEADING SEPARATE CHARACTER. X VALUE SPACE. S9999 SIGN IS LEADING SEPARATE CHARACTER. X VALUE SPACE. X(n). HP COBOL Manual for TNS and TNS/R Programs —522555-006 15- 2 Debugging Tools Standard COBOL Debugging Tools The contents of the elementary items within DEBUG-ITEM are: Elementary Item Contents DEBUG-LINE Number of source line that called the procedure being traced DEBUG-NAME First 30 characters of the name of the called procedure (including any section-name qualifier if the procedure is a paragraph) DEBUG-SUB-1 DEBUG-SUB-2 DEBUG-SUB-3 Not used DEBUG-CONTENTS Nonnumeric string varying in size and value (see next table) The contents of DEBUG-CONTENTS depends on the nature of the called procedure: Contents of DEBUG-CONTENTS The called procedure is ... START PROGRAM The first procedure in the program A procedure name The destination in an ALTER statement Spaces The destination in a GO TO statement PERFORM LOOP In a PERFORM loop SORT INPUT In a SORT input procedure SORT OUTPUT In a SORT output procedure USE PROCEDURE In a USE procedure FALL THROUGH Being executed as a result of fall-through from the previous procedure Example 15-1. Use of the DEBUG-ITEM Special Register ... ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP WITH DEBUGGING MODE. ... PROCEDURE DIVISION. DECLARATIVES. TRACE-PROGRAM SECTION. USE FOR DEBUGGING ON ALL PROCEDURES. DISPLAY-DEBUG-ITEM. DISPLAY DEBUG-ITEM. END DECLARATIVES. BEGIN-PROCESSING. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 15- 3 Debugging Tools Run-Time Debuggers Run-Time Debuggers The HP run-time debuggers are: Debugger For PIC For Non-PIC Visual Inspect * Yes Yes Inspect No Yes Debug No Yes * PC-based Except for Debug, the HP run-time debuggers are interactive, and symbolic. If you compile your program with the SYMBOLS directive (described in SYMBOLS and NOSYMBOLS), the symbolic debuggers allow you to debug the program using the names you assigned to the procedures and data items of the source program, rather than the addresses that the compiler and the Binder or linker ultimately assigned to them. If you do not compile your program with the SYMBOLS directive, you can use only the low-level commands of a symbolic debugger. Note. When you have debugged the program, recompile it without the SYMBOLS directive to decrease the size of the object file and decrease program compilation time. Any mechanism that calls the debugging facility calls the selected run-time debugger. Examples of such mechanisms are: • • • The RUND command An explicit call to the Debug debugger by the process A command interpreter DEBUG command Topics: • • • • Visual Inspect Inspect Debug Debugger Selection Visual Inspect • • • • • The most powerful of the HP debuggers For PIC and non-PIC programs Symbolic Interactive PC-based For more information, see: • • Debugging Visual Inspect’s online help HP COBOL Manual for TNS and TNS/R Programs —522555-006 15- 4 Debugging Tools Inspect Inspect • • • • • For non-PIC programs Symbolic Interactive Its LOW command allows you to reach machine code (the Inspect debugger in low-level mode is similar to the Debug debugger but more convenient) Handles TNS and native HP COBOL programs differently—see Using the Inspect and Visual Inspect Debuggers For more information, see the Inspect Manual. Debug • • • Precursor to the Inspect debugger For non-PIC programs Low-level—you must use the addresses, rather than the names, of procedures and data items To obtain the addresses, you must compile your program with these directives: Compiler Directives References COBOL85 ICODE IICODE and NOICODE LMAP LMAP and NOLMAP MAP MAP and NOMAP INNERLIST INNERLIST and NOINNERLIST MAP MAP and NOMAP NMCOBOL This is what each directive lists, in the order the information appears in the listing: Directive Information Provided ICODE For each source statement: • • Instruction codes generated Code block relative address An asterisk marks the beginning of each source statement. INNERLIST Immediately after each source statement: Generated machine instructions in mnemonic form LMAP Base addresses of code and data blocks (located in column headed “BASE”) MAP For each paragraph and section header: Code block relative address For each data item: Summary of storage attributes (including data block relative address HP COBOL Manual for TNS and TNS/R Programs —522555-006 15- 5 Debugging Tools Debugger Selection More information: Topic Source Debug Debug Manual Load map listings Binder Manual Debugger Selection Figure 15-2. Debugger Selection for a TNS or Non-PIC Native Process Start INSPECT attribute on? No Yes Visual Inspect session? Yes Select Visual Inspect No Inspect available? No Yes Select Inspect Select Debug End VST195.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 15- 6 Debugging Tools Debugger Selection Figure 15-3. Debugger Selection for a PIC Native Process Start INSPECT attribute on? No Yes Visual Inspect session? No Yes Select Visual Inspect Select Debug End VST024.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 15- 7 Debugging Tools CROSSREF Utility Program Regarding Figure 15-3 and Figure 15-3: • • You can turn on the INSPECT attribute in any of these ways: ° Compile the program without a NOINSPECT directive (described in INSPECT and NOINSPECT). ° Compile the program with a SAVEABEND directive (described in SAVEABEND and NOSAVEABEND). ° ° Set the INSPECT attribute in the Binder or linker. ° Specify INSPECT ON as a run option in the RUN command that initiates the process. Use the PARAM INSPECT ON command in the command interpreter environment before running the process Visual Inspect is available if you established a connection to it before the process entered debugging mode. CROSSREF Utility Program Note. This topic applies only to the COBOL85 compiler. You cannot use the CROSSREF utility program with the NMCOBOL compiler, because the NMCOBOL compiler does not produce a cross-reference listing. If you need a cross-reference listing for a native HP COBOL program, use the noft utility with the XREFPROC flag (see the nld Manual). The CROSSREF utility, with the help of the COBOL85 compiler, produces a crossreference listing of selected types of identifiers (including literals), showing where they occur in a program and how the program uses them. The CROSSREF utility is interactive, and is more efficient and flexible than the CROSSREF directive, which also produces a cross-reference listing. The CROSSREF directive produces one cross-reference listing for each program unit in a source file. The CROSSREF utility allows you to generate a listing of the identifiers from one or more program units. Both the CROSSREF directive and the CROSSREF utility allow you to restrict the types of identifiers to be reported, but only the CROSSREF utility allows you to explicitly include and exclude individual data names. Topics: • • • Running the CROSSREF Utility Specifying Directives and a Default COPY Library Specifying Certain Identifier Types Only For complete information about the CROSSREF utility, see the CROSSREF Manual. For information about the CROSSREF directive, see CROSSREF and NOCROSSREF. HP COBOL Manual for TNS and TNS/R Programs —522555-006 15- 8 Debugging Tools CROSSREF Utility Program Running the CROSSREF Utility You can run the CROSSREF utility interactively or with an OBEY command file. The command to run the CROSSREF utility interactively is: CROSSREF The command to run the CROSSREF utility with an OBEY command file (named XREFCMDS in this example) is: CROSSREF /IN XREFCMDS/ This explanation assumes that you are running CROSSREF interactively. If you run CROSSREF with an OBEY command file, put the CROSSREF commands in that file. The CROSSREF prompt is an ampersand (&). Example 15-2 creates a print file ($S.#CROS) containing a cross-reference listing of the program in Example 31-13. The SET LANGUAGE command informs CROSSREF that it is cross-referencing an HP COBOL source file. The SCAN command directs CROSSREF to collect information about all identifiers (except literals, which, by default, are not recorded). The GENERATE command directs CROSSREF to format the information collected and put it in the file $S.#CROS. The EXIT command ends the CROSSREF session. Example 15-2. CROSSREF Utility Program CROSSREF - CROSS-REFERENCE PROGRAM - T9622D20 - (8JUN92) ... &SET LANGUAGE COBOL85 &SCAN PROBE &GENERATE /OUT $S.#CROS/ &EXIT Specifying Directives and a Default COPY Library Because CROSSREF uses the COBOL85 compiler to collect the identifier information, you might need to pass directives and the name of a default COPY library from CROSSREF to the compiler. (The default COPY library is for COPY statements that do not specify file names.) In Example 15-3, the SET LIBRARY MYLIB command sets the default COPY library name to MYLIB (it would have been COPYLIB otherwise), and the SET DIRECTIVES “ANSI;SETTOG 1” command sets the ANSI formatting directive and a conditional compilation toggle. HP COBOL Manual for TNS and TNS/R Programs —522555-006 15- 9 Debugging Tools FIXERRS Macro Example 15-3. Setting the Default COPY Library CROSSREF - CROSS-REFERENCE PROGRAM - T9622D20 - (8JUN92) ... &SET LANGUAGE COBOL85 &SET LIBRARY MYLIB &SET DIRECTIVES "ANSI;SETTOG 1" &SCAN PROBE &GENERATE /OUT $S.#CROS/ &EXIT Specifying Certain Identifier Types Only You can instruct CROSSREF to collect information about only certain types of identifiers. This example instructs CROSSREF to report only identifiers of conditions and procedure (section and paragraph) names: CROSSREF - CROSS-REFERENCE PROGRAM - T9622D20 - (8JUN92) ... &SET LANGUAGE COBOL85 &SET CLASS CONDITIONS, PROGLABELS &SCAN PROBE &GENERATE /OUT $S.#CROS/ &EXIT FIXERRS Macro FIXERRS is a TACL macro that helps you find and fix syntax errors in your source file. To use the FIXERRS TACL macro to fix errors in a source file, you must compile your program with the directive ERRORFILE. You can then use FIXERRS with the errorlogging file produced by that directive. The FIXERRS TACL macro starts a two-window TEDIT session and displays an error message on the top line of the screen with the corresponding source text in the remaining lines. When you start FIXERRS, the cursor is positioned at the first error in the source text. To start FIXERRS enter: FIXERRS error-file ; tedit-command VST372.vsd error-file is the name of the error file produced by the compiler. This file has a file code of 106. HP COBOL Manual for TNS and TNS/R Programs —522555-006 15 -10 Debugging Tools FIXERRS Macro tedit-command is the TEDIT command that you want to execute at the start of the FIXERRS session. You can move from error to error using the NEXTERR and PREVERR commands on the TEDIT command line. NEXTERR displays the error following the currently displayed error; PREVERR displays the error preceding the currently displayed error. When you enter PREVERR at the beginning of the error file or NEXTERR at the end of the error file, FIXERRS displays the message: There are no more errors When you enter PREVERR after you have corrected errors in the file, the compiler positions you at the line and column on which the error was originally reported. This line and column number might be invalid after you correct the error. HP COBOL Manual for TNS and TNS/R Programs —522555-006 15 -11 Debugging Tools FIXERRS Macro HP COBOL Manual for TNS and TNS/R Programs —522555-006 15 -12 16 ANSI Reference Format In ANSI reference format, each line has 80 characters (columns). Five margins divide each line into five areas. Figure 16-1. ANSI Reference Format Margin: L Column: C 1 2 3 4 A 5 6 7 Sequence Number Area B 8 R 9 10 11 12 ... 72 73 ... 80 Area A Indicator Field Area B Identification Field Line VST524.vsd To ensure that each line has 80 characters, the COBOL compiler truncates lines that are too long and space-pads lines that are too short. The topics of this section explain the five areas that Figure 16-1 shows, which are: • • • • • Sequence Number Area Indicator Area Area A Area B Identification Field Sequence Number Area The Sequence Number Area begins at Margin L and uses columns 1 through 6. It can be empty, or it can contain a line number (up to six digits) or a line label (a combination of letters and numbers). No sequence number area exists for compiler directive lines. HP COBOL Manual for TNS and TNS/R Programs —522555-006 16- 1 ANSI Reference Format Indicator Area Indicator Area The indicator area begins at Margin C and uses only column 7. It can be empty, or it can contain a single character that describes the type of information on the line. Table 16-1. Valid Indicator Area Characters (ANSI Reference Format) Valid Character Character Name Indicates that the line is a … ? Question mark Compiler Directive * Asterisk Ordinary Comment / Slash Comment for Top of Page D Uppercase D Debugging Line d Lowercase d Debugging Line - Hyphen Continuation Line Compiler Directive A compiler directive has a question mark (?) in the indicator area. If the question mark is in column 1 instead of column 7, the compiler treats the line as if it begins with the indicator area. A compiler directive is an instruction to the COBOL compiler, and a compiler directive line has no sequence number area. (For more information on compiler directives, see Compiler Directives.) Ordinary Comment An ordinary comment has an asterisk (*) in the indicator area. A comment can appear anywhere in a program. The compiler ignores it. Comment for Top of Page A comment to be printed at the top of the next page has a slash (/) in the indicator area. Like an ordinary comment, this comment can appear anywhere in a program. The compiler advances to the top of the next page and prints the comment at the top of that page. Debugging Line A debugging line has D or d in the indicator area. If you run the program with DEBUGGING MODE, the line is part of the program; otherwise, the line is a comment. A debugging line cannot contain embedded SQL/MP or SQL/MX statements. For information on DEBUGGING MODE, see SOURCE-COMPUTER Paragraph. HP COBOL Manual for TNS and TNS/R Programs —522555-006 16- 2 ANSI Reference Format Continuation Line Continuation Line A continuation line has a hyphen (-) in the indicator area. It is a continuation of the previous line. Always leave area A of a continuation line blank. You can continue any word or literal. If you continue a numeric literal, a reserved word, or a user-defined word, the compiler ignores the trailing spaces of the previous line and initial spaces of the continuation line. The ANSI rules for continuing a nonnumeric literal are: • • The nonnumeric literal contains all trailing spaces present in area B (through column 72) in the previous line. The first character in area B of the continuation line that is not a space must be a quotation mark. The continuation begins with the character immediately following that quotation mark. Example 16-1. Continuation of Nonnumeric Literal in ANSI Format ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 DISPLAY "THIS IS AN EXAMPLE OF CONTINUING A LITERAL IN ANSI S "TANDARD FORMAT." The ANSI rules for continuing a national literal are: • • • The national literal contains all trailing spaces present in area B in the previous line. The first character in area B of the continuation line that is not a space must be an N or n followed by a quotation mark. The N or n must be in an odd-numbered column. The continuation begins with the character immediately following the quotation mark. The literal string must end on the previous line before the internal character count (the number of bytes) reaches 73. If you are counting the national characters as you type them, remember that each national character represents two bytes internally. The number of characters allowed on the line depends on the column in which the character-string begins. It might take a few compilations before you have the literal string divided properly over multiple lines. HP COBOL Manual for TNS and TNS/R Programs —522555-006 16- 3 ANSI Reference Format Area A Area A Area A begins at Margin A and uses columns 8 through 11. These must begin in area A: • • • • Division names Section headers Paragraph headers These level indicators and level numbers for the Data Division: ° ° ° FD (file descriptions) SD (sort-merge file descriptions) Level-numbers 01 and 77 Level-numbers 02 through 49, 66, and 88 can begin in either area A or area B. Area B Area B begins at Margin B and uses columns 12 through 72. Sentences within a paragraph must begin in area B. Level-numbers 02 through 49, 66, and 88 can begin in either area A or area B. Identification Field The identification field begins at Margin R and uses columns 73 through 80. The identification field can contain any ASCII characters. The compiler treats it as a comment. HP COBOL Manual for TNS and TNS/R Programs —522555-006 16- 4 17 HP Extensions to ISO COBOL This section lists the HP extensions to ISO/ANSI COBOL, grouping them according to the sections of this manual that explain them; that is: • • • • • • Source Program Organization and Format Language Elements Data Fundamentals Environment Division Data Division Procedure Division Verbs These HP extensions are explained in other sections, and are not repeated in this section: • • • HP Reserved Words Section 18, HP COBOL CRE Support Section 48, Run-Time Diagnostic Messages All Compiler Directives are HP extensions to ISO COBOL. HP extensions for using SQL/MP with HP COBOL are explained in the SQL/MP Programming Manual for COBOL. HP extensions for using SQL/MX with HP COBOL are explained in the SQL/MX Programming Manual for C and COBOL. Source Program Organization and Format The only HP extension to ISO/ANSI COBOL that affects source program organization or format is Tandem reference format, which features: • • • 132 columns Continuation of a nonnumeric literal without including trailing spaces No sequence number area or identification field (comment lines instead) For more information on Tandem reference format, see Reference Format for Source Program Lines. HP COBOL Manual for TNS and TNS/R Programs —522555-006 17- 1 HP Extensions to ISO COBOL Language Elements Language Elements The HP extensions to ISO/ANSI COBOL that are language elements are: • • • • • HP COBOL requires at least one character in a COBOL word to be either a letter or a hyphen; COBOL requires a letter. In HP COBOL, using a COBOL word as a library-name does not interfere with its concurrent use as the name of an entity in another category; however, librarynames must be unique among themselves. COBOL limits the forms of system-names to those permitted for user-defined names. HP COBOL relaxes this restriction. The use of each particular systemname is limited to contexts appropriate for its category. The few minor restrictions on duplicate usages of system-names are discussed in SPECIAL-NAMES Paragraph. HP COBOL allows you to qualify status condition-names. COBOL does not permit the decimal point as the rightmost (last) character of a numeric literal; HP COBOL relaxes this restriction somewhat: ° If the apparent last character of a numeric literal qualifies as a decimal point and the immediately following character is not a space (but is a semicolon, comma, or right parenthesis), the compiler interprets that last character as the decimal point. ° If the apparent last character qualifies as a decimal point but the immediately following character is a space, the compiler interprets that last character and the space together as the separator that follows the literal. Data Fundamentals The only HP extension to ISO/ANSI COBOL that affects data fundamentals is byte alignment of binary data items (see PORT and NOPORT). HP COBOL Manual for TNS and TNS/R Programs —522555-006 17- 2 HP Extensions to ISO COBOL Environment Division Environment Division These HP extensions to ISO/ANSI COBOL are elements of the Environment Division: • • CHARACTER-SET Clause Special system-names: ° ° ° CONSOLE for the operator’s console MYTERM for the home terminal of a process CHANNEL-1 through CHANNEL-12 for carriage-control tape channels See System-Name Clause. • • File-Control Entries in General RECEIVE-CONTROL Paragraph Data Division These HP extensions to ISO/ANSI COBOL are elements of the Data Division: • • • Extended-Storage Section ACCESS MODE Clause These additional data formats (see USAGE Clause): ° ° ° ° ° ° ° COMPUTATIONAL-3 (COMP-3) COMPUTATIONAL-5 (COMP-5) NATIVE-2 NATIVE-4 NATIVE-8 PACKED-DECIMAL POINTER HP COBOL Manual for TNS and TNS/R Programs —522555-006 17- 3 HP Extensions to ISO COBOL Procedure Division Verbs Procedure Division Verbs These HP extensions to ISO/ANSI COBOL involve Procedure Division verbs: • • • • For developing fault-tolerant programs to run as process pairs: ° ° ° CHECKPOINT STARTBACKUP SYNCDEPTH phrase of OPEN To mark the beginning of a parameter list, the USING phrase of ENTER To specify a data item that stores the value a function returns, the GIVING phrase of ENTER To control file access and maintain the integrity of data bases in transactionprocessing applications or other applications that allow multiple access to files: ° ° ° ° LOCKFILE UNLOCKFILE UNLOCKRECORD TIME LIMITS phrase of these statements: ° ° ° • • • • • ° ° ° OPEN READ START EXCLUSIVE, SHARED, and PROTECTED phrases of OPEN LOCK phrase of READ UNLOCK phrase of REWRITE To display a prompt before a read operation, PROMPT phrase of READ REVERSED phrase of READ To specify an object file that contains a program unit, the OF or IN phrase of these statements: ° ° ° CALL CANCEL ENTER) Parameters of CALL can be at levels other than 01 or 77 and, under some conditions, can be subscripted Specification of any type of conditional expression in the WHEN phrase of SEARCH ALL (at the cost of not being able to use binary searching in that case) HP COBOL Manual for TNS and TNS/R Programs —522555-006 17- 4 HP Extensions to ISO COBOL • • • • • • Procedure Division Verbs To enable different methods of positioning files, the POSITION, GENERIC, and APPROXIMATE phrases of START PARAGRAPH, SECTION, and PERFORM CYCLE options of EXIT, which transfer control to the end of the paragraph, section, and PERFORM cycle, respectively The GUARDIAN-ERR special register is updated each time a file-manipulating statement is executed. The value of GUARDIAN-ERR usually provides more specific information about the cause of an unsuccessful completion signaled by the file-status data item. For example, if the file status is 30 (permanent error), GUARDIAN-ERR contains the file system error number identifying the cause. See Diagnosing Input-Output Errors. Additional special registers: ° ° ° ° PROGRAM-STATUS PROGRAM-STATUS-1 PROGRAM-STATUS-2 RETURN-CODE If the program is compiled with the PORT directive and runs in the CRE, CALL behaves like the X/OPEN CALL statement, which is not an element of COBOL (see PORT and NOPORT). SET TO statement for pointers In COBOL, identifier-3 is a data item in the Linkage Section of any level except 66 or 88; in HP COBOL, it is any data item in the Linkage Section or Data Division of any level except 88. • MOVE TO statement with sender with decimal digits The 1985 COBOL standard does not allow decimal positions in a numeric item used as sender in a MOVE TO statement. HP COBOL does allow decimal positions in such an item. The decimal point is ignored and sender is handled as if it were an alphanumeric item whose size is equal to the number of 9s in the PICTURE clause. If its USAGE is not DISPLAY, it is converted to DISPLAY for the move operation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 17- 5 HP Extensions to ISO COBOL Procedure Division Verbs HP COBOL Manual for TNS and TNS/R Programs —522555-006 17- 6 18 HP COBOL CRE Support This section: • • Briefly describes the Common Run-time Environment (CRE) (see Introducing the CRE) Summarizes the changes to HP COBOL that allow HP COBOL programs to run in the CRE. These changes involve: ° ° ° ° ° ° ° ° ° Compiler Directives Volume Names Shared File Operations $RECEIVE Processing Arithmetic Overflow Processing TNS HP COBOL Programs in TNS User Libraries CHECKPOINT Access to Extended-Storage Section CBL85UTL Routines COBOLLIB Routines A TNS HP COBOL program that runs in the CRE can call and be called by CRE programs written in HP C, HP C++, FORTRAN, Pascal, and TAL, even if the main program is not written in COBOL. In the non-CRE environment, this is possible only if the main program is written in COBOL. All native programs run in the CRE. Native HP COBOL programs can call and be called by programs written in native HP C, native HP C++, and pTAL, even if the main program is not written in HP COBOL. This section uses these terms: CRE program A program that runs in the CRE Non-CRE program A program that runs in the non-CRE environment For more information: Topics Sources Writing HP COBOL programs for the CRE CRE Programmer’s Guide Converting non-CRE HP COBOL programs to CRE programs Guardian Application Conversion Guide HP COBOL Manual for TNS and TNS/R Programs —522555-006 18- 1 HP COBOL CRE Support Introducing the CRE Introducing the CRE On C-series systems, the HP C, HP C++, HP COBOL, FORTRAN, Pascal, and TAL programming languages each have their own unique run-time environments defined by their respective run-time libraries. These language-specific run-time environments are often incompatible with each other because each language’s run-time library is unaware of other run-time libraries. This incompatibility severely limits the potential for creating useful mixed-language programs. On D-series systems, the Common Run-Time Environment (CRE) is a set of services that supports mixed-language programs. The CRE library is a collection of routines that implements the CRE. The CRE library enables the language-specific run-time libraries to coexist peacefully with each other. User routines and run-time libraries call CRE library routines to access shared resources managed by the CRE, such as the standard files (input, output, and log) and the user heap, regardless of language. The CRE does not support all possible operations. For example, the CRE supports file sharing only for the three standard files: standard input, standard output, and standard log. The language-specific run-time libraries access all other files by calling operating environment procedures directly, whether or not a program uses the CRE. Table 18-1. Run-Time Environments Language TNS Programs Native Programs HP C CRE CRE HP C++ CRE CRE HP COBOL CRE or COBOL environment CRE FORTRAN CRE or FORTRAN environment Not applicable Pascal CRE Not applicable pTAL CRE CRE TAL CRE or TAL environment Not applicable If one program in a run unit runs in the CRE, every program in that run unit must run in the CRE. If a program runs in the CRE, each routine in the program appears to be running in its own language-specific run-time environment, regardless of the language of the main routine. For example, if the main routine of a mixed-language program is written in HP COBOL, an HP C routine has complete access to the HP C run-time library. If a program does not use the CRE, routines written in languages other than that of the main routine have limited access to their run-time libraries. For example, if the main routine of a mixed-language program is written in HP COBOL, an HP C routine has limited access to the HP C run-time library. HP COBOL Manual for TNS and TNS/R Programs —522555-006 18- 2 HP COBOL CRE Support Compiler Directives D-series HP C, HP C++, and Pascal run-time libraries always call CRE library routines for services managed by the CRE; they can run in the CRE only. D-series HP COBOL and FORTRAN run-time libraries call CRE library routines if you compile all of the routines in a program to run in the CRE. In contrast, TAL routines call CRE library routines directly. Refer to the CRE Programmer’s Guide for more information on writing programs that use the services provided by the CRE. Compiler Directives These directives support the CRE: • • • • ENV HIGHPIN HIGHREQUESTERS RUNNAMED Volume Names A CRE HP COBOL program can have eight-character volume names (the dollar sign followed by one to seven characters) in these contexts: • • SELECT clause FILE clause It must have seven-character volume names (the dollar sign followed by one to six characters) in these contexts: • • USING or GIVING files in SORT or MERGE statements Files being read or written with HP COBOL Fast I-O If you use an eight-character volume name in this context, you do not get an error or warning message, but you get normal I-O instead of HP COBOL Fast I-O. HP COBOL Manual for TNS and TNS/R Programs —522555-006 18- 3 HP COBOL CRE Support Shared File Operations Shared File Operations A CRE HP COBOL program shares certain file operations with other programs in its run unit. The shared file operations are associated with these files. Other file operations are not shared. • Standard Output File For DISPLAY statements, it is the default file (no UPON phrase is specified). • Standard Input File For ACCEPT statements, it is the default file (no FROM phrase is specified). This file can be a disk file, including an EDIT file. • Execution Log File The HP COBOL run-time diagnostic messages are written to this file. It is normally the home terminal, but can be selected by PARAM EXECUTION-LOG. • $RECEIVE File It is specified in the RECEIVE-CONTROL paragraph or by a TACL ASSIGN command. Any program in the run unit can read from or write to the preceding files and there is only one shared file connector. In the case of the $RECEIVE File, HP COBOL has high-level interface to it, but programs written in other languages must make special calls to CRE routines to share it. In the case of the other files listed previously, sharing is done by concurrent opens of the file. $RECEIVE Processing $RECEIVE processing in the non-CRE environment and the CRE differ in: • • • • • EXTERNAL Clause MESSAGE SOURCE Clause REPORT Clause Message Format Message Replies The material in this topic applies only to CRE HP COBOL programs that read and write $RECEIVE. It does not apply to non-CRE programs, even if they read and write $RECEIVE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 18- 4 HP COBOL CRE Support EXTERNAL Clause EXTERNAL Clause The EXTERNAL clause of the RECEIVE-CONTROL paragraph enables HP COBOL external files to share communication with $RECEIVE and to share $RECEIVE properly with FORTRAN. For more information, see RECEIVE-CONTROL Paragraph and #RECEIVE Blocks. MESSAGE SOURCE Clause If you specify the MESSAGE SOURCE clause in the RECEIVE-CONTROL paragraph, the last items in the message sender format change: Non-CRE Environment 02 02 CRE PROCESS-ID. 02 PROCESS-NAME 02 CPU-PIN FILLER PIC X(6). PIC X(2). PIC X(16). 02 02 PHANDLE FILLER PIC X(20). PIC X(4). The overall data length is the same, but the process identification is different. In the CRE, the process handle (PHANDLE) has no processor or PIN. Do not write code to extract pieces of the process handle, because its format can change at any time. In the Guardian environment, if you must know the values of the processor and PIN, call the Guardian routine PROCESSHANDLE_DECOMPOSE_. For instructions on how to use PROCESSHANDLE_DECOMPOSE_, see the Guardian Application Conversion Guide. REPORT Clause The message types specified in the REPORT clause are different in the non-CRE environment and the CRE. These old message types have been eliminated in the CRE, because they are covered by other message types: Old Message Type Corresponding CRE Messages ABEND PROCESS-DELETION STOP PROCESS-DELETION NETWORK NODE-DOWN NODE-UP REMOTE-CPU-DOWN REMOTE-CPU-UP The CRE has many new message types and some new message type codes for old message types. In the CRE, the message type SYSTEM includes all messages except LOGICAL-CLOSE and LOGICAL-OPEN. For details, see Table 6-9. HP COBOL Manual for TNS and TNS/R Programs —522555-006 18- 5 HP COBOL CRE Support Message Format Message Format Most of the SYSTEM messages in the CRE are longer than those in the non-CRE environment. If your CRE program is to process SYSTEM messages, make the record area of the $RECEIVE file at least 256 characters long. Message Replies The replies to some messages have changed, particularly the replies to the messages OPEN and CLOSE. In the non-CRE environment, you can reply to these messages with anything; in the CRE, you must reply correctly or (in the Guardian environment) operating environment error 2 results. For correct replies, see the Guardian User’s Guide. Arithmetic Overflow Processing When an arithmetic overflow condition occurs that is not covered by ON SIZE ERROR, the CRE traps the error. Then, if the program specifies PARAM INSPECT ON, the CRE causes the program to enter the selected debugger (see Debugger Selection). If the program specifies PARAM INSPECT OFF, the CRE causes the program to terminate abnormally with a run-time diagnostic message and a trace to the offending statement. TNS HP COBOL Programs in TNS User Libraries The CRE allows TNS HP COBOL programs in TNS user libraries if the programs satisfy the criteria listed in Library Programs. CHECKPOINT Access to Extended-Storage Section The CHECKPOINT statement can access Extended-Storage Section data items. For the NMCOBOL compiler, the CHECKPOINT statement is available for the RVU D46.00 and G06.00 or later, software product revision T8107AAT (run-time library T8108AAR). HP COBOL Manual for TNS and TNS/R Programs —522555-006 18- 6 HP COBOL CRE Support CBL85UTL Routines CBL85UTL Routines Every CBL85UTL routine has a non-CRE version and a CRE version (except one, which is unnecessary in the CRE). The CBL85UTL file is for the COBOL85 compiler. Its CRE routines are also in the ZCOBSRL file, which is for the NMCOBOL compiler. Table 18-2. Old and New Utility Routine Names COBOL-Environment Routine Name1 CRE Routine Name2 COBOL85^ARMTRAP3 No equivalent (unnecessary) COBOL85^COMPLETION COBOL_COMPLETION_ None COBOL_CONTROL_3 COBOL85^RETURN^SORT^ERRORS COBOL_RETURN_SORT_ERRORS_ COBOL85^REWIND^SEQUENTIAL COBOL_REWIND_SEQUENTIAL_ COBOL85^SET^SORT^PARAM^TEXT COBOL_SET_SORT_PARAM_TEXT_ COBOL85^SET^SORT^PARAM^VALUE COBOL_SET_SORT_PARAM_VALUE_ None COBOL_SETMODE_3 COBOL85^SPECIAL^OPEN COBOL_SPECIAL_OPEN_ 1. These routines are only in CBL85UTL, not in ZCOBSRL. 2. These routines are in both CBL85UTL and ZCOBSRL. 3. These routines are not in ZCOBSRL. Using them causes errors. A non-CRE HP COBOL program can call only the non-CRE routines, but a TNS HP COBOL program that runs in the CRE can call any routine. If a TNS HP COBOL program that runs in the CRE calls a non-CRE routine, it actually calls the corresponding CRE routine indirectly. If a CRE HP COBOL program calls COBOL^ARMTRAP, it is ignored. A native HP COBOL program can only call the native routines in ZCOBSRL. Corresponding non-CRE and CRE routines have the same parameters, with this exception: COBOL85^COMPLETION has the parameter text-length, but COBOL_COMPLETION_ does not (the CRE gets the text length from the specified text instead). For more information on the routines listed in Table 18-2, see CBL85UTL and ZCOBSRL Routines. HP COBOL Manual for TNS and TNS/R Programs —522555-006 18- 7 HP COBOL CRE Support COBOLLIB Routines COBOLLIB Routines These COBOLLIB routines are affected by CRE support: • • • COBOLASSIGN COBOLFILEINFO COBOLSPOOLOPEN COBOLASSIGN In the CRE, the routine COBOL_ASSIGN_ has replaced the non-CRE routine COBOLASSIGN. If either a TNS HP COBOL program that runs in the CRE or a native HP COBOL program calls COBOLASSIGN, it actually calls COBOL_ASSIGN_ indirectly. The advantages to calling COBOL_ASSIGN_ directly are: • • • • Any of the parameters that you can pass can be loaded in the Extended-Storage Section or Linkage Section. The system-file-name in the SELECT clause need not be #DYNAMIC. You can specify temporary file names. You can specify two additional parameters, file-code and file-type. For more information, see COBOLASSIGN and COBOL_ASSIGN_. COBOLFILEINFO In the CRE, COBOLFILEINFO always returns a fully-qualified file name (that is, the first character is backward slash (\) and the second character is the system number, even if the file is on a local system). In the non-CRE environment, COBOLFILEINFO does not always return a fully-qualified file name. The native version of COBOLFILEINFO is in the file ZCRESRL. For more information, see COBOLFILEINFO. COBOLSPOOLOPEN A CRE COBOL program cannot call the routine COBOLSPOOLOPEN. Instead, it can call the routine COBOL_SPECIAL_OPEN_, which has all the facilities of COBOLSPOOLOPEN and more. COBOLSPOOLOPEN is in the COBOLLIB file, the TNS version of COBOL_SPECIAL_OPEN_ is in the CBL85UTL file, and the native version of COBOL_SPECIAL_OPEN_ is in the ZCOBSRL file. For more information, see COBOLSPOOLOPEN and COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_. HP COBOL Manual for TNS and TNS/R Programs —522555-006 18- 8 19 Using HP COBOL in the OSS Environment The NonStop operating system offers two operating environments: • • Guardian environment OSS environment Open System Services provides industry-standard application program interfaces (APIs) and utilities to enable you to port existing applications quickly and easily to NonStop systems. The NonStop operating system continues to support Guardian services. HP has enhanced many tools from the Guardian environment so that they also operate in the OSS environment. For example, the Binder and linker now identify OSS object files as well as Guardian object files. Most features of the HP COBOL language and library are available in the OSS environment, and most of them operate as they do in the Guardian environment. This section explains the few exceptions. It also describes line sequential files (also called OSS ASCII files), which are available in the OSS environment. For complete information about the OSS environment, see the Open System Services Programmer’s Guide. Topics: • • • • • • • • • • Running the COBOL85 Compiler Running the NMCOBOL Compiler Running HP COBOL Programs Calling OSS Functions From HP COBOL Programs Mixed-Language Programs Changing Default Pathnames and Disk Volume Files in the OSS Environment Line Sequential Files Features Unavailable in the OSS Environment Features That Operate Differently in the OSS Environment To terminate a compilation in the OSS environment, press Control-C (that is, press Control and C—not c—simultaneously). HP COBOL Manual for TNS and TNS/R Programs —522555-006 19- 1 Using HP COBOL in the OSS Environment Running the COBOL85 Compiler Running the COBOL85 Compiler In the OSS environment, the OSS utility cobol calls the COBOL85 compiler, optionally followed by the Binder (BIND), Accelerator (AXCEL), and SQL/MP compiler (SQLCOMP). The flags and the types of files in the operands determine which processes operate on the files in the operands. The cobol utility generates programs that run in the OSS environment. To generate programs that run in the Guardian environment, use the COBOL85 command in the Guardian environment (see Starting a Compilation). Text file inputs to the compiler can be OSS ASCII text files (code 180) or Guardian EDIT files (code 101). The command to run the COBOL85 compiler in the OSS environment is: cobol pathname flag operand operand VST621.vsd cobol must be typed as shown, in lowercase letters. flag is as described in the Open System Services Shell and Utilities Reference Manual. operand pathname -l library VST622.vsd pathname ns file ns . cbl cob a o srl VST623.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 19- 2 Using HP COBOL in the OSS Environment Running the NMCOBOL Compiler Successful compilation always creates object files. If the -c flag is specified, the object files created for source files of the form file.cbl have the form file.o. For example, for a source file named main.cbl, successful compilation creates an object file named main.o in the current directory. Note. If you compile more than one source file in a single compilation with the cobol utility, the COBOL85 compiler creates an object file for each source file for which there were no compilation errors. Running the NMCOBOL Compiler In the OSS environment, the OSS utility nmcobol calls the native HP COBOL compiler (NMCOBOL), optionally followed by the linker and SQLCOMP compiler (for SQL/MP) or MXCMP compiler (for SQL/MX). The flags and the types of files in the operands determine which processes operate on the files in the operands. The nmcobol utility generates programs that run in the OSS environment. To generate programs that run in the Guardian environment, use either the -Wsystype=guardian flag in the OSS environment or the NMCOBOL command in the Guardian environment (see Starting a Compilation). Text file inputs to the compiler can be OSS ASCII text files (code 180) or Guardian EDIT files (code 101). The command to run the NMCOBOL compiler in the OSS environment is: nmcobol pathname flag operand operand VST733.vsd nmcobol must be typed as shown, in lowercase letters. flag is as described in the Open System Services Shell and Utilities Reference Manual. operand pathname -l library VST622.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 19- 3 Using HP COBOL in the OSS Environment Running HP COBOL Programs pathname ns file ns . cbl cob ecbl ecob a m o srl VST623.vsd Note. The file suffixes (cbl, cob, and so on) are not case-sensitive. Running HP COBOL Programs After successfully compiling your HP COBOL program in the OSS environment, you have a loadfile. Its name is either a.out (by default) or the name you gave it with the -o flag. If the current directory is in your search path, you can run your program by typing the name of the loadfile and pressing Return. For example, if the name of the loadfile is a.out, enter: a.out To run the program with the selected debugger (see Debugger Selection), enter: run -debug a.out If the current directory is not in your search path, add it with this command: export PATH=$PATH:. Calling OSS Functions From HP COBOL Programs An HP COBOL program can call an OSS function with either the X/Open CALL statement or the ENTER statement. The ENTER statement is easier. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19- 4 Using HP COBOL in the OSS Environment Mixed-Language Programs Mixed-Language Programs In the OSS environment, you can write mixed-language programs. Topics: • • TNS Programs Native Programs TNS Programs A TNS HP COBOL program can call programs written in TNS HP COBOL, TNS HP C, TNS HP C++, or TAL, but not programs written in FORTRAN or Pascal. To produce a TNS HP COBOL program that contains TNS HP COBOL and TNS HP C modules, follow these steps: 1. Using the /usr/nonnative/c89 utility, compile the HP C modules, but do not bind them. 2. Using the cobol utility, compile the HP COBOL modules, specifying any necessary binding, accelerating, or SQL-compiling flags. For example, suppose that you want to produce a loadfile from the HP COBOL modules cobol1.cbl and cobol2.cbl and the HP C modules c1.c and c2.c. First you use the c89 utility to compile the HP C modules without binding them: c89 -c -o cprog.o c1.c c2.c The resulting object file is cprog.o. Then you use the cobol utility to do this: • • • Compile the HP COBOL modules Bind the COBOL85 compiler output, the object file cprog.o, and the standard HP C library Run the Accelerator and produce the loadfile myprog: cobol -o myprog cprog.o cobol1.cbl cobol2.cbl HP COBOL Manual for TNS and TNS/R Programs —522555-006 19- 5 Using HP COBOL in the OSS Environment Native Programs Native Programs Native HP COBOL programs can call programs written in native HP COBOL, native HP C, native HP C++, or pTAL. To produce a native HP COBOL program that contains native HP COBOL and native HP C modules, follow these steps: 1. Using the c89 utility, compile the HP C modules, but do not link them. 2. Using the nmcobol utility, compile the HP COBOL modules, specifying any necessary linking or SQL-compiling flags. For example, suppose that you want to produce a loadfile from the native HP COBOL modules cobol1.cbl and cobol2.cbl and the native HP C modules c1.c and c2.c. First you use the c89 utility to compile the HP C modules without linking them: c89 -c -o cprog.o c1.c c2.c The resulting object file is cprog.o. Then you use the nmcobol utility to do this: • • • Compile the HP COBOL modules Link the nmcobol compiler output, the object file cprog.o, and the native HP C library. Produce the loadfile myprog: nmcobol -o myprog cprog.o cobol1.cbl cobol2.cbl The nmcobol utility automatically links the HP C SRLs to myprog. Changing Default Pathnames and Disk Volume The “Default” column of Table 19-1 shows the default pathnames of the programs that the cobol and nmcobol commands call and the default disk volume on which they create temporary files. To change one or more of these defaults before executing the cobol or nmcobol command, use the export command. To execute a cobol or nmcobol command with a specified set of environment variables, use the OSS env function with the environment variables that Table 19-1 lists and explains. For the syntax of the env function, see the env(1) command reference page either online or in the Open System Services System Calls Reference Manual. The effect of the export command lasts until you explicitly change it. The effect of the env function applies only to the cobol or nmcobol command with which you use it. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19- 6 Using HP COBOL in the OSS Environment Changing Default Pathnames and Disk Volume Table 19-1. Environment Variables Variable Effect Default COBOL Determines the pathname of the COBOL85 compiler that the cobol utility calls /G/system/system/cobol85 NMCOBOL Determines the pathname of the NMCOBOL compiler that the nmcobol utility calls /G/system/system/cobolfe BIND1 Determines the pathname of the Binder that the cobol utility calls /G/system/system/bind AXCEL1 Determines the pathname of the Accelerator that the cobol utility calls /G/system/system/axcel SWAPVOL1 Determines the disk volume on which the COBOL85 compiler, Binder, Accelerator, and SQL/MP compiler create temporary files Same as in the Guardian environment— see PARAM SWAPVOL SQLCOMP Determines the pathname of the SQL/MP compiler that the cobol or nmcobol utility calls /G/system/system/sqlcomp MXSQLCO2 Determines the pathname of the alternate COBOL SQL/MX preprocessor that the nmcobol utility calls /usr/tandem/sqlmx/bin/ MXCMP2 Determines the pathname of the alternate SQL/MX compiler that the nmcobol utility calls /G/system/system/ SQLCLIO2 Determines the pathname of the object file that describes the SQL/MX API to the nmcobol utility /usr/tandem/sqlmx/lib/sqlcli.o 1. For the COBOL85 compiler only. 2. For the NMCOBOL compiler only. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19- 7 Using HP COBOL in the OSS Environment Files in the OSS Environment Files in the OSS Environment In the OSS environment, you can use both OSS and Guardian files. OSS files are either line sequential files (see Line Sequential Files) or sequential files with fixedlength records and no alternate keys. Guardian files are all types of files that HP COBOL programs can access in the Guardian environment. In the OSS environment, both OSS and Guardian files must have OSS pathnames. Topics: • • • • OSS Pathnames OSS Pathnames in HP COBOL Source Programs OSS Files in HP COBOL Source Programs #IN and #OUT OSS Pathnames In the OSS environment, both OSS files and Guardian files must have OSS pathnames. These two topics briefly describe these pathnames. For further information, see the Open System Services Programmer’s Guide and the filename(5) reference page either online or in the Open System Services System Calls Reference Manual. OSS Pathnames for OSS Files The OSS pathname of an OSS file has this format: ns OSS /E/ ns node filename / ns ns directory / ns VST634.vsd OSS specifies that the file is an OSS file (the default). If OSS is specified, the entire pathname must be enclosed in quotation marks. node specifies the name of a remote node. The operating system on the node must be version D40.00 or later, and the node must have a compatible OSS name server. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19- 8 Using HP COBOL in the OSS Environment OSS Pathnames / specifies the root directory when it appears at the beginning of a pathname; elsewhere, it separates directory names and file names. directory is the name of a directory. A directory name can contain any characters except slash (/) and the NULL character (zero). Its first character cannot be a hyphen (-). Its maximum length is NAME_MAX characters, as defined by the limitsh header file. If directory contains special characters, the entire pathname must be enclosed in quotation marks. These directory names have special meanings: Directory Name Meaning . OSS current working directory .. Parent directory of the OSS current working directory file-name is the name of a file. A file name can contain any characters except slash (/) and the NULL character (zero). Its first character cannot be a hyphen (-). Its maximum length is NAME_MAX characters, as defined by the limitsh header file. If filename contains special characters, the entire pathname must be enclosed in quotation marks. Example 19-1. OSS Pathnames for OSS Files file2 vol1/file2 usr/vol1/file2 /usr/vol1/file2 /usr/vol1/part3/file2 "OSS /usr/vol1/file2" /E/qa2/usr/vol1/file2 "OSS /E/qa2/usr/vol1/file2" OSS Pathnames for Guardian Files The OSS pathname of a Guardian file has this format: " ns ns GUARDIAN " device file-id-1 ns OSS file-id-2 ns /E/ ns node VST734.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 19- 9 Using HP COBOL in the OSS Environment OSS Pathnames in HP COBOL Source Programs device specifies a Guardian device or either of the special names #DYNAMIC or #TERM. file-id-1 node.volume.subvolume.file_id node specifies the name of a remote node. The operating system on the node must be version D40.00 or later, and the node must have a compatible OSS name server. file-id-2 /G/volume/subvolume/file_id Example 19-2. OSS Pathnames for Guardian Files "GUARDIAN \qa.tests.cobol85.release4" "GUARDIAN S.#PRNT2" "OSS /G/tests.cobol85.release4" "OSS /E/qa/G/$tests.cobol85.release4" OSS Pathnames in HP COBOL Source Programs Within an HP COBOL source program, OSS pathnames are allowed as systemfile-name parameters in these contexts: • In the File-Mnemonic clause of the SPECIAL-NAMES paragraph, for example: SPECIAL-NAMES. FILE "OSS /usr/test/fileID" IS A-FILE. FILE "GUARDIAN $MYVOL.SUBVOL.FILEID" IS B-FILE. FILE "OSS /G/MYVOL/SUBVOL/FILEID" IS C-FILE. Note. If system-file-name is an OSS file, it cannot be a DEFINE name. If systemfile-name is a Guardian file, it can be DEFINE name. • In the ASSIGN clause of a file-control entry, for example: FILE-CONTROL. SELECT A-FILE ASSIGN TO "OSS /usr/test/fileID". SELECT B-FILE ASSIGN TO "GUARDIAN $MYVOL.SUBVOL.FILEID". SELECT C-FILE ASSIGN TO "OSS /G/MYVOL/SUBVOL/FILEID". Within an HP COBOL program, the maximum length of an OSS pathname is the maximum length of a literal (160 characters). HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -10 Using HP COBOL in the OSS Environment OSS Files in HP COBOL Source Programs OSS Files in HP COBOL Source Programs The only OSS files that an HP COBOL program can use are line sequential files (see Line Sequential Files) and sequential files with fixed-length records and no alternate keys. Relative files, indexed files, and sequential files with keys or variable-length records must be Guardian files (Enscribe files), and their OSS pathnames must include “/G” or “GUARDIAN” (see OSS Pathnames for Guardian Files). If the OSS pathname of a sequential file does not include “/G” or “GUARDIAN,” then that file is an OSS unstructured file. It has fixed-length records of the maximum record size. In contrast, the default Guardian sequential file is entry-sequenced and can have variable-length records. #IN and #OUT In the OSS environment, #IN and #OUT are the default input device (FD 0) and the default output device (FD 1), respectively. You cannot use #IN and #OUT in SELECT clauses or the SPECIAL-NAMES paragraph as you can in the Guardian environment. Line Sequential Files Line sequential files (code 180) are available only in the OSS environment. Their organization is line sequential. They are compatible with the system text editor of the OSS environment; therefore, they can also be called OSS ASCII text files. (The X/Open CAE specification defines an OSS ASCII text file as one that is compatible with the system text editor.) Line sequential files have these characteristics: • Every character in a record is printable. Note. The operating system does not check for this. • • • Every record ends with a line-feed character, which is appended by a write operation and removed by a read operation. (This characteristic distinguishes line sequential files from sequential files.) After a read operation, the record area from the last character of the actual record to the end of the record area is filled with space characters (ASCII character code SP). If the record area is shorter than the record in the file, the next read operation starts after the last character moved to the record area. (The length of the record area is determined by the RECORD clause if it exists; otherwise it is determined by the largest of the record descriptions.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -11 Using HP COBOL in the OSS Environment File-Control Entries These topics explain these items with respect to line sequential files: • • • • • • • File-Control Entries File Description Entries I-O-CONTROL Paragraph OPEN Statement READ Statement REWRITE Statement WRITE Statement File-Control Entries The syntax for a file-control entry for a line sequential file is: SELECT clause ASSIGN clause . RESERVE clause ORGANIZATION clause ACCESS MODE clause FILE STATUS clause VST624.vsd SELECT clause FILE-CONTROL file-control-entry . VST036.vsd OPTIONAL makes the file optional, which means that an OPEN statement with an INPUT, I-O, or EXTEND phrase can open the file regardless of whether the file exists. If the file exists, its I-O status code is “00”; if not, its I-O status code is “05.” OPTIONAL does not affect the OPEN statement with an OUTPUT phrase. When you open a nonexistent optional file for input, the first READ statement for that file calls the AT END option (or USE procedure if the READ statement has no AT END phrase). HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -12 Using HP COBOL in the OSS Environment File-Control Entries file-name is the COBOL file name (the file-name in a file description entry). ASSIGN clause ASSIGN system-file-name TO VST640.vsd associates file-name with system-file-name. Only the first system-filename has meaning. The compiler ignores subsequent names and literals and issues a warning. system-file-name is the name of a file as it is known to the file system. It must be enclosed in quotation marks unless it forms a COBOL word. For more information about Guardian file names, see the Guardian Procedure Calls Reference Manual. For more information about OSS file names, see the filename(5) reference page either online or in the Open System Services System Calls Reference Manual. RESERVE clause is ignored. ORGANIZATION clause LINE ORGANIZATION SEQUENTIAL IS VST625.vsd makes the organization of the file line sequential. ACCESS MODE clause ACCESS SEQUENTIAL MODE IS VST044.vsd makes the access mode of the file sequential (the default). HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -13 Using HP COBOL in the OSS Environment File Description Entries FILE STATUS clause filestat STATUS FILE IS VST000.vsd defines filestat as the file-status data item for the file. When a COBOL runtime I-O routine completes an operation on the file, it stores the status code in filestat before returning control to your program (see I-O Status Code). filestat is an alphanumeric, nonnational data item defined in the Working-Storage Section, Extended-Storage Section, or Linkage Section. File Description Entries The syntax for a file description entry for a line sequential file is: file-name . EXTERNAL clause GLOBAL clause RECORD CONTAINS clause «LABEL RECORDS clause» «VALUE OF clause» «DATA RECORDS clause» REPORT clause VST633.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -14 Using HP COBOL in the OSS Environment I-O-CONTROL Paragraph file-name is the highest-level qualifier for both a file description entry and its data descriptions; therefore, the name must be unique within a program. EXTERNAL clause GLOBAL clause RECORD CONTAINS clause «LABEL RECORDS clause» «VALUE OF clause» «DATA RECORDS clause» REPORT clause are described in File Description Entries. I-O-CONTROL Paragraph The syntax for an I-O-CONTROL paragraph for a line sequential file is: I-O-CONTROL . . «RERUN clause» SAME AREA clause VST632.vsd «RERUN clause» Note. The 1985 COBOL standard classifies RERUN as obsolete, so you are advised not to use it. RERUN rerun-file ON system-name EVERY rerun-file-2-phrase units CLOCK-UNITS condition VST058.vsd rerun-file system-name are handled as comments. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -15 Using HP COBOL in the OSS Environment I-O-CONTROL Paragraph rerun-file-2-phrase recs RECORDS REEL OF END UNIT rerun-file-2 OF VST059.vsd units condition are handled as comments. SAME AREA clause SAME RECORD SORT AREA FOR MERGE same-file VST060.vsd specifies the files that share the same memory during program execution. These files do not share disk space or tape space. The SAME AREA clause has different meanings for I-O files (sequential, relative, indexed) than for sort-merge files. same-file is a file name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -16 Using HP COBOL in the OSS Environment OPEN Statement OPEN Statement The OPEN statement has this file-specification: INPUT OUTPUT I-O input-file-description output-file-description i-o-file-description EXTEND extend-file-description VST187.vsd INPUT specifies that the file or files in input-file-description are being opened for reading only. input-file-description infile SHARED PROTECTED EXCLUSIVE VST627.vsd infile is the file description file name of a file to open in INPUT mode, for read operations only. SHARED allows other processes to read or write the file while this process is open. SHARED is the default for terminals. PROTECTED allows other processes to read but not write the file while this process is open. PROTECTED is the default for input files that are not terminals. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -17 Using HP COBOL in the OSS Environment OPEN Statement EXCLUSIVE prevents other processes from reading or writing the file while this process is open. EXCLUSIVE is the default for all other files. OUTPUT specifies that the file or files in output-file-description are being opened for writing only. output-file-description outfile SHARED PROTECTED EXCLUSIVE VST628.vsd outfile is the file description file name of a file to open in OUTPUT mode, for write operations only. SHARED PROTECTED EXCLUSIVE are the same as described earlier for infile. I-O specifies that the file or files in i-o-file-description are being opened for reading and writing. i-o-file-description iofile SHARED PROTECTED EXCLUSIVE VST626.vsd iofile is the file description file name of a file to open in I-O mode, for both read and write operations. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -18 Using HP COBOL in the OSS Environment OPEN Statement SHARED PROTECTED EXCLUSIVE are the same as described earlier for infile. EXTEND specifies that the file or files in extend-file-description are being opened for writing additional data following any existing data. extend-file-description extfile SHARED PROTECTED EXCLUSIVE VST629.vsd extfile is the file description file name of a sequential file to open in EXTEND mode, for write operations that append records to the file. The file is positioned after the last logical record when opened. All operations on the file must be write operations, as if the file had been opened in OUTPUT mode. If the file is an Enscribe unstructured file, its size must be a multiple of the record size. SHARED PROTECTED EXCLUSIVE are the same as described earlier for infile. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -19 Using HP COBOL in the OSS Environment READ Statement READ Statement The READ statement for a line sequential file has this syntax: READ file-name INTO data-name END imperative-stmt-1 AT NOT END imperative-stmt-2 AT END-READ VST630.vsd file-name is the file description name of the file to retrieve a record from. data-name is the identifier of the data area defined by your program to which the contents of the record area are transferred after the read operation is complete. data-name cannot be an index-name or the identifier of an index data item. The transfer is conducted as if it were a move from an alphanumeric item to an alphanumeric item. The INTO phrase is allowed only when either: • • All records associated with file-name are defined as data structures or as elementary alphanumeric items and data-name is either a data structure or an elementary alphanumeric item. Only one record is associated with file-name. LOCK keeps other programs from gaining access to the record retrieved until an UNLOCKFILE or UNLOCKRECORD statement is executed. The file specified by file-name must be associated with a disk device. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -20 Using HP COBOL in the OSS Environment REWRITE Statement imperative-stmt-1 is an imperative statement to be performed when the end of the file is encountered at the beginning of the read operation. This phrase is required if no USE statement is applicable for the file. If both a USE statement and an AT END phrase are present, only the AT END phrase is used. imperative-stmt-2 is an imperative statement to be performed when the end of the file is not encountered at the beginning of the read operation. END-READ ends the scope of the READ statement, causing the READ to be a delimited-scope statement. If the READ statement does not end with an END-READ phrase, the presence of the AT END or the NOT AT END phrase causes the READ statement to be a conditional statement, which ends at the next period separator. REWRITE Statement The REWRITE statement for a line sequential file has this syntax: REWRITE FROM record-name data-name END-REWRITE VST721.vsd record-name is the record-name in an file description entry whose current contents replaces a record in the file. The file must be open in I-O mode. data-name is the identifier of the item that contains the new record instead of record-name. When this phrase is used, an implicit MOVE statement occurs to copy the data to record-name before the rewrite operation occurs. data-name cannot specify an index-name or an index data item. data-name cannot specify a data item allocated within the record area in which record-name is located. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -21 Using HP COBOL in the OSS Environment WRITE Statement END-REWRITE ends the scope of the REWRITE statement, causing the REWRITE to be a delimited-scope statement. If the REWRITE statement does not end with an ENDREWRITE phrase, the presence of the INVALID KEY or the NOT INVALID KEY phrase causes the REWRITE statement to be a conditional statement, which ends at the next period separator. WRITE Statement The WRITE statement for a line sequential file has this syntax: WRITE record-name FROM from-name END-WRITE VST631.vsd record-name is a logical record described in the File Section of the Data Division. The recordname can be qualified by the name of the file with which the record is associated. The data written is the current contents of record-name. from-name is the identifier of a data area whose contents are to be moved to the record specified by record-name before the WRITE occurs. from-name must specify a data area other than that specified by record-name. It cannot specify an index data item. END-WRITE ends the scope of the WRITE statement, causing the WRITE to be a delimitedscope statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -22 Using HP COBOL in the OSS Environment Features Unavailable in the OSS Environment Features Unavailable in the OSS Environment Features that are available in the Guardian environment but not in the OSS environment fall into these categories: • • • • ASSIGN Commands PARAM Commands Compiler Directives Process Pairs ASSIGN Commands ASSIGN commands are not available in the OSS environment, You can use DEFINEs for some ASSIGN functions, but because DEFINEs do not accept OSS pathnames, they cannot perform the ASSIGN function of overriding file assignments made at compilation time. PARAM Commands PARAM commands are not directly available in the OSS environment, but analogous OSS environment variables exist for the PARAM commands in Table 19-2. Table 19-2. Analogous PARAM Commands and OSS Environment Variables PARAM Command OSS Environment Variable1 PARAM DEBUG ON export DEBUG=ON PARAM DEBUG OFF export DEBUG=OFF PARAM EXECUTION-LOG None—STDERR is used PARAM INSPECT ON export INSPECT=ON PARAM INSPECT OFF export INSPECT=OFF PARAM NONSTOP ON export NONSTOP=ON PARAM NONSTOP OFF export NONSTOP=OFF PARAM PRINTER-CONTROL name export PRINTER_CONTROL=name PARAM SWITCH-n ON2 export SWITCH_n =ON2 PARAM SWITCH-n OFF2 export SWITCH_n =OFF2 PARAM WAITED-IO Not applicable to CRE 1. Type nonvariables with the cases and spacing shown. 2. n is “1” through “9” or “10” through “15” (without quotes). HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -23 Using HP COBOL in the OSS Environment Compiler Directives Compiler Directives These compiler directives are not allowed in the OSS environment: Directive Reason ENV OLD ENV LIBRARY In the OSS environment, HP COBOL programs run in the CRE. NONSTOP The OSS environment does not support HP COBOL process pairs. SAVE The OSS environment does not have initialization messages. SUBTYPE The OSS environment does not support the concept of subtypes. Process Pairs The OSS environment does not support HP COBOL process pairs; therefore, the CHECKPOINT and STARTBACKUP statements return error 7000 in the special register PROGRAM-STATUS. Features That Operate Differently in the OSS Environment Features that operate differently in the Guardian and OSS environments fall into these categories: • • ACCEPT and DISPLAY Statements Utility Routines that require or return file names ACCEPT and DISPLAY Statements These are true in the OSS environment but not in the Guardian environment: • • • No prompt is given for an ACCEPT statement. If a DISPLAY statement includes mnemonic-name, it must be the OSS pathname of either a Guardian file or a pipe to a terminal or device. If an ACCEPT statement includes mnemonic-name, it must be the OSS pathname of a Guardian process or terminal. If mnemonic-name is an OSS device, a diagnostic is issued and the default input device (#IN) is used instead. HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -24 Using HP COBOL in the OSS Environment Utility Routines Utility Routines These utility routines accept only Guardian file names: • • • COBOL_RETURN_SORT_ERRORS_ COBOL_SET_SORT_PARAM_TEXT_ COBOL_SPECIAL_OPEN_ If a program passes a file name to the utility routine COBOL_ASSIGN_, then COBOL_ASSIGN_ assumes that the file name is a Guardian file name unless the calling program identified the file name as an OSS file name. The utility routine COBOLFILEINFO does not return useful information in the OSS environment. Use the routine COBOL_FILE_INFO_ instead. When using #DYNAMIC in the OSS environment to dynamically assign Guardian file names or Guardian spooler process names, you must use "GUARDIAN #DYNAMIC" in the file-control entry. The file name passed by the COBOL_ASSIGN_ utility is a standard Guardian name. Example 19-3. “GUARDIAN #DYNAMIC” in a File-Control Entry SELECT ASGN ASSIGN TO "GUARDIAN #DYNAMIC" FILE STATUS IS FILE-STATUS. ... MOVE "$S.#TEST" TO FILENAM ENTER "COBOL_ASSIGN_" USING ASGN, FILENAM GIVING asn-error HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -25 Using HP COBOL in the OSS Environment HP COBOL Manual for TNS and TNS/R Programs —522555-006 19 -26 Utility Routines 20 HP COBOL Limits The HP architecture and the method of implementation of the HP COBOL compilers, COBOL85 and NMCOBOL, impose these kinds of limits on HP COBOL programs: • • • • • • Size Number Callability External Names Ranges of Values Ignored Elements Size • Block size of record in a data file The maximum block size of a record in a data file is 32,767 characters. • Buffer size for reading (HP COBOL Fast I-O) 2 * number * dbs, where number is specified in the RESERVE clause for the file being read, and dbs is the data block size of the file being read. • Buffer size for writing (buffered cache or HP COBOL Fast I-O) 29K characters per block, regardless of the number in the RESERVE clause. • Buffer space needed for files The sum of the buffer space needed for files cannot exceed 62 KB. • Code ° Single TNS HP COBOL program A single TNS HP COBOL program (in which no other HP COBOL programs are nested) can occupy up to 128 KB of user code space. A program that contains nested programs can be much larger than 128 KB, but no single program can exceed 128 KB. ° Single TNS/R HP COBOL program The code space limit for a native HP COBOL program is 32 megabytes. ° C, FORTRAN, Pascal, and TAL programs in TNS processes For a TNS process, an individual C, FORTRAN, Pascal, or TAL program unit can occupy up to 64 KB of user code space or user library space (but FORTRAN programs in user library space cannot use DATA, COMMON, or SAVE statements). HP COBOL Manual for TNS and TNS/R Programs —522555-006 20- 1 HP COBOL Limits ° Size TNS COBOL run unit A COBOL run unit can have up to 32 segments of code, each segment including up to 128 KB. If the program calls any code in user library space, the user code space can contain a maximum of 16 segments of COBOL, FORTRAN, TAL, C, and Pascal code, and the user library space can contain an additional 16 segments of COBOL, FORTRAN and TAL code. If the program does not call any routines in user library space, the user code space can contain up to 32 segments of COBOL, FORTRAN, TAL, C, and Pascal code. The procedure entry-point (PEP) table, up to 1024 bytes, is part of each code segment. If any program unit exceeds 64 KB, the PEP table for its segment is exactly 1024 bytes. If any program in a segment calls an external routine (a routine in another code segment), an external entry-point (XEP) table is also part of the segment. The size of the XEP table depends upon the number of external routines called. The Binder object-file builder reserves space for one XEP table entry for each unresolved external reference. ° TNS/R COBOL run unit On a D-series or pre-G05 system, individual segments are limited to 128 KB. On a G05 or later system, a native run unit has an overall address space of just under 1.1 GB. ° Contained program The object code generated for a contained program cannot exceed 65,536 bytes. ° Separately compiled program The object code generated for a separately compiled program cannot exceed 131 KB. • Composite of Operands The composite of operands for an arithmetic statement other than COMPUTE must not exceed a size of 18 decimal digits. For arithmetic expressions or COMPUTE statements, the composite of operands does not apply. HP COBOL Manual for TNS and TNS/R Programs —522555-006 20- 2 HP COBOL Limits • Size Data in a run unit ° TNS HP COBOL The total size of all the items in the File Sections and Working-Storage Sections of all the programs of a run unit cannot exceed approximately 63,400 bytes. The upper 64 KB of the 128 KB of user data space is reserved for buffers and run-time data structures. Declare very large data items in the Extended-Storage Section. The total size of all the items in the Extended-Storage Sections of all the programs of a run unit cannot exceed 133,693,440 bytes (127.5K). ° TNS/R HP COBOL The Working-Storage Section and the Extended-Storage Section are the same in native HP COBOL. The small data area has a maximum size of 32,768 characters. On a D-series or pre-G05 system, individual segments are limited to 128 KB. On a G05 or later system, a native run unit has an overall address space of just under 1.1 GB. • Data item to be operated on by the INSPECT, STRING, or UNSTRING statement For the COBOL85 compiler, a data item to be operated on by the INSPECT, STRING, or UNSTRING statement cannot exceed 32,767 characters, even if it is described in the Extended-Storage Section. • File-control entry with multiple keys In a file-control entry with multiple keys, the sum of the lengths of the keys cannot exceed 253 characters. • Index An index (index-name or index data item) occupies four bytes, in any section: File, Working-Storage, or Extended-Storage. • Length of a numeric literal A numeric literal has a maximum length of 18 digits. • Length of a nonnumeric literal or OSS path name A nonnumeric literal or OSS path name has a maximum length of 160 characters. • Logical page When a file definition includes a LINAGE clause, the size of its logical page is limited to 9,999 lines. HP COBOL Manual for TNS and TNS/R Programs —522555-006 20- 3 HP COBOL Limits • Number Record or table Location of Record or Table Maximum Record or Table Size Extended-Storage Section No explicit limit—one record of 134,217,726 characters is possible File assigned to $RECEIVE 32 KB File assigned to another device Operating environment limits for the device apply File Section 32,767 characters Linkage Section 134 megabytes Working-Storage Section For a TNS program: 32,767 characters. For a native program: no explicit limit—one record of 134,217,726 characters is possible • Relative record number For software RVUs G06.00 and D46.00 and later, the maximum relative record number for a relative file is 64 bits for NMCOBOL and in the CRE for COBOL85. • Tables allocated by the RECEIVE-CONTROL paragraph The maximum size of the tables allocated by the RECEIVE-CONTROL paragraph is 62 KB (65,400 characters). Anything larger causes a compilation error. Smaller sizes can cause Binder errors (depending on the number of files specified in the programs that comprise the run unit and other factors). Number These items, whose number in a program is limited, are in alphabetic order. • AFTER phrases in a PERFORM statement The maximum number of AFTER phrases in a PERFORM statement is 6. • Characters written to an Edit-format file A HP COBOL program can write at most 239 characters to a record of an Editformat file • CONSULT and SEARCH files for NMCOBOL program For RVUs D46 and G06 and later, the number of CONSULT and SEARCH files (including NMCOBEXT, ZCRESRL, and ZCOBSRL) for an NMCOBOL program cannot exceed 64. • Digits in a hexadecimal numeric literal The minimum number of hexadecimal digits in a hexadecimal numeric literal is 2 (1 pair); the maximum is 16 (8 pairs). HP COBOL Manual for TNS and TNS/R Programs —522555-006 20- 4 HP COBOL Limits • Number File names ° In a MULTIPLE FILE TAPE clause HP COBOL supports 31 file names within a single MULTIPLE FILE TAPE clause. ° In the GIVING or USING phrase of a MERGE or SORT statement HP COBOL supports a maximum of 31 file names within the USING or GIVING phrase of a SORT or MERGE statement. • Keys HP COBOL supports a maximum of 31 alternate record keys for a file, 31 key references in an OCCURS clause, and 31 keys in a SORT or MERGE statement. • Maximum number of concurrent statement names in SQL/MP Without Extended Dynamic SQL (EDS), the maximum number of concurrent statement names in SQL/MP is 20. With EDS, you need not prespecify the maximum number of concurrent statement names. • MULTIPLE FILE TAPE clauses HP COBOL supports a maximum of 8 MULTIPLE FILE TAPE clauses within a source program. • Nesting depth ° OCCURS clauses The maximum depth of OCCURS clauses in a table is 7. ° Programs Programs can be nested within other programs to a depth of 7. ° HP COBOL PERFORM stack The maximum depth varies from 0 to approximately 15,000, depending on the space available on the stack. ° NMCOBOL PERFORM stack The maximum depth is 50. • Parameters The maximum number of parameters that can be passed by a HP COBOL program or to a HP COBOL program is 126. • Prime key offset For indexed files, the maximum offset of a prime key from the beginning of a record is 2,034, which is an Enscribe record manager limitation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 20- 5 HP COBOL Limits • Number Procedure names in a program (COBOL85 compiler only) The default maximum number of procedure names (paragraph names and section names) in a program is approximately 1K. You can change the default with the PARAM SYMBOL-BLOCKS command (see PARAM SYMBOL-BLOCKS). • Records ° External (COBOL85 compiler only) A record (or file) that has the EXTERNAL attribute belongs to the run unit itself, and is available to any program in the run unit that declares it consistently. Up to 24 Extended-Storage Section records can have the EXTERNAL attribute. Each such record consumes 2 units of allocation. Call the number of such records actually used N. The allocation units remaining for EXTERNAL records of Working-Storage Section, EXTERNAL records of File Section, and the EXTERNAL files associated with those records is: 240 - ( 2 * N ) Each Working-Storage Section EXTERNAL record (together with any redefinitions of it) consumes one unit of allocation. Each File-Section EXTERNAL file consumes one unit of allocation for its record area (together with any redefinitions of it). ° Internal There is no explicit limit on the number of internal records (records that do not have the EXTERNAL attribute) in a main program, a called program, or a run unit. • Receivers ° In an INITIALIZE Statement The maximum number of receivers in an INITIALIZE statement is 127. ° In a MOVE statement The maximum number of receivers in a MOVE statement is 255. • References to level-88 condition-names in a program (NMCOBOL only) A condition-name can be defined in the Environment Division (associated with an external switch) or in the Data Division (as a level-88 item). The Procedure Division of a program can have a maximum of 32,767 references to level-88 conditionnames. There is no limit to the number of references to condition-names for external switches. • Subjects in an EVALUATE statement The maximum number of receivers in an EVALUATE statement is 127. HP COBOL Manual for TNS and TNS/R Programs —522555-006 20- 6 HP COBOL Limits • Callability Subscripts See Nesting depth. Callability TNS HP COBOL programs can call programs written in: • • • • • • TNS HP C TNS HP C++ TNS HP COBOL FORTRAN Pascal TAL In the non-CRE environment, if a run unit contains any HP COBOL program, then its main program must be a HP COBOL program. Native HP COBOL programs can call programs written in: • • • • Native HP C Native HP C++ Native HP COBOL pTAL External Names Within a run unit, no external data item can have the same name as any external file connector or any program. Ranges of Values The ranges of values for types NATIVE-2, NATIVE-4, and NATIVE-8 are: Type Lower Bound Upper Bound NATIVE-2 -32768 +32767 NATIVE-4 -2147483648 +2147483647 NATIVE-8 -9223372036854775808 +9223372036854775807 HP COBOL Manual for TNS and TNS/R Programs —522555-006 20- 7 HP COBOL Limits Ignored Elements The ranges of values for the type COMPUTATIONAL-5 are. Bracketed items are optional. Range PICTURE Clause NATIVE-n Equivalent Signed Unsigned PIC [S]9(1) PIC [S]9(4) NATIVE-2 -32,768 through 32,767 0 through 65,535 PIC [S]9(5) PIC [S]9(9) NATIVE-4 -2,147,483,648 through 2,147,483,647 0 through 4,294,967,295 PIC [S]9(10) PIC [S]9(18) NATIVE-8 -9,223,372,036,854,775,808 through 9,223,372,036,854,775,807 0 through 18,446,744,073,709,551,615 Ignored Elements HP COBOL compilers ignore these elements of COBOL because they are unnecessary in the HP implementation: • • In the entire source program: In ANSI format, columns 1 through 6 and beyond 72 Environment Division: ° ° In the SOURCE-COMPUTER paragraph: Source computer name In the OBJECT-COMPUTER paragraph: ° ° ° ° Object computer name MEMORY SIZE clause SEGMENT-LIMIT clause In the INPUT-OUTPUT section: ° In the FILE-CONTROL paragraph: in the file-control-entry : ° ° ° • In the ASSIGN clause: multiple file names In the SELECT clause: RECORD DELIMITER and PADDING CHARACTER clauses In the I-O-CONTROL paragraph: ° ° ° RERUN clause SAME AREA clause SAME SORT AREA clause Procedure Division ° ° In independent segments: SEGMENT-LIMIT ENTER COBOL statement HP COBOL Manual for TNS and TNS/R Programs —522555-006 20- 8 21 Reserved Words This section contains these alphabetized lists: • • All Reserved Words HP Reserved Words Figure 21-1. How Lists of Reserved Words Are Related All Reserved Words in HP COBOL New COBOL Reserved Words HP-Only Reserved Words VST522.vsd All Reserved Words This is an alphabetic list of all reserved words in HP COBOL. It includes new HP COBOL reserved words (additions to COBOL 74) and reserved words found only in HP COBOL (HP additions to COBOL). A B C D E F G H I J K L M N O P Q R S T U V W Z Special Characters A ACCEPT ACCESS ADD ADDRESS ADVANCING AFTER ALL ALPHABET ALPHABETIC ALPHABETIC-LOWER ALPHABETIC-UPPER ALPHANUMERIC ALPHANUMERIC-EDITED ALSO ALTER ALTERNATE AND ANY APPROXIMATE AREA HP COBOL Manual for TNS and TNS/R Programs —522555-006 21- 1 Reserved Words All Reserved Words AREAS ASCENDING ASSIGN AT AUTHOR B BEFORE BINARY BLANK BLOCK BOTTOM BY C CALL CANCEL CD CF CH CHARACTER CHARACTERS CHARACTER-SET CHECKPOINT CLASS CLOCK-UNITS CLOSE COBOL CODE CODE-SET COLLATING COLUMN COMMA COMMON COMMUNICATION COMP COMP-3 COMP-5 COMPUTATIONAL COMPUTATIONAL-3 COMPUTATIONAL-5 COMPUTE CONFIGURATION CONTAINS CONTENT CONTINUE HP COBOL Manual for TNS and TNS/R Programs —522555-006 21- 2 Reserved Words All Reserved Words CONTROL CONTROLS CONVERTING COPY CORR CORRESPONDING COUNT CURRENCY D DATA DATE DATE-COMPILED DATE-WRITTEN DAY DAY-OF-WEEK DE DEBUG-CONTENTS DEBUG-ITEM DEBUG-LINE DEBUG-SUB-2 DEBUG-SUB-3 DEBUGGING DECIMAL-POINT DECLARATIVES DEBUG-NAME DEBUG-SUB-1 DELETE DELIMITED DELIMITER DEPENDING DESCENDING DESTINATION DETAIL DISABLE DISPLAY DIVIDE DIVISION DOWN DUPLICATES DYNAMIC E EGI ELSE HP COBOL Manual for TNS and TNS/R Programs —522555-006 21- 3 Reserved Words All Reserved Words EMI ENABLE END END-ADD END-COMPUTE END-DELETE END-DIVIDE END-EVALUATE END-IF END-MULTIPLY END-OF-PAGE END-PERFORM END-READ END-RECEIVE END-RETURN END-REWRITE END-SEARCH END-START END-STRING END-SUBTRACT END-UNSTRING END-WRITE ENTER EOP EQUAL ERROR ESI EVALUATE EVERY EXCEPTION EXCLUSIVE EXIT EXTEND EXTENDED-STORAGE EXTERNAL F FALSE FD FILE FILE-CONTROL FILLER FINAL FIRST FOOTING FOR HP COBOL Manual for TNS and TNS/R Programs —522555-006 21- 4 Reserved Words All Reserved Words FROM FUNCTION G GENERATE GENERIC GIVING GLOBAL GO GREATER GROUP GUARDIAN-ERR H HEADING HIGH-VALUE HIGH-VALUES I I-O I-O-CONTROL IDENTIFICATION IF IN INDEX INDEXED INDICATE INITIAL INITIALIZE INITIATE INPUT INPUT-OUTPUT INSPECT INSTALLATION INTO INVALID IS J JUST JUSTIFIED HP COBOL Manual for TNS and TNS/R Programs —522555-006 21- 5 Reserved Words All Reserved Words K KEY L LABEL LAST LEADING LEFT LENGTH LESS LIMIT LIMITS LINAGE LINAGE-COUNTER LINE LINE-COUNTER LINKAGE LOCK LOCKFILE LOW-VALUE LOW-VALUES M MEMORY MERGE MESSAGE MODE MODULES MOVE MULTIPLE MULTIPLY N NATIVE NEGATIVE NEXT NO NOT NULL NULLS NUMBER NUMERIC NUMERIC-EDITED HP COBOL Manual for TNS and TNS/R Programs —522555-006 21- 6 Reserved Words All Reserved Words O OBJECT-COMPUTER OCCURS OF OFF OMITTED ON OPEN OPTIONAL OR ORDER ORGANIZATION OTHER OUTPUT OVERFLOW P PACKED-DECIMAL PADDING PAGE PAGE-COUNTER PERFORM PF PH PIC PICTURE PLUS POINTER POSITION POSITIVE PRINTING PROCEDURE PROCEDURES PROCEED PROGRAM PROGRAM-ID PROGRAM-STATUS PROGRAM-STATUS-1 PROGRAM-STATUS-2 PROMPT PROTECTED PURGE HP COBOL Manual for TNS and TNS/R Programs —522555-006 21- 7 Reserved Words All Reserved Words Q QUEUE QUOTE QUOTES R RANDOM RD READ RECEIVE RECEIVE-CONTROL RECORD RECORDS REDEFINES REEL REFERENCE REFERENCES RELATIVE RELEASE REMAINDER REMOVAL RENAMES REPLACE REPLACING REPLY REPORT REPORTING REPORTS RERUN RESERVE RESET RETURN REVERSED REWIND REWRITE RF RH RIGHT ROUNDED RUN S SAME SD SEARCH HP COBOL Manual for TNS and TNS/R Programs —522555-006 21- 8 Reserved Words All Reserved Words SECTION SECURITY SEGMENT SEGMENT-LIMIT SELECT SEND SENTENCE SEPARATE SEQUENCE SEQUENTIAL SET SHARED SIGN SIZE SORT SORT-MERGE SOURCE SOURCE-COMPUTER SPACE SPACES SPECIAL-NAMES STANDARD STANDARD-1 STANDARD-2 START STARTBACKUP STATUS STOP STRING SUB-QUEUE-1 SUB-QUEUE-2 SUB-QUEUE-3 SUBTRACT SUM SUPPRESS SYMBOLIC SYNC SYNCDEPTH SYNCHRONIZED T TABLE TAL TALLYING TAPE TERMINAL HP COBOL Manual for TNS and TNS/R Programs —522555-006 21- 9 Reserved Words All Reserved Words TERMINATE TEST TEXT THAN THEN THROUGH THRU TIME TIMES TO TOP TRAILING TRUE TYPE U UNIT UNLOCK UNLOCKFILE UNLOCKRECORD UNSTRING UNTIL UP UPON USAGE USE USING V VALUE VALUES VARYING W WHEN WITH WORDS WORKING-STORAGE WRITE Z ZERO ZEROES HP COBOL Manual for TNS and TNS/R Programs —522555-006 21 -10 Reserved Words HP Reserved Words Special Characters + * / ** < > = HP Reserved Words This is an alphabetic list of reserved words found only in HP COBOL (HP additions to COBOL). ACEGLNPRSTU A ADDRESS APPROXIMATE C CHARACTER-SET CHECKPOINT COMP-3 COMP-5 COMPUTATIONAL-3 COMPUTATIONAL-5 E EXCLUSIVE EXTENDED-STORAGE G GENERIC GUARDIAN-ERR L LOCKFILE HP COBOL Manual for TNS and TNS/R Programs —522555-006 21 -11 Reserved Words HP Reserved Words N NULL NULLS P PROGRAM-STATUS PROGRAM-STATUS-1 PROGRAM-STATUS-2 PROMPT PROTECTED R RECEIVE-CONTROL REPLY S SHARED STARTBACKUP SYNCDEPTH T TAL U UNLOCK UNLOCKFILE UNLOCKRECORD HP COBOL Manual for TNS and TNS/R Programs —522555-006 21 -12 Part II. Programming in HP COBOL Title Section 22, Creating and Compiling HP COBOL Source Programs Section 23, Calling Other Programs and Routines Section 24, Issues Related to Binding and Linking Section 25, Executing and Debugging HP COBOL Programs Section 26, Input and Output Concepts Section 27, Tape Input and Output Section 28, Disk Input and Output Section 29, Terminal Input and Output Section 30, Printer and Spooler Output Section 31, Process Initiation, Communication, and Management Section 32, Fault-Tolerant Processes Section 33, Migrating TNS Programs to Native Programs Section 34, Native COBOL Cross Compiler on PC HP COBOL Manual for TNS and TNS/R Programs —522555-006 Part II. Programming in HP COBOL HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 Creating and Compiling HP COBOL Source Programs Note. This section applies primarily to the Guardian environment. If you are compiling HP COBOL programs in the OSS environment, see Section 19, Using HP COBOL in the OSS Environment. Topics: • • • • • • • • • Using the TACL Command Log Creating or Altering an HP COBOL Source Program Compiling an HP COBOL Source Program Using COPY and SOURCE Libraries Creating or Altering a COPY or SOURCE Library Including Text From a COPY Library Including Text From a SOURCE Library Replacing Text-Words in an HP COBOL Source Program Understanding and Controlling the Compiler Listing If you want to include SQL/MP or SQL/MX commands in your HP COBOL program, see the SQL/MP Programming Manual for COBOL or the SQL/MX Programming Manual for C and COBOL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22- 1 Creating and Compiling HP COBOL Source Programs Using the TACL Command Log Using the TACL Command Log When you log onto an HP system, the HP Tandem Advanced Command Language (TACL) prompt appears. The TACL prompt includes the command number, which starts at 1: 1> Topics: • • • Displaying Previous Commands Reexecuting Previous Commands Editing and Reexecuting Previous Commands Displaying Previous Commands TACL maintains a chronological log of previously entered commands, which you can display with the HISTORY command. Suppose that you have entered these TACL commands (notice the command number in each of the prompts): 1> 2> 3> 4> who fileinfo view myfile history Command 4, history, displays: 1> 2> 3> 4> 5> who fileinfo view myfile history If you enter a question mark (?), TACL displays the last command: 5> ? 5> history 5> If you enter a question mark followed by a number, TACL displays the command with that number: 5> ?2 5> fileinfo 5> If you enter a question mark followed by text, TACL displays the most recent command that begins with that text: 5> ?v 5> view myfile 5> HP COBOL Manual for TNS and TNS/R Programs —522555-006 22- 2 Creating and Compiling HP COBOL Source Programs Reexecuting Previous Commands Reexecuting Previous Commands If you enter an exclamation mark (!), TACL displays and executes the last command: 5> 5> 1> 2> 3> 4> 5> 6> ! history who fileinfo view myfile history history If you enter an exclamation mark followed by a number, TACL displays and executes the command with that number: 6> 6> 1> 2> 3> 4> 5> 6> 7> !4 history who fileinfo view myfile history history history If you enter an exclamation mark followed by text, TACL displays and executes the most recent command that begins with that text: 7> !v 7> view myfile 8> HP COBOL Manual for TNS and TNS/R Programs —522555-006 22- 3 Creating and Compiling HP COBOL Source Programs Editing and Reexecuting Previous Commands Editing and Reexecuting Previous Commands If you enter the command FC, TACL displays the last command so that you can edit it: 8> fc 8> view myfile 8... You can edit the displayed command (view myfile) with the commands D (delete), I (insert), and R (replace). When you press Return, TACL displays the edited command. You can continue to edit the command or press Return. When you press Return without editing the command, TACL executes the command. 8> fc 8> view 8.. 8> view 8.. 8> view 8.. 8> view 8.. 8> view 8... myfile dd file isrc srcfile r1 srcfil1 e1 srcfile1 The absence of a D, I, or R command is handled as an R command (last change in the preceding example). If you enter the FC command followed by a number, TACL displays the command with that number so that you can edit it: 9> fc 2 9> fileinfo 9... If you enter the FC command followed by text, TACL displays the most recent command that begins with that text so that you can edit it: 10> fc view 10> view srcfile1 10... TACL also allows you to program the function keys on your terminal and write macros. For more information about TACL, see the TACL Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22- 4 Creating and Compiling HP COBOL Source Programs Creating or Altering an HP COBOL Source Program Creating or Altering an HP COBOL Source Program The compiler accepts source lines from any sequential file. On NonStop systems, the most common way to create or alter a HP COBOL source program is to use an HP editor or Starbase Corporation’s Codewright smart language editor with HP Extensions for Codewright. HP offers two editors, EDIT and PS TEXT EDIT (abbreviated “TEDIT”). Both editors create and allow you to alter the same type of file, the EDIT format file (abbreviated “EDIT file”). Both HP editors and Codewright smart language editor allow you to: • • • • • • • • Create a new file Enter lines in a file Copy lines from one file into another file Move lines from one place in a file to another place in the same file Duplicate lines from one place in a file to another place in the same file Delete lines from a file Change one portion of text to another throughout a range of lines in a file List the lines that a file contains Whether or not you use an HP editor, your HP COBOL source file must conform to a reference format that the compiler accepts. Topics: • • • • • EDIT Files Reference Format EDIT Editor TEDIT Editor HP Tandem Extensions for Codewright (TEC) EDIT Files An EDIT format file (abbreviated “EDIT file”) is a specially formatted disk file. It is the only type of file that the EDIT and TEDIT editors create or alter. The file-code value that the EDIT or TEDIT editor assigns to an EDIT file is 101. To use the EDIT or TEDIT editor on the contents of a non-EDIT file, create a new EDIT file and copy the text of the non-EDIT file into it. For more information about EDIT files, see the EDIT User’s Guide and Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22- 5 Creating and Compiling HP COBOL Source Programs Reference Format Reference Format Individual source program lines must follow a reference format that the compiler accepts. There are two choices of reference format: Tandem and ANSI. Tandem format, an HP extension to COBOL, is less restrictive than ANSI. The principal differences between the Tandem and ANSI formats are in: • • • • Margin locations Permitted line lengths Absence of sequence number and identification field in Tandem format Continuation lines Figure 22-1. Tandem Reference Format Margin: C A Column: B 1 2 3 4 R 5 6 7 8 9 10 ... n* Area A *n <= 132 Area B Indicator Area Line VST500.vsd Figure 22-2. ANSI Reference Format Margin: L Column: C 1 2 3 4 Sequence Number Area A 5 6 7 8 B R 9 10 11 12 ... 72 73 ... 80 Area A Indicator Field Area B Identification Field Line VST524.vsd You can write a COBOL source program entirely in either format or in a mixture of both. The default is Tandem format. Unless you direct the compiler to accept ANSI format, the compiler assumes the entire program is in Tandem format. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22- 6 Creating and Compiling HP COBOL Source Programs EDIT Editor EDIT Editor The EDIT editor is not as powerful as the TEDIT editor, but it has some useful abilities that TEDIT either lacks or does not perform as simply. Examples of both cases are in this explanation. Caution. The EDIT editor works on your original file, not on a copy of it. If you want to provide for the possibility of discarding an entire editing session, you must make a backup copy yourself; that is, the EDIT editor does not automatically create a backup file. You can make the backup copy with the EDIT command PUT. To call the EDIT editor, type its name at the TACL prompt (case is unimportant): 93> EDIT The EDIT editor identifies itself (including version and RVU date) and prompts you with an asterisk: TEXT EDITOR - T9601D10 - (08JUN92) * To retrieve an EDIT file to work on (in this example, PAYROLS), use the GET command: *GET PAYROLS CURRENT FILE IS \NODE1.$VOL3.SUBVOL2.PAYROLS You can also call the EDIT editor with a file name: 94> EDIT PAYROLS TEXT EDITOR - T9601D10 - (08JUN92) CURRENT FILE IS \NODE1.$VOL3.SUBVOL2.PAYROLS To retrieve lines from a non-EDIT file (in this example, PAYROLXX) and put them into an EDIT file (in this example, PAYROLS), use the GET and PUT commands together: *GET PAYROLXX PUT PAYROLS (With the TEDIT editor, you cannot combine the GET and PUT commands.) If the file PAYROLS already exists, the EDIT editor asks you whether it should purge the old PAYROLS (that is, overwrite its current text with the new text from PAYROLXX, keeping the name PAYROLS for the file): *GET PAYROLXX PUT PAYROLS SHALL I PURGE THE OLD \NODE1.$VOL3.SUBVOL2.PAYROLS? If you tell the EDIT editor not to delete PAYROLS, the EDIT editor asks you for a new name for the EDIT file: SHALL I PURGE THE OLD \NODE1.$VOL3.SUBVOL2.PAYROLS? NO NAME THE NEW FILE: PAYROLS2 CURRENT FILE IS \NODE1.$VOL3.SUBVOL2.PAYROLS2 HP COBOL Manual for TNS and TNS/R Programs —522555-006 22- 7 Creating and Compiling HP COBOL Source Programs TEDIT Editor If you are sure that you want to overwrite PAYROLS, you can avoid the question-andanswer routine by following PAYROLS with an exclamation mark: *GET PAYROLXX PUT PAYROLS! CURRENT FILE IS \NODE1.$VOL3.SUBVOL2.PAYROLS Another convenience the EDIT editor provides that the TEDIT editor lacks is the ability to list all lines that contain two or more combinations of text characters in any order. Although the TEDIT editor has some powerful pattern-matching abilities, it is much easier to find all lines containing both ABC and XYZ, in any order, using the EDIT editor. The EDIT editor has a line editor and a full-screen editor. The full-screen editor is named VS. If VS terminates abnormally, it creates a recovery file whose name is of the form ZZVSnnnn (where nnnn is a four-digit number chosen by VS to make a unique file name). To detect these ZZVSnnnn files, use the TACL command FILES. Purge any ZZVSnnnn files that you do not need. To exit the EDIT editor, type “exit” in response to the asterisk prompt (case is unimportant): *EXIT 95> For complete information about the EDIT editor, see the EDIT User’s Guide and Reference Manual. TEDIT Editor The TEDIT editor is a full-screen editor with a command line. Overall, the TEDIT editor is more powerful than the EDIT editor. The TEDIT commands SEARCH and REPLACE have powerful pattern-matching abilities, with single-character, multicharacter, and setof-characters wild cards. Caution. The TEDIT editor works on your original file, not on a copy of it. If you want to provide for the possibility of discarding an entire editing session, you must make a backup copy yourself. You can make the backup copy before editing the file, with the File Utility Program (FUP) DUP command, or you can use the WRITE command from within the TEDIT editor to make a copy at any time. To call the TEDIT editor, type its name at the TACL prompt (case is unimportant): 81> TEDIT The TEDIT editor clears the screen and displays a help screen that explains its function. At the bottom of the help screen, it asks you for a file name: (To EXIT press CTRL-Y) File: PAYROLS You can also call the TEDIT editor with a file name: 82> TEDIT PAYROLS HP COBOL Manual for TNS and TNS/R Programs —522555-006 22- 8 Creating and Compiling HP COBOL Source Programs TEDIT Editor If you call the TEDIT editor with a file name, it does not display the help screen. If the file you specified exists, the TEDIT editor clears the screen and displays the first 24 lines of the file and a banner on line 25. The banner contains: • • • • The window number (you can open a second window) The file name, fully qualified with node, volume, and subvolume names The range of lines displayed (with “(BOF)” if you are at the beginning of the file and “(EOF)” if you are at the end of the file) The version of the TEDIT editor you are using Example 22-1. TEDIT Banner 1) \NODE1.$VOL3.SUBVOL2.PAYROLS 1/24 (BOF) 1:79 D20. If the TEDIT editor cannot find the PAYROLS file, it clears the screen and displays: \NODE1.$VOL3.SUBVOL2.PAYROLS doesn’t exist. OK to create? Respond Y or N: To exit the TEDIT editor, press Shift and F16 simultaneously. These topics briefly describe the TEDIT editor’s second window, commands, and customizing. For complete information about the TEDIT editor, see the PS TEXT EDIT Reference Manual and the PS TEXT EDIT and PS TEXT FORMAT User’s Guide. Topics: • • • Second Window TEDIT Commands Customizing the TEDIT Editor Second Window The TEDIT editor allows you to open a second window. Some of the tasks that the TEDIT editor allows you to do with two windows are: • • • • • Display two parts of the same file (such as the first 10 lines and the last 10 lines) Display two different files (such as the source text and a COPY library) Copy text from one window to the other Display only window 1, only window 2, or both windows Close one window and open it to a third file HP COBOL Manual for TNS and TNS/R Programs —522555-006 22- 9 Creating and Compiling HP COBOL Source Programs TEDIT Editor TEDIT Commands Most TEDIT commands consist of a noun (such as LINE, SENTENCE, WINDOW, BALANCED-EXPRESSION, or REGION) and a verb (such as INSERT, MOVE, COPY, DELETE, FORWARD, BACKWARD, SEARCH, REPLACE, or UNDO). Some TEDIT commands also include a repeat count or parameters. Many nouns and verbs are persistent—that is, you can specify a noun (such as LINE) and apply a series of verbs to it (such as COPY, MOVE, DELETE), or you can specify a verb and apply a series of nouns to it; for example, the command DELETE; LINE; LINE; LINE deletes the line the cursor is on and the two lines after it. You execute TEDIT commands in two ways: • • Press predefined command keys and key combinations (see the TEDIT keyboard template for your terminal). Type the commands on the command line and press Return (to access the command line, press Shift and Return simultaneously, or use the key specified by the TEDIT keyboard template for your terminal). If a command requires parameters and you do not supply them, the TEDIT editor prompts you for them. SEARCH and REPLACE are examples of TEDIT commands that require parameters. Customizing the TEDIT Editor Some ways in which you can customize the TEDIT editor are: • • • You can write macros that perform complex tasks with few keystrokes. With the RECONFIGURE KEYS command, you can redefine the default keys. With the RECONFIGURE OPTIONS command, you can do such things as reset your tab stops and define delimiter pairs. You can define up to 10 delimiter pairs, such as left and right parentheses and the commonly used HP COBOL keyword pairs, such as IF and END-IF. If you establish IF and END-IF as the delimiters of a balanced expression, you can use FORWARD BALANCE-EXPRESSION to move the cursor from an IF to its corresponding ENDIF. • • You can save your redefined option set in your TEDIT user profile and recall it whenever you want it with the TEDIT command USEPROFILE. You can define different option sets for distinct programming tasks. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -10 Creating and Compiling HP COBOL Source Programs HP Tandem Extensions for Codewright (TEC) HP Tandem Extensions for Codewright (TEC) Starbase Corporation’s Codewright is a smart language editor that allows you to edit source code and issue compiler, version-control, and operating-system commands. The base editor facilitates source code creation with keyword chromacoding, search and replace mechanisms, function execution, undo and redo commands, and general editing capabilities. Codewright blends a command shell with its own tools, and you can easily extend it to work with other third-party tools or dynamic link libraries that you build with your own compiler language. HP has taken advantage of this extensibility to create HP Tandem Extensions for Codewright (TEC). The main features of TEC are: • • • • • • Language-Sensitive Programming Support Dictionaries and Templates Chromacoding Project Definition Viewing Source Files Comment Headers and Parameter Documentation More information on TEC is available through its online help. Language-Sensitive Programming Support TEC provides language-specific menus to support the coding of these HP languages: • • • • HP C and HP C++ COBOL pTAL and TAL TACL When you open a source file, the appropriate language-specific menu appears on the menu bar. For all languages, you can search (GREP) commands in the file, keywords are chromacoded (see Chromacoding), and you can save function call parameters in the dictionary for later use (see Dictionaries and Templates). For HP C and HP C++, you can create or insert modules or work with #PRAGMAS and #INCLUDES. For HP C++, you have additional support for creating classes and class members. For COBOL, you can view source code by paragraph and search (GREP) by paragraph. For pTAL and TAL, you can generate HP C prototypes from TAL procedures by pointing and clicking; insert ?PROC, ?SECTION, or ?PAGE; and check references. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -11 Creating and Compiling HP COBOL Source Programs HP Tandem Extensions for Codewright (TEC) Dictionaries and Templates TEC maintains four project dictionaries: user, parameter, class, and system. Information can be stored and retrieved from these dictionaries and used in conjunction with comment generation (see Comment Headers and Parameter Documentation). You can define text templates that contain values for function parameters. The values are defined when you insert the template into the dictionary. When you direct TEC to call a function, TEC calls it with the parameter values that you specified. Chromacoding Language-dependent chromacoding enables you to select colors to enhance the visibility of comments, keywords, strings, numbers, preprocessor commands, changed lines, and braces. You can set the colors you select in Document Preferences in TEC version 3.0. Project Definition In addition to the basic project information supplied by Codewright itself, TEC allows you to define and change a set of dictionary specifications and search directories to facilitate locating source files. Viewing Source Files TEC allows you to view or collapse source files by function, #PRAGMA, paragraph, or normal view. This feature helps you to locate code quickly by higher-level code segments and to provide a call map of the selected module. After you have located the code, you can return the source program to its normal expanded view. Comment Headers and Parameter Documentation TEC allows you to automatically create and maintain information in comment boxes, particularly for the beginning and end of each module. After you have entered parameters into the parameter/comment dictionary (by pointing and clicking), TEC automatically retrieves their definitions for building other parameter list comment boxes. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -12 Creating and Compiling HP COBOL Source Programs Compiling an HP COBOL Source Program Compiling an HP COBOL Source Program The COBOL85 and NMCOBOL compilers translate HP COBOL source programs into machine language. The COBOL85 compiler interacts with Binder, which collects any additional object programs needed to satisfy external references and validates any calls to routines that are part of the operating environment or are to be executed in a TNS user library. The NMCOBOL compiler does not interact with the ld utility, but if you specify the CALL-SHARED and RUNNABLE directives, and there are no compilation errors, the NMCOBOL compiler calls the ld utility, which produces a PIC loadfile. If you specify the SHARED and RUNNABLE directives, and there are no compilation errors, the NMCOBOL compiler calls the ld utility, which produces a DLL. From the user’s viewpoint, compilation is a single-step process. (If you are interested in the details of the compilation process, see Compilation Details. Caution. (This applies only to the COBOL85 compiler.) If the file C8LIB, the run-time library, is present in the same subvolume as the compiler, the run-time routines are bound into the object. This feature can cause the object to be as much as 10 times larger than it would otherwise be; it can also cause failures and other serious problems when running on systems other than the one on which the program was compiled. This feature is intended for use by HP COBOL developers and support groups only. Topics: • • • • • • • • Running the Compiler Naming the Object File Specifying the Default COPY Library Specifying Compiler Directives Specifying Subvolumes to Be Searched for Unqualified Files Changing the Compilation Environment Improving Compilation Speed Launching Compilations to Run Unattended Running the Compiler To run the COBOL85 or NMCOBOL compiler, use the COBOL85 or NMCOBOL command. Specify the name of the file containing the source program or programs that you want to compile; for example: 23> COBOL85 /IN XYZ/ 23> NMCOBOL /IN XYZ/ HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -13 Creating and Compiling HP COBOL Source Programs Running the Compiler The preceding NMCOBOL command produces a loadfile only if the source file, XYZ, contains a RUNNABLE directive. If it does not, the command that produces a loadfile is: 23> NMCOBOL /IN XYZ/; RUNNABLE The file XYZ must be an EDIT or entry-sequenced file. 24> COBOL85 /IN XYZ/ 24> NMCOBOL /IN XYZ/; RUNNABLE The preceding commands deliver the compiler listing to your terminal. To send the compiler listing to spooler collector $SPX for printing instead, you must specify the OUT parameter: 25> COBOL85 /IN XYZ, OUT $SPX/ 25> NMCOBOL /IN XYZ, OUT $SPX/; RUNNABLE The preceding commands send the compiler listing to the default location of spooler collector $SPX. To specify another location, such as #LPPR, include the location in the OUT parameter: 26> COBOL85 /IN XYZ, OUT $SPX.#LPPR/ 26> NMCOBOL /IN XYZ, OUT $SPX.#LPPR/; RUNNABLE If spooler collector $SPX recognizes location #LPPR, the compiler listing is queued for printing. If you want to examine the compiler listing before printing it, specify a fictitious location, such as #XYZLST: 27> COBOL85 /IN XYZ, OUT $SPX.#XYZLST/ 27> NMCOBOL /IN XYZ, OUT $SPX.#XYZLST/; RUNNABLE Using the PERUSE utility, list the last page of the compiler listing (the last page is a compilation summary). If the summary reports errors, use an HP editor to fix the source program and then recompile it (remember to delete the compiler listing from the spooler collector). If the summary does not report errors, change its location to an existing printer. You delete the compiler listing from the spooler collector or change its location to an existing printer from within the PERUSE utility. For information about the PERUSE utility, see Using PERUSE and the Guardian User’s Guide. Note. For easier ways to check a program for syntax errors, see Directives for Syntax Checking Only. If you want to compile a source program without producing a listing file, specify an empty OUT file for the COBOL85 compiler: 28> COBOL85 /IN XYZ, OUT / The preceding commands cause any listing lines that the compiler generates to be discarded. The NMCOBOL compiler does not accept an empty OUT file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -14 Creating and Compiling HP COBOL Source Programs Running the Compiler To specify a file for information about any compilation errors or warnings, use the ERRORFILE directive: 29> COBOL85 /IN XYZ, OUT $SPX.#XYZLST/; ERRORFILE EFILE 29> NMCOBOL /IN XYZ, OUT $SPX.#XYZLST/; RUNNABLE; ERRORFILE EFILE The error logging file is not an EDIT file. You can use it only with the FIXERRS TACL macro. For more information about the FIXERRS macro, see FIXERRS Macro. For more information about the ERRORFILE directive, see ERRORFILE. IN and OUT are options of the TACL command RUN. Other RUN command options that you might find useful when compiling HP COBOL programs are: • NOWAIT If you specify COBOL85 /IN XYZ, OUT $SPX.#LPPR, NOWAIT/ or NMCOBOL /IN XYZ, OUT $SPX.#LPPR, NOWAIT/; RUNNABLE the TACL program does not wait while the compiler runs, but returns a TACL prompt after starting the compiler. (The compiler runs in the background.) • CPU If you specify COBOL85 /IN XYZ, OUT $SPX.#LPPR, CPU 7/ or NMCOBOL /IN XYZ, OUT $SPX.#LPPR, CPU 7/; RUNNABLE the compiler runs in processor seven (processors are numbered from 0 through 15). For more information about these and additional RUN commands, see the TACL Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -15 Creating and Compiling HP COBOL Source Programs Naming the Object File Using an HP editor, you can create OBEY command files. OBEY command files contain TACL commands, such as the COBOL85 or NMCOBOL commands, which are executed when you specify the name of the OBEY command file in an OBEY command. Here is a sample session: 45> EDIT CFILE1 TEXT EDITOR - T9601D10 - (08JUN92) $VOL3.SUBVOL2.CFILE1 DOES NOT EXIST. SHALL I CREATE IT? Y CURRENT FILE IS $VOL3.SUBVOL2.CFILE1 *ADD 1 COBOL85 /IN XYZ,OUT $SPX.#HOLD/ 2 // *EXIT 46> OBEY CFILE1 The command OBEY CFILE1 causes execution of the command: COBOL85 /IN XYZ,OUT $SPX.#HOLD/ An OBEY command file can contain more than one command. If another OBEY command file, CFILE2, contains the commands COBOL85 /IN XYZ,OUT $SPX.#HOLD/ PERUSE the command OBEY CFILE2 is equivalent to the command series 47> COBOL85 /IN XYZ,OUT $SPX.#HOLD/ 48> PERUSE For more information about OBEY command files, see the Guardian User’s Guide. Naming the Object File To simplify the compilation examples in the preceding topic, no name is specified for the object file that the compiler produces. In these examples, the object file is given the default name RUNUNIT. To specify a name for the object file, type the name after the final slash, as in this example, which names the object file XYZOBJ: 88> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ 88> NMCOBOL /IN XYZ, OUT $SPX/ XYZOBJ; RUNNABLE Although program compilation is a single-step process from the user’s viewpoint, producing a loadfile actually involves Binder (for the COBOL85 compiler) or the linker (for the NMCOBOL compiler). Binder or the linker resolves the external references in CALL and ENTER statements and the implicit calls to HP COBOL run-time library routines that many HP COBOL statements cause. During most of the time that the COBOL85 compiler executes, Binder runs as a separate process called BINSERV. The COBOL85 compiler communicates with BINSERV through interprocess messages. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -16 Creating and Compiling HP COBOL Source Programs Naming the Object File If you specify the CALL-SHARED and RUNNABLE directives, and there are no compilation errors, the NMCOBOL compiler calls the ld utility, which produces a PIC loadfile. If you specify the SHARED and RUNNABLE directives, and there are no compilation errors, the NMCOBOL compiler calls the ld utility, which produces a DLL. Binder does the actual building of the object file. If there are no compilation or binding or linking errors, and file XYZOBJ either does not exist or is secured such that Binder can purge it, Binder puts the new version of XYZOBJ on the disk. If you do not specify a name for the object file, Binder or the compiler uses the default name RUNUNIT. Binder tries these names, in this order: 1. ZZBInnnn, where nnnn is a sequence of randomly chosen alphanumeric characters 2. OBJECT Binder can name the new object file OBJECT only if no file named OBJECT already exists. If a file named OBJECT already exists, Binder names the new object file ZZBInnnn. The NMCOBOL compiler: 1. If the object file already exists and it is not a code 700 file, the compiler attempts to create the file named OBJECT. If this file exists or is open by another process, the compiler creates a file named ZZNCnnnn, where nnnn is a sequence of randomly chosen alphanumeric characters. 2. If the object file already exists and is a code 700 file and is not open by another process, it is purged and a new one is created. 3. If the object file is open by another process, the compiler renames the existing file, giving it the name ZZNCnnnn where nnnn is a sequence of randomly chosen alphanumeric characters. The specified object file is then created. If the existing object file cannot be renamed, the compilation terminates. The NMCOBOL compiler tries the name ZZNCnnnn, where nnnn is a sequence of randomly chosen alphanumeric characters. If the ZZNCnnnn name that the NMCOBOL compiler tries already exists, the compiler tries another one (with a different sequence of randomly chosen alphanumeric characters). The compiler tries several different ZZNCnnnn names if necessary, but does not keep trying indefinitely. If the compiler stops trying to name the object file, verify that you have create access to the designated subvolume. Suppose that you specify the name OBJFILE for the object file, but the operating environment is executing a process from a file named OBJFILE. Binder or the NMCOBOL compiler cannot replace the executing version of OBJFILE, so Binder or the linker renames the old object file ZZBInnnn or ZZNCnnnn, respectively, and names the new object file OBJFILE as you specified. The next user who executes the object program named OBJFILE executes the new object file, even if another user is still executing the old, renamed one. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -17 Creating and Compiling HP COBOL Source Programs Specifying the Default COPY Library Use the TACL command FILES to detect ZZBInnnn or ZZNCnnnn files and the TACL command PURGE to purge the unwanted ones. Specifying the Default COPY Library The default COPY library is the library from which COPY statements read text when no library name is specified in the COPY statement. If you do not specify the default COPY library (as in the compilation examples in the preceding topic), then COPYLIB is the default COPY library. To specify a different default COPY library, such as COPLIB2, include its name in the compilation command: 89> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ, COPLIB2 89> NMCOBOL /IN XYZ, OUT $SPX/ XYZOBJ, COPLIB2 For more information about COPY libraries, see Using COPY and SOURCE Libraries. Specifying Compiler Directives Compiler directives can be included in the source program or specified in the compilation command. To specify compiler directives (such as NOFIPS and NOWARN) in the compilation command, put them at the end of the compilation command, as in this example (note the semicolons): 90> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ, COPLIB2;NOFIPS;NOWARN 90> NMCOBOL /IN XYZ, OUT $SPX/ XYZOBJ, COPLIB2;NOFIPS;NOWARN Compiler directives specified in this way are considered to be on line zero of the source program. Most of them stay active until the compiler encounters a conflicting directive later in the source program, but it depends on the directive. For information about specific directives, see Compiler Directives. Directives for Syntax Checking Only If you compile your program with the SYNTAX directive, the compiler only checks its syntax and does not generate object code. Because the compiler does not generate object code, it runs much faster (but only if there are no errors). 90> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ, COPLIB2; SYNTAX 90> NMCOBOL /IN XYZ, OUT $SPX/ XYZOBJ, COPLIB2; SYNTAX Another way to find syntax errors in your program is with the FIXERRS macro, which requires that you compile your program with the ERRORFILE directive. For more information about the FIXERRS macro, see FIXERRS Macro. For more information about the ERRORFILE directive, see ERRORFILE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -18 Creating and Compiling HP COBOL Source Programs Specifying Subvolumes to Be Searched for Unqualified Files Directive for Specifying the Program’s Run-Time Environment Note. This topic applies only to TNS programs. Native programs always run in the CRE. For TNS programs in the Guardian environment, you have a choice of run-time environments: the non-CRE environment or the CRE. The CRE is recommended for mixed-language programs, because it puts fewer restrictions on them and they execute more efficiently (see Run-Time Environment). By default, the COBOL85 compiler produces object code that executes in the non-CRE environment. To make the COBOL85 compiler produce object code that executes in the CRE, use the compiler directive ENV with the option COMMON, like this: 90> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ, COPLIB2; ENV COMMON Specifying Subvolumes to Be Searched for Unqualified Files In your HP COBOL source program, an unqualified file is a file whose name does not contain a volume and subvolume. It can be a source file (as in a COPY statement) or an object file (as in an ENTER statement). Two DEFINEs allow you to specify one or more subvolumes for the compiler to search for unqualified files: • • =_SOURCE_SEARCH (for unqualified source files) =_OBJECT_SEARCH (for unqualified object files) These DEFINEs have CLASS attribute SEARCH. Use them by entering ADD DEFINE commands before compiling your program, as in this example. (An ampersand at the end of a line means that the TACL command continues on the next line.) 91> 91> 92> 92> 93> 93> ADD DEFINE =_SOURCE_SEARCH, CLASS SEARCH, SUBVOL0& (=_DEFAULTS,$VOL1.SUB2,$VOL1.SUB3) ADD DEFINE =_OBJECT_SEARCH, CLASS SEARCH, SUBVOL0& (=_DEFAULTS,$VOL2.SUB1,$VOL2.SUB2) COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ NMCOBOL /IN XYZ, OUT $SPX/ XYZOBJ In the preceding example, the compiler will search for unqualified source files on the default subvolume first, then on $VOL1.SUB2, and finally on $VOL1.SUB3. The compiler will search for unqualified object files on the default subvolume first, then on $VOL2.SUB1, and finally on $VOL2.SUB2. Suppose that you want to add the subvolume $VOL3.SUB1 to the _SOURCE_SEARCH list. Use an ADD DEFINE command whose SUBVOLn parameter has n greater than 0 (the value of n in the preceding example): 94> ADD DEFINE =_SOURCE_SEARCH, CLASS SEARCH, SUBVOL1& 94> ($VOL3.SUB1) Now the compiler will search for unqualified source files on these subvolumes in this order: default subvolume, $VOL1.SUB2, $VOL1.SUB3, $VOL3.SUB1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -19 Creating and Compiling HP COBOL Source Programs Changing the Compilation Environment Changing the Compilation Environment You can change these aspects of the compilation environment: • • • Processors the Compilation Processes Use Volume(s) for Temporary Files Compiler Space Allocation Processors the Compilation Processes Use Note. This topic applies only to the COBOL85 compiler. Although program compilation is a single-step process from the user’s viewpoint, a COBOL85 compilation consists of three processes: Process Description COBOL85 Reads the source program (processing any COPY statements and SOURCE directives), produces listings, and generates object code for binding BINSERV Binds object code and generates Binder listings SYMSERV Builds a symbol table that a symbolic debugger, CROSSREF directive, and Crossref utility can use The compilation environment is the environment in which the COBOL85, BINSERV, and SYMSERV processes run. By default, COBOL85 and BINSERV run in the same processor, and SYMSERV runs in the processor with the next higher number (for example, if COBOL85 and BINSERV run in processor 7, then SYMSERV runs in processor 8). If there is no processor with the next higher number, then SYMSERV runs in the processor with the lowest number. The PARAM SAMECPU command causes COBOL85, BINSERV, and SYMSERV to run in the same processor. Using PARAM SAMECPU can improve compilation speed if either or both of the processors that the compilation would use by default are very busy. The processors that the compilation would use by default are determined by the TACL option CPU, which is explained in the Guardian User’s Guide. The PARAM SAMECPU command requires a dummy-value parameter, which must be a nonzero value. dummy-value does not determine the processor; like the default processor, this processor is determined by the TACL option CPU. In this example, dummy-value is 7. The processes COBOL85, BINSERV, and SYMSERV will run in the same processor, but it will not necessarily be processor 7. 91> PARAM SAMECPU 7 92> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -20 Creating and Compiling HP COBOL Source Programs Changing the Compilation Environment If you have given the command PARAM SAMECPU and decide that you do not want it, you can clear it with the CLEAR command before running the compiler; for example: 91> PARAM SAMECPU 7 92> CLEAR PARAM SAMECPU 93> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ Volume(s) for Temporary Files By default, the COBOL85 compiler creates its temporary files on the current default volume. The BINSERV and SYMSERV processes create their temporary files on the volume where the target file is located, unless that volume is on another node. If the volume is on another node, the BINSERV and SYMSERV processes create their temporary files on the current default volume of the node on which they execute. For example, suppose you are executing on \MYSYS and your default volume is $CURR. If you execute the command: COBOL85 /IN MYSRC, OUT $S.#MYLST/ \ALIEN.$FAR.XX.MYOBJ the BINSERV and SYMSERV processes use $CURR for any temporary files, instead of using volume $FAR on system \ALIEN. By default, the NMCOBOL compiler creates its temporary files on the current default volume. If called by the NMCOBOL compiler, the processes COBOLFE, UGEN, and AS1 and the linker create their temporary files on the current default volume. The PARAM SWAPVOL command specifies the volume on which the compiler and its processes will create temporary files (if possible). It does not determine where the operating system creates the compiler’s own swap file—the Kernel-Managed Swap Facility (KMSF) does that. For more information, see the Kernel-Managed Swap Facility (KMSF) Manual. If you have given the command PARAM SWAPVOL and decide that you do not want it, you can clear it with the CLEAR command before running the compiler; for example: 94> PARAM SWAPVOL $COBVOL 95> CLEAR PARAM SWAPVOL 96> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ Compiler Space Allocation The PARAM SYMBOL-BLOCKS command specifies how much space the compiler allocates for its symbol dictionary, embedded SQL/MP statements, and for the COBOL85 compiler, its local label table—see PARAM SYMBOL-BLOCKS. If you have given the command PARAM SYMBOL-BLOCKS and decide that you do not want it, you can clear it before running the compiler with the CLEAR command; for example: 98> PARAM SYMBOL-BLOCKS 1 99> CLEAR PARAM SYMBOL-BLOCKS 100> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -21 Creating and Compiling HP COBOL Source Programs Improving Compilation Speed If you have given several PARAM commands, you can clear all of them before running the compiler with the command CLEAR ALL PARAM; for example: 101> 102> 103> 104> 105> PARAM SAMECPU 7 PARAM SWAPVOL $COBVOL PARAM SYMBOL-BLOCKS 1 CLEAR ALL PARAM COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ Improving Compilation Speed Under these conditions, these actions can improve compilation speed: Condition Action Either or both of the processors that the COBOL85, BINSERV, and SYMSERV processes would use by default are very busy.* Use the PARAM SAMECPU command (see Processors the Compilation Processes Use). The volumes on which COBOL85, BINSERV, and SYMSERV would create their temporary files by default are accessed often.* Use the PARAM SWAPVOL command (see Volume(s) for Temporary Files). The compilation summary shows that the maximum symbol table size is less than 256 KB. Use the PARAM SYMBOL-BLOCKS 1 command (see Compiler Space Allocation). You only want the compiler to check the program’s syntax (not generate object code). Use the SYNTAX directive (see Specifying Compiler Directives). * Applies only to the COBOL85 compiler. Launching Compilations to Run Unattended You can launch a compilation to run unattended with NetBatch, a job management system. For details, see the NetBatch Manual. Using COPY and SOURCE Libraries A COPY or SOURCE library is an EDIT file that contains one or more blocks of text. Each block is preceded by a SECTION directive that specifies its name and (optionally) its reference format (ANSI or Tandem, the default being Tandem). The section name in the SECTION directive is the one to use in a COPY statement or SOURCE directive. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -22 Creating and Compiling HP COBOL Source Programs Using COPY and SOURCE Libraries Example 22-2. COPY or SOURCE Library ?SECTION NAMEREC 01 NAME-REC. 03 LAST-NAME 03 M-I 03 FIRST-NAME 03 TITLE PICTURE PICTURE PICTURE PICTURE X(15). X(1). X(15). X(5). ?SECTION STANDARD-LINAGE LINAGE IS 55 LINES WITH FOOTING AT 45 LINES AT TOP 5 LINES AT BOTTOM 6 ?SECTION ZOO-FILE ASSIGN TO "$A0101.ZOO.ROSTER" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS ANIMAL-NUMBER ALTERNATE RECORD KEY IS SPECIES WITH DUPLICATES ALTERNATE RECORD KEY IS HABITAT WITH DUPLICATES FILE STATUS IS ZOO-STAT ?SECTION EMPLOYEE-NUM-PIC PICTURE 9(6). The only difference between a COPY library and a SOURCE library is context—a library that is referenced by a COPY statement is called a COPY library, and a library that is referenced by a SOURCE directive is called a SOURCE library. The important differences between the COPY statement and the SOURCE directive are: • • • The COPY statement can replace specified text-words in the library text with different text-words; the SOURCE directive cannot. The SOURCE directive requires the name of the library file; the COPY statement does not, as it can use the default COPY library. The SOURCE directive can be in library text (that is, SOURCE directives can be nested); the COPY statement cannot. To use the library in Example 22-2 as a COPY library, include a line like this in your source program: 01 STARTING-EMPLOYEE COPY EMPLOYEE-NUM-PIC. The COPY statement and the period (.) that follows it are replaced. The effect is the same as including this line in your source program: HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -23 Creating and Compiling HP COBOL Source Programs Creating or Altering a COPY or SOURCE Library 01 STARTING-EMPLOYEE PICTURE 9(6). To use the library in Example 22-2 as a SOURCE library, include a line like this in your source program: ?SOURCE file-name (NAMEREC,ZOO-FILE) where file-name is the name of the file containing the library text in Example 22-2. The effect is the same as including these lines in your source program: 01 NAME-REC. 03 LAST-NAME 03 M-I 03 FIRST-NAME 03 TITLE PICTURE PICTURE PICTURE PICTURE X(15). X(1). X(15). X(5). ASSIGN TO "$A0101.ZOO.ROSTER" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS ANIMAL-NUMBER ALTERNATE RECORD KEY IS SPECIES WITH DUPLICATES ALTERNATE RECORD KEY IS HABITAT WITH DUPLICATES FILE STATUS IS ZOO-STAT Creating or Altering a COPY or SOURCE Library You can create a COPY or SOURCE library with an HP editor or with Data Definition Language (DDL). You can alter a COPY or SOURCE library with an HP editor unless it was created with DDL, in which case you must alter it with DDL. Topics: • • Using an HP Editor Using Data Definition Language (DDL) Using an HP Editor To create or alter a COPY or SOURCE library with either HP editor, EDIT or TEDIT, use the same method as you would use to create or alter a HP COBOL source program (see Creating or Altering an HP COBOL Source Program). Follow the library format described in Library Format (see Example 22-2). HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -24 Creating and Compiling HP COBOL Source Programs Using Data Definition Language (DDL) Using Data Definition Language (DDL) Data Definition Language (DDL) is a language with which you describe the data structures of a database. The DDL compiler reads your description and generates a data declaration library (a COPY library) for the database and a File Utility Program (FUP) command file for building the database files. DDL also lets you create and maintain a data dictionary for your database. Because DDL can create data declarations for other programming languages, it facilitates sharing data structures in mixed-language programs. Figure 22-3. DDL Input and Output Data Declaration (COPY) Library DDL Compiler Your Description FUP Command File Data Dictionary VST700.vsd Topics: • • • • Describing the Data Structures Data Declaration (COPY) Library File Utility Program (FUP) Commands Data Dictionary Describing the Data Structures You describe the data structures of your database with DEFINE statements. Each data item can be an elementary item or a data structure. A data item can be composed of explicit, COBOL-like definitions or it can refer to data items defined earlier in the data dictionary. In the latter case, you define records with RECORD statements. A record definition can include both explicitly defined data items and data items defined earlier in the data dictionary. In Example 22-3, note the absence of the level number 01. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -25 Creating and Compiling HP COBOL Source Programs Using Data Definition Language (DDL) Example 22-3. Input to the DDL Compiler DEFINE NAME. 02 LAST-NAME 02 MIDDLE-INITIAL 02 FIRST-NAME END PIC X(15). PIC X(1). PIC X(15). DEFINE ADDRESS. 02 STREET-NUMBER 02 STREET-NAME 02 FLAT-NUMBER 02 MUNICIPALITY 02 STATE-OR-PROVINCE 02 NATION 02 POSTAL-CODE END PIC PIC PIC PIC PIC PIC PIC X(6). X(25). X(8). X(25). X(25). X(25). X(11). DEFINE NAME-AND-ADDRESS. 05 NAME TYPE *. 05 ADDRESS TYPE *. END RECORD PERSON-RECORD. 02 NAME-AND-ADDRESS 02 OCCUPATION-NUMBER 02 OCCUPATION-NAME 02 EMPLOYER-NAME 02 EMPLOYER-ADDRESS FILE IS "folks" Entry-Sequenced. TYPE *. PIC 9(6). PIC X(35). PIC X(35). TYPE address. KEY "PN" IS NAME-AND-ADDRESS.NAME. KEY "EN" IS EMPLOYER-NAME. END Data Declaration (COPY) Library Example 22-4 shows the data declaration (COPY) library that the DDL compiler produces from the input shown in Example 22-3. The DDL compiler has assigned (or reassigned) appropriate level numbers—for example: Data Item Level Number NAME 01 STREET-NUMBER in the record ADDRESS 02 STREET-NUMBER in the record NAME-AND-ADDRESS 03 STREET-NUMBER in the record PERSON-RECORD 04 HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -26 Creating and Compiling HP COBOL Source Programs Using Data Definition Language (DDL) Example 22-4. COPY Library Produced by the DDL Compiler (page 1 of 2) * SCHEMA PRODUCED DATE - TIME : 2/28/93 12:01:42 ?SECTION NAME,HP * Definition NAME created on 02/28/93 at 12:01 01 NAME. 02 LAST-NAME PIC X(15). 02 MIDDLE-INITIAL PIC X(1). 02 FIRST-NAME PIC X(15). ?SECTION ADDRESS,HP * Definition ADDRESS created on 02/28/93 at 12:01 01 ADDRESS. 02 STREET-NUMBER PIC X(6). 02 STREET-NAME PIC X(25). 02 FLAT-NUMBER PIC X(8). 02 MUNICIPALITY PIC X(25). 02 STATE-OR-PROVINCE PIC X(25). 02 NATION PIC X(25). 02 POSTAL-CODE PIC X(11). ?SECTION NAME-AND-ADDRESS,HP * Definition NAME-AND-ADDRESS created on 02/28/93 at 12:01 01 NAME-AND-ADDRESS. 02 NAME. 03 LAST-NAME PIC X(15). 03 MIDDLE-INITIAL PIC X(1). 03 FIRST-NAME PIC X(15). 02 ADDRESS. 03 STREET-NUMBER PIC X(6). 03 STREET-NAME PIC X(25). 03 FLAT-NUMBER PIC X(8). 03 MUNICIPALITY PIC X(25). 03 STATE-OR-PROVINCE PIC X(25). 03 NATION PIC X(25). 03 POSTAL-CODE PIC X(11). HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -27 Creating and Compiling HP COBOL Source Programs Using Data Definition Language (DDL) Example 22-4. COPY Library Produced by the DDL Compiler (page 2 of 2) ?SECTION PERSON-RECORD,HP * Record PERSON-RECORD created on 02/28/93 at 12:01 01 PERSON-RECORD. 02 NAME-AND-ADDRESS. 03 NAME. 04 LAST-NAME PIC X(15). 04 MIDDLE-INITIAL PIC X(1). 04 FIRST-NAME PIC X(15). 03 ADDRESS. 04 STREET-NUMBER PIC X(6). 04 STREET-NAME PIC X(25). 04 FLAT-NUMBER PIC X(8). 04 MUNICIPALITY PIC X(25). 04 STATE-OR-PROVINCE PIC X(25). 04 NATION PIC X(25). 04 POSTAL-CODE PIC X(11). 02 OCCUPATION-NUMBER PIC 9(6). 02 OCCUPATION-NAME PIC X(35). 02 EMPLOYER-NAME PIC X(35). 02 EMPLOYER-ADDRESS. 03 STREET-NUMBER PIC X(6). 03 STREET-NAME PIC X(25). 03 FLAT-NUMBER PIC X(8). 03 MUNICIPALITY PIC X(25). 03 STATE-OR-PROVINCE PIC X(25). 03 NATION PIC X(25). 03 POSTAL-CODE PIC X(11). File Utility Program (FUP) Commands Example 22-5 shows the FUP command file that the DDL compiler produces from the input shown in Example 22-3. Assuming that the name of the FUP command file is FUPSRC, you create the file FOLKS with this command: 110> FUP /IN FUPSRC/ The name of the FUP command file is specified in the DDL command FUP; for details, see the Data Definition Language (DDL) Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -28 Creating and Compiling HP COBOL Source Programs Including Text From a COPY Library Example 22-5. FUP Command File Produced by the DDL Compiler < SCHEMA PRODUCED DATE - TIME : 2/28/93 12:01:41 < SECTION PERSON-RECORD < Record PERSON-RECORD created on 02/28/93 at 12:01 RESET SET ALTKEY ( "PN", KEYOFF 0, KEYLEN 31, FILE 0 ) SET ALTKEY ( "EN", KEYOFF 197, KEYLEN 35, FILE 0 ) SET NO ALTCREATE SET ALTFILE ( 0, folks0 ) SET TYPE E SET REC 357 SET BLOCK 512 CREATE folks RESET SET TYPE K SET KEYLEN 41 SET REC 41 SET BLOCK 512 SET IBLOCK 512 CREATE folks0 Data Dictionary A data dictionary is a set of files that documents the structure and location of each file in your database. You can use the DDL compiler to translate DDL source statements into a data dictionary, and then you can use the DDL compiler to modify the data dictionary and re-create the data declaration (COPY) library. Alternatively, you can keep the DDL source statements in a disk file, and when you want to change a data description, you can recompile the data dictionary. The former procedure is faster (because you are not recompiling the entire data dictionary); the latter procedure is more straightforward. For complete information about DDL, see the Data Definition Language (DDL) Reference Manual. Including Text From a COPY Library Text from a COPY library is included in a HP COBOL source program with a COPY statement. Although a COPY statement can appear anywhere in a HP COBOL source program that a character-string or separator can appear, its most common uses are: • • • To copy descriptions of records or data structures into the Data Division To copy the same small piece of code into several different programs (where “small” means too small to merit being a separately compiled program) To copy the occurrence number in an OCCURS clause into more than one data description entry, as if it were a constant HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -29 Creating and Compiling HP COBOL Source Programs Including Text From a COPY Library Topics: • • • • • • Simple Copying Copying With Replacement Replacing Substrings Copying Into Debugging Lines Using Multiple COPY Libraries Using COPY Libraries Efficiently Simple Copying Simple copying means copying text from a COPY library into a source program. This example uses simple copying to copy the occurrence number in an OCCURS clause into more than one data description entry, as if it were a constant. Suppose that the present number of sales offices is 24, but you expect it to change. Put this text into a COPY library: ?SECTION OFFICES 24 In every table whose length must be the same as the number of sales offices, use a COPY statement; for example: 01 RENT RATE 01 EMPLOYEES 03 MANAGEMENT 03 ADMINISTRATIVE 03 SALES 03 SUPPORT 03 OTHER PICTURE 9(6) OCCURS COPY OFFICES. TIMES. OCCURS COPY OFFICES. TIMES. PICTURE 9(3). PICTURE 9(3). PICTURE 9(3). PICTURE 9(3). PICTURE 9(3). Each COPY statement ends with a period. The COPY statement and its period are replaced by the library text: 01 RENT RATE 01 EMPLOYEES 03 MANAGEMENT 03 ADMINISTRATIVE 03 SALES 03 SUPPORT 03 OTHER PICTURE 9(6) OCCURS 24 TIMES. OCCURS 24 TIMES. PICTURE 9(3). PICTURE 9(3). PICTURE 9(3). PICTURE 9(3). PICTURE 9(3). If the section OFFICES had been empty, the COPY statements would have been replaced with spaces. If there had been no section named OFFICES, the compiler would have reported an error 72 (Expected section-name ). HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -30 Creating and Compiling HP COBOL Source Programs Including Text From a COPY Library Copying With Replacement Copying with replacement means copying text from a COPY library, modifying it, and then writing it into a source program. Copying with replacement is achieved with the REPLACING phrase. Using the preceding example, suppose that the number of sales offices increases from 24 through 27. You have two choices: • In the COPY library, change 24 to 27: ?SECTION OFFICES 27 • In the HP COBOL source program, add REPLACING phrases to the appropriate COPY statements: 01 RENT RATE PICTURE 9(6) OCCURS COPY OFFICES REPLACING 24 BY 27. TIMES. 01 EMPLOYEES OCCURS COPY OFFICES REPLACING 24 BY 27. TIMES. ...03 MANAGEMENT PICTURE 9(3). ...03 ADMINISTRATIVE PICTURE 9(3). ...03 SALES PICTURE 9(3). ...03 SUPPORT PICTURE 9(3). ...03 OTHER PICTURE 9(3). The resulting source code is: 01 RENT RATE 01 EMPLOYEES ...03 MANAGEMENT ...03 ADMINISTRATIVE ...03 SALES ...03 SUPPORT ...03 OTHER PICTURE 9(6) OCCURS 27 TIMES. OCCURS 27 TIMES. PICTURE 9(3). PICTURE 9(3). PICTURE 9(3). PICTURE 9(3). PICTURE 9(3). (This COPY library itself does not change.) Copying with replacement is not the only way to replace text-words in source code; the REPLACE statement is another way. See Replacing Text-Words in an HP COBOL Source Program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -31 Creating and Compiling HP COBOL Source Programs Including Text From a COPY Library Replacing Substrings The REPLACING phrase can only replace entire text-words (DAILY-TOTAL but not just TOTAL, for example); however, parenthesized words within pseudo-text are recognized as text-words, allowing you to write statements such as: COPY SUM-IT REPLACING ==(PREFIX)== BY ==DAILY==. Suppose that you want to declare several identifiers that begin with the same prefix (such as DAILY-TOTAL, DAILY-MINIMUM, and DAILY-MAXIMUM), several identifiers that end with the same suffix (such as DAILY-TOTAL, WEEKLY-TOTAL, and MONTHLY-TOTAL), and several identifiers that contain the same strings (such as AVG-DAILY-COST, AVG-MONTHLY-COST, and AVG-ANNUAL-COST). Example 22-6. Replacing Substrings Lines in COPY library: ?SECTION PREFIX 77 (PREFIX)-TOTAL 77 (PREFIX)-MINIMUM 77 (PREFIX)-MAXIMUM ?SECTION SUFFIX 77 DAILY-(SUFFIX) 77 WEEKLY-(SUFFIX) 77 MONTHLY-(SUFFIX) ?SECTION PRESUF 77 (PRE)-DAILY-(SUF) 77 (PRE)-MONTHLY-(SUF) 77 (PRE)-ANNUAL-(SUF) PIC S9(8).99. PIC S9(8).99. PIC S9(8).99. PIC S9(8).99. PIC S9(8).99. PIC S9(8).99. PIC S9(8).99. PIC S9(8).99. PIC S9(8).99. Lines in HP COBOL source program: COPY PREFIX REPLACING ==(PREFIX)== COPY SUFFIX REPLACING ==(SUFFIX)== COPY PRESUF REPLACING ==(PRE)== BY ==(SUF)== BY BY ==DAILY==. BY ==TOTAL==. ==AVG== ==COST==. HP COBOL source program effectively contains these lines: 77 77 77 77 77 77 77 77 77 DAILY-TOTAL DAILY-MINIMUM DAILY-MAXIMUM DAILY-TOTAL WEEKLY-TOTAL MONTHLY-TOTAL AVG-DAILY-COST AVG-MONTHLY-COST AVG-ANNUAL-COST PIC PIC PIC PIC PIC PIC PIC PIC PIC S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -32 Creating and Compiling HP COBOL Source Programs Including Text From a COPY Library Copying Into Debugging Lines When the source line containing the word COPY is a debug line (has a D or d in the indicator area), the compiler changes each library line that has a space in its indicator area to a debug line. Example 22-7. Copying Into Debugging Lines Source line: D COPY DEB-DISP. Library lines: ?SECTION DEB-DISP DISPLAY KINGDOM PHYLUM CLASS ORDER FAMILY GENUS SPECIES. Compiled as: D D DISPLAY KINGDOM PHYLUM CLASS ORDER FAMILY GENUS SPECIES. Using Multiple COPY Libraries There is no limit to the number of COPY libraries the compiler can use in a single compilation. To specify a nondefault COPY library, use an OF or IN phrase in the COPY statement; for example: COPY RECORD1 OF LIBRARY3. (where LIBRARY3 is on the default volume and subvolume) or: COPY RECORD1 IN \NODE4.$VOL2.SUBVOL1.LIBRARY2. (where LIBRARY3 is fully qualified). Using COPY Libraries Efficiently You can reduce the time the compiler spends searching for items in COPY libraries by putting the most frequently used items in the front of their COPY libraries. The reason is that the first time the compiler encounters a COPY statement, the compiler opens the default or specified COPY library and reads until it finds the specified item, building a temporary directory of items as it reads them. Subsequent COPY statements search the directory for items before searching libraries for them; therefore, COPY statements that reference items already entered in the directory compile faster than COPY statements that reference items not yet entered in the directory. If a specified item is not yet in the directory, the compiler resumes reading the library after the last item in the directory, continuing to build the directory. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -33 Creating and Compiling HP COBOL Source Programs Including Text From a SOURCE Library Including Text From a SOURCE Library Text from a SOURCE library is included in a HP COBOL source program with a SOURCE directive. A SOURCE directive must be the last directive on its line. When the compiler reads a SOURCE directive, it suspends reading from its primary source file and begins reading (entire lines) from a specified section of a SOURCE library. The SOURCE directive does not have anything like the COPY statement’s REPLACING phrase; it cannot replace library text-words with different text-words. The SOURCE directive’s most common uses are: • • • To copy File Descriptions into the Environment Division To copy record or group descriptions into the Data Division To copy blocks of code lines into the Procedure Division Example 22-8. Including Text From a Source File Library file, SRCFILE: ?SECTION NAMEREC 01 NAME-REC. 03 LAST-NAME 03 M-I 03 FIRST-NAME 03 TITLE ?SECTION ADDRREC 01 ADDR-REC. 03 NUMBER 03 STREET 03 APT-NUM 03 CITY 03 STATE 03 ZIPCODE ?SECTION DATEREC 01 DATE-REC. 03 MONTH 03 DAY 03 YEAR PICTURE PICTURE PICTURE PICTURE X(15). X(1). X(15). X(5). PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE X(5). X(15). X(3). X(15). X(2). X(5). PICTURE X(9). PICTURE X(2). PICTURE X(4). Line in HP COBOL source program: ?SOURCE SRCFILE HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -34 Creating and Compiling HP COBOL Source Programs Including Text From a SOURCE Library Example 22-8. Including Text From a Source File Resulting source code: 01 01 01 NAME-REC. 03 LAST-NAME 03 M-I 03 FIRST-NAME 03 TITLE ADDR-REC. 03 NUMBER 03 STREET 03 APT-NUM 03 CITY 03 STATE 03 ZIPCODE DATE-REC. 03 MONTH 03 DAY 03 YEAR PICTURE PICTURE PICTURE PICTURE X(15). X(1). X(15). X(5). PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE X(5). X(15). X(3). X(15). X(2). X(5). PICTURE X(9). PICTURE X(2). PICTURE X(4). If the HP COBOL source program in Example 22-8 contains the line ?SOURCE SRCFILE (NAMEREC,DATEREC) then only the sections NAMEREC and DATEREC are included in the resulting source code, which is: 01 01 NAME-REC. 03 LAST-NAME 03 M-I 03 FIRST-NAME 03 TITLE DATE-REC. 03 MONTH 03 DAY 03 YEAR PICTURE PICTURE PICTURE PICTURE X(15). X(1). X(15). X(5). PICTURE X(9). PICTURE X(2). PICTURE X(4). HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -35 Creating and Compiling HP COBOL Source Programs Replacing Text-Words in an HP COBOL Source Program Replacing Text-Words in an HP COBOL Source Program You can replace text-words with other text-words in a HP COBOL source file with a REPLACE statement. A REPLACE statement is active from the time the compiler encounters it until the compiler encounters either another, overriding REPLACE statement or the end of a separately compiled program. The two Data Divisions in Example 22-9 are equivalent. Example 22-9. Replacing Text-Words in an HP COBOL Source Program DATA DIVISION. REPLACE ==OFFICES== BY ==10== ==SQ-FT-SIZE== BY ==5== 01 OFFS. 03 OFFICE-INFO OCCURS OFFICES TIMES. 05 DISTRICT PICTURE 99. 05 SQUARE-FEET PICTURE S9(SQ-FT-SIZE) PROCEDURE DIVISION. PERFORM REPORT-OFFICE OFFICE TIMES. REPLACE OFF. DATA DIVISION. 01 OFFS. 03 OFFICE-INFO OCCURS 10 TIMES. 05 DISTRICT PICTURE 99. 05 SQUARE-FEET PICTURE S9(5) PROCEDURE DIVISION. PERFORM REPORT-OFFICE 10 TIMES. For restrictions on the use of the REPLACE statement and a detailed explanation of the comparison operation that it uses, see REPLACE Statement. Topics: • • • Replacing Substrings Replacing Text-Words From COPY Libraries Replacing Text-Words From SOURCE Libraries HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -36 Creating and Compiling HP COBOL Source Programs Replacing Substrings Replacing Substrings The REPLACE statement can only replace entire text-words (DAILY-TOTAL but not just TOTAL, for example); however, parenthesized words within pseudo-text are recognized as text-words, allowing you to write statements such as: REPLACE ==(PREFIX)== BY ==DAILY==. Suppose that you want to declare several identifiers that begin with the same prefix (such as DAILY-TOTAL, DAILY-MINIMUM, and DAILY-MAXIMUM), several identifiers that end with the same suffix (such as DAILY-TOTAL, WEEKLY-TOTAL, and MONTHLY-TOTAL), and several identifiers that contain the same strings (such as AVG-DAILY-COST, AVG-MONTHLY-COST, and AVG-ANNUAL-COST). The two sets of source code in Example 22-10 are equivalent. Example 22-10. Replacing Substrings in an HP COBOL Source Program REPLACE ==(PREFIX)== BY ==DAILY==. ==(SUFFIX)== BY ==TOTAL==. ==(PRE)== BY ==AVG== ==(SUF)== BY ==COST==. 77 (PREFIX)-TOTAL PIC S9(8).99. 77 (PREFIX)-MINIMUM PIC S9(8).99. 77 (PREFIX)-MAXIMUM PIC S9(8).99. 77 DAILY-(SUFFIX) PIC S9(8).99. 77 WEEKLY-(SUFFIX) PIC S9(8).99. 77 MONTHLY-(SUFFIX) PIC S9(8).99. 77 (PRE)-DAILY-(SUF) PIC S9(8).99. 77 (PRE)-MONTHLY-(SUF) PIC S9(8).99. 77 (PRE)-ANNUAL-(SUF) PIC S9(8).99. 77 77 77 77 77 77 77 77 77 DAILY-TOTAL DAILY-MINIMUM DAILY-MAXIMUM DAILY-TOTAL WEEKLY-TOTAL MONTHLY-TOTAL AVG-DAILY-COST AVG-MONTHLY-COST AVG-ANNUAL-COST PIC PIC PIC PIC PIC PIC PIC PIC PIC S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. S9(8).99. Compare the preceding example to the example in Replacing Substrings. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -37 Creating and Compiling HP COBOL Source Programs Replacing Text-Words From COPY Libraries Replacing Text-Words From COPY Libraries The compiler processes REPLACE statements after it has processed any COPY statements. REPLACE statements do not change COPY libraries. In Example 22-11, the compiler substitutes OFFICES for COPY OFFNUM and SQ-FTSIZE for COPY AREA first and then substitutes 10 for OFFICES and 5 for SQ-FTSIZE. Example 22-11. Replacing Text-Words From a COPY Library Source code: REPLACE ==OFFICES== BY ==10== ==SQ-FT-SIZE== BY ==5== 01 OFFS. 03 OFFICE-INFO OCCURS COPY OFFNUM. TIMES. 05 DISTRICT PICTURE 99. 05 SQUARE-FEET PICTURE S9(COPY AREA.) REPLACE OFF Lines in default COPY library: ?SECTION OFFNUM OFFICES ?SECTION AREA SQ-FT-SIZE Resulting source code (COPY library is unchanged): 01 OFFS. 03 OFFICE-INFO OCCURS 10 TIMES. 05 DISTRICT PICTURE 99. 05 SQUARE-FEET PICTURE S9(5). If the COPY statement has a REPLACING phrase, the compiler applies the REPLACING phrase before applying the REPLACE statement. For an example of a COPY statement with a REPLACING phrase, see Copying With Replacement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -38 Creating and Compiling HP COBOL Source Programs Replacing Text-Words From SOURCE Libraries Replacing Text-Words From SOURCE Libraries If a REPLACE statement is active when the compiler encounters a SOURCE directive, the REPLACE statement applies to the copy of the library text that the compiler includes in the HP COBOL source program (but not to the original text in the SOURCE library). Example 22-12. Replacing Text-Words From a SOURCE Library Source code: REPLACE ==OFFICES== BY ==10== ==SQ-FT-SIZE== BY ==5== ?SOURCE SRCFILE REPLACE OFF Lines in SOURCE library: 01 OFFS. 03 OFFICE-INFO OCCURS OFFICES TIMES. 05 DISTRICT PICTURE 99. 05 SQUARE-FEET PICTURE S9(SQ-FT-SIZE). Resulting source code (SOURCE library is unchanged): 01 OFFS. 03 OFFICE-INFO OCCURS 10 TIMES. 05 DISTRICT PICTURE 99. 05 SQUARE-FEET PICTURE S9(5). Understanding and Controlling the Compiler Listing By default, the compiler produces a listing that includes: • • • • Compilation Banner Source Program Listing Load Maps Compilation Summary With compiler directives, you can include one or more of these in the compiler listing: • • • • Symbol Table Listing Octal Code Listing Symbolic Code Listing Cross-Reference Listing HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -39 Creating and Compiling HP COBOL Source Programs Understanding and Controlling the Compiler Listing Compiler directives also allow you to: • • Request different or additional load maps (see Load Maps) Suppress parts of the compiler listing (see Table 22-1) The minimum compiler listing, produced when you compile a program with the SUPPRESS directive, includes only a banner, any diagnostics and the source lines that caused them, and a summary. To discard the COBOL85 compiler listing entirely—including any diagnostics—specify the RUN command’s OUT option with no file name; for example: 17> COBOL85 /IN PERFECT, OUT/ (The NMCOBOL compiler does not accept an empty OUT file.) When you compile several separately compiled programs at once (each of which could include nested programs), the listing includes one banner, one set of load maps, and one summary. Between the banner and the first load map, the listing includes a source program listing, symbol table, octal code listing,symbolic code listing, and crossreference listing for each program that requested them (by default or directive). Note. The NMCOBOL compiler does not produce an octal code listing or a cross-reference listing. To display a native object file, use the noft utility. To produce a cross-reference listing for a native program, use the noft utility with the XREFPROC flag. (See the noft Manual.) In Table 22-2, the compiler listing parts are in the order in which they appear in the compiler listing. Table 22-1. Compiler Listing Parts and the Directives That Control Them (page 1 of 2) Compiler Listing Part Directive That Lists Part Directives That Suppress Part Compilation banner None—always listed None Source program listing LIST (default) NOLIST or SUPPRESS COPY statements SHOWCOPY (default) NOSHOWCOPY, NOLIST, or SUPPRESS Diagnostic messages1 WARN (default) NOWARN for warning messages, none for error and failure messages 1. Included in source program listing 2. If an object program was produced 3. NMCOBOL compiler ignores this directive 4. COBOL85 compiler does not recognize this directive HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -40 Creating and Compiling HP COBOL Source Programs Compilation Banner Table 22-1. Compiler Listing Parts and the Directives That Control Them (page 2 of 2) Compiler Listing Part Directive That Lists Part Symbol table MAP Octal code listing CODE3 Symbolic code listing ICODE3, INNERLIST4 Cross-reference listing CROSSREF3 Load maps2 LMAP3 (default) Compilation summary None—always listed Directives That Suppress Part • • • • • • • • • • • • • • • • NOMAP NOLIST SUPPRESS NOCODE3 NOLIST SUPPRESS NOICODE3 NOINNERLIST4 NOLIST SUPPRESS NOCROSSREF3 NOLIST SUPPRESS NOLMAP3 NOLIST SUPPRESS None 1. Included in source program listing 2. If an object program was produced 3. NMCOBOL compiler ignores this directive 4. COBOL85 compiler does not recognize this directive For further information about any compiler listing part, see the appropriate following topic. The topics are in the order that they appear in Table 22-2. Compilation Banner The COBOL85 compilation banner consists of this information: • • • • Page number of compiler listing, date and time at which compilation began (line 1) Version of the compiler (line 4) Default options (line 5) Copyright information (line 6) Example 22-13. COBOL85 Compilation Banner PAGE 1 \ALPHA.$BETA.TESTS.ACOS Tandem COBOL85 COBOL85 - T9257D32 - (29 MAY 97) Default options: On (LIST,LMAP,SHOWCOPY,WARN) Off (CODE,ICODE,MAP) Copyright Tandem Computers Incorporated 1986-1997 HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -41 Creating and Compiling HP COBOL Source Programs Source Program Listing The NMCOBOL compilation banner consists of this information: • • • • Page number of compiler listing, date and time at which compilation began (line 1) Version of the compiler (line 4) Copyright information (line 5) Directives included on compiler command line, if any (line 7) Example 22-14. NMCOBOL Compilation Banner Page 1 1997 May 6, 16:07:20 COBOL - T8107D99 - (30 APR 97) Copyright Tandem Computers Incorporated 1986-1997 Directives: RUNNABLE Source Program Listing The compiler lists your entire source program, unless you specify otherwise. The format of the listing depends in part on the current reference format, ANSI or Tandem. Figure 22-4 compares the two listing formats. Figure 22-4. Source Program Listing Formats ANSI Format 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 ... Identification Field (cols 72 through 80 of input line) Sequence Number Line Number Area A Area B Indicator Field Text summoned by COPY marked here with "<". Tandem Format 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 ... Line Number Text summoned by COPY marked here with "<". Area A Area B Indicator Field VST701.vsd The two formats are aligned such that, even if your program mixes ANSI and Tandem formats, the COPY and comment indicators and areas A and B are aligned. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -42 Creating and Compiling HP COBOL Source Programs Source Program Listing Topics: • • • • • • • • Identification Field Line Number Sequence Number Indicator Area and Beyond Text Altered by REPLACE Statement Text Retrieved by COPY Statement Text Retrieved by SOURCE Directive SQL/MP and SQL/MX Statements Identification Field The identification field is copied from columns 72 through 80 of ANSI format source lines. Some installations use these columns for marking revisions to the program. Line Number When the file being listed is an EDIT file, the line number in the listing is the EDIT file line number. If the file is in ANSI format, the fractional part of the number, if any, is omitted. When the file being listed is not an EDIT file, the line number in the listing is a “synthetic” line number (an integer that the compiler generates). Every time the compiler reads a line of input from the file, it increments a counter by 1. Sequence Number When the file is in ANSI format, the compiler copies columns 1 through 6 of the input line to this field. Some COBOL implementations use this field as a sequence number, and if the values are not in ascending order, these implementations report a diagnostic. HP COBOL does no such reporting. Indicator Area and Beyond Beginning with the indicator area, the two formats are the same. If, in Tandem format, the input line exceeds 120 characters, it will not fit on the 132-character print line. The compiler wraps such lines onto the next line, beginning at print column 1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -43 Creating and Compiling HP COBOL Source Programs Source Program Listing Text Altered by REPLACE Statement Each REPLACE statement is listed as the compiler encounters it. Each line on which a REPLACE statement has made a change is listed after the change has been made. If the line is too long, the compiler truncates it after a reasonable token and writes as many additional lines (with the same line number) as are necessary to deliver the entire replaced text. Text Retrieved by COPY Statement The compiler marks any line containing text that it copied from a COPY library by displaying a less than (>) character in printer column 9. The compiler directives SHOWCOPY and NOSHOWCOPY determine how the compiler lists lines containing COPY statements. The default, SHOWCOPY, causes the compiler to list both the line containing the COPY statement (as a comment) and the line that results from the COPY statement. The alternative, NOSHOWCOPY, causes the compiler to list only the line that results from the COPY statement. NOSHOWCOPY makes it hard to determine from the listing where the copied lines came from. The HP COBOL COPY logic attempts to keep your listings readable by combining the original source text line with the copied library text. HP COBOL COPY logic handles these cases: • Column Position of Library Text Characters The compiler preserves the column position of library text characters; it does not shift text to the left or right when it attempts this combining operation; for example: Source line: MOVE COPY SOURCE1. TO X. Library lines: ?SECTION SOURCE1 ABLE Printed line: MOVE ABLE TO X. If “ABLE” in the library line begins in column 1, you get: Printed lines: MOVE ABLE TO X. If “ABLE” in the library line begins in column 22, you get: Printed lines: MOVE ABLE TO X. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -44 Creating and Compiling HP COBOL Source Programs • Source Program Listing Text Before the Word COPY If the source line on which the COPY statement begins has text before the word COPY, the compiler tries to combine the original source line with the first line of the library text. This strategy succeeds only if at least one space separates the first nonspace character of the library text line from the last nonspace character of the source line. The combined line retains the line number of the source line that contains the COPY statement. • Text After the Word COPY If the source line on which the COPY statement ends has text following the terminating period, the compiler tries to combine the last line of library text with the text that follows the COPY statement’s period. This strategy succeeds only if at least one space separates the last nonspace character of the library line from the first nonspace character of the remainder of the source line. The combined line retains the line number of the source line that contains the COPY statement. • ANSI Reference Format If the current reference format is ANSI, the listed line begins with the identification field of the appended source line. Example 22-16 shows this behavior. The compiler does not attempt to combine: • • • Lines of different reference formats Debug and nondebugging lines Library text lines that do not contain a space, D, or d in the indicator area When the NOSHOWCOPY directive is absent, the compiler lists the line containing a COPY statement as a comment before listing the line that results from the COPY statement substitution. The error-reporting mechanism can sometimes report a syntax error against the copied text and point to the COPY statement in the comment, as in Example 22-15. Example 22-15. Diagnostic Reported Against a Copied Line 35 * MOVE COPY SOURCE1. TO X. ** LINE 35 ^ ** ERROR 240 ** SYNTAX ERROR DETECTED AT TOKEN: ABLE 35 MOVE ABLE ** LINE 35 ** WARNING 244 ** PARSING RESUMED AT TOKEN: TO X. ^ X HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -45 Creating and Compiling HP COBOL Source Programs Source Program Listing Example 22-16. ANSI Format COPY Expansion (page 1 of 2) Source Program Lines: PD0023 A. ANSIFMT PD0024 ANSIFMT PD0024 ANSIFMT PD0026 ANSIFMT PD0027 ANSIFMT PD0028 ANSIFMT PD0029 ANSIFMT PD0030D ANSIFMT PD0031 ANSIFMT COPY MOVE1. COPY MOVE2. MOVE COPY SOURCE1. TO X. MOVE COPY SOURCE2. TO X. MOVE COPY SOURCE3. TO X. ADD COPY ADD1. COPY ADD2. COPY ADD3. COPY ADD4. TO ANSR. DISPLAY COPY SHOW-LIST OF SOMELIB. . STOP RUN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -46 Creating and Compiling HP COBOL Source Programs Source Program Listing Example 22-16. ANSI Format COPY Expansion (page 2 of 2) COPY Library Lines: ?SECTION MOVE1,ANSI MOVE ABLE TO BAKER. ?SECTION MOVE2,HP MOVE ABLE TO BAKER. ?SECTION SOURCE1,ANSI ABLE SOURCE1 ?SECTION SOURCE2,ANSI ABLE SOURCE2 ?SECTION SOURCE3,ANSI MOVE1 ABLE SOURCE3 ?SECTION 000001 ?SECTION 000101 ?SECTION ?SECTION ADD1,ANSI ANDY ADD2,ANSI BARBARA ADD3,ANSI ADD4 ADD1 ADD2 CAL Listing: ANSIFMT ANSIFMT MOVE1 < ANSIFMT < ANSIFMT ANSIFMT < ANSIFMT ANSIFMT ANSIFMT < ANSIFMT SOURCE3 < ANSIFMT ANSIFMT ANSR. ANSIFMT ANSIFMT < ANSR. ANSIFMT < ANSIFMT < ANSR. ANSIFMT < ANSR. ANSIFMT < ANSR. ANSIFMT SHOWLIST< ANSIFMT < ANSIFMT 33 34 34 35 13 36 36 37 37 38 39 39 40 41 PD0023 A. PD0024* PD0024* PD0026* PD0026 PD0027* PD0027 PD0028* PD0028 PD0028 PD0029* COPY MOVE1. MOVE ABLE TO BAKER. COPY MOVE2. MOVE ABLE TO BAKER. MOVE COPY SOURCE1. TO X. MOVE ABLE TO X. MOVE COPY SOURCE2. TO X. MOVE ABLE TO X. MOVE COPY SOURCE3. TO X. MOVE ABLE TO X. ADD COPY ADD1. COPY ADD2. COPY ADD3. COPY ADD4. TO 41 PD0029 42 000001* ADD ANDY 42 000001 43 000101* ANDY BARBARA COPY ADD3. COPY ADD4. TO 43 000101* BARBARA COPY ADD4. TO 43 000101 BARBARA 44 PD0030* 44 PD0030D 45 D 46 PD0031 DISPLAY COPY SHOW-LIST OF SOMELIB. . DISPLAY ABLE BAKER CHARLENE DELTA ANDY BARBARA . STOP RUN. COPY ADD2. COPY ADD3. COPY ADD4. TO CAL HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -47 TO Creating and Compiling HP COBOL Source Programs Source Program Listing Text Retrieved by SOURCE Directive The compiler does not mark lines containing text that it copied from a SOURCE library. The compiler directives SHOWFILE and NOSHOWFILE determine whether the compiler listing indicates when the compiler stops reading from one source file and starts reading from another. The default, NOSHOWFILE, prevents the compiler from reporting when it switches from one source file to another. The alternative, SHOWFILE, causes the compiler to report each time it starts reading from a new source file by printing a line of the form: Source file: [n] filename yyyy-mm-dd hh:mm:ss The n is the ordinal number that the compiler assigned to the source file. Initially, n is 1, and the compiler increments n by 1 every time it encounters a SOURCE directive. The filename is the fully qualified name of the new source file. The remainder of the line is the date and time when that file was last modified. SQL/MP and SQL/MX Statements SQL/MP or SQL/MX statements embedded in your HP COBOL program always appear in the compiler listing, but their format depends on whether you used the preprocessor to produce the object file. For SQL/MP statements, using the preprocessor is optional (see the SQL/MP Programming Manual for COBOL). For embedded SQL/MX statements, you always use the preprocessor to produce the object file (see the SQL/MX Programming Manual for C and COBOL). If you used the preprocessor, the SQL/MP or SQL/MX commands in your HP COBOL source program appear in the compiler listing in their processed form (that is, as SQL/MP or SQL/MX data structures, PERFORM statements, and calls to TAL routines). If the compiler detects an error in a processed SQL/MP or SQL/MX statement, it prints the error message after the offending SQL/MP or SQL/MX data structure, PERFORM statement, or TAL routine call. If you do not use the preprocessor, the SQL/MP or SQL/MX commands in your HP COBOL source program appear in the compiler listing exactly as they appear in the source program. SQL/MP or SQL/MX data structures, PERFORM statements, or calls to TAL routines that the compiler generated do not appear in the compiler listing (except called or included data structures). If the compiler detects an error in an embedded SQL/MP or SQL/MX statement, it prints the error message after the offending SQL/MP or SQL/MX statement itself. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -48 Creating and Compiling HP COBOL Source Programs Diagnostic Messages Diagnostic Messages Table 22-2. Diagnostic Messages in the Compiler Listing Diagnostic Message Category Subcategory Numbered Suppressable Compiler Warning Yes Yes After detection Yes Error Yes No After detection Yes Failure Yes No After detection No INSPCI1 No No After all compiler diagnostic messages have been printed No Binder1 Yes No After all INSPCI diagnostic messages have been printed No Informational Yes Yes No Warning Yes Yes Error Yes No After all compiler diagnostic messages have been printed Linker2 When Printed 1. COBOL85 compiler only 2. NMCOBOL compiler only, and only if it calls a linker Topics: • • • • • • Compiler Warning Messages Compiler Error Messages Compiler Failure Messages INSPCI Error Messages Binder Messages Error Files HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -49 Can Be Documented in Error File No No Creating and Compiling HP COBOL Source Programs Diagnostic Messages For a list of all the compiler diagnostic messages and their probable causes, see Section 47, Compiler Diagnostic Messages. For a list of all the Binder messages and their probable causes, see the Binder Manual. Compiler Warning Messages A warning message reports a questionable condition. A warning does not prevent the generation of code. You can suppress warning messages with the NOWARN directive. Example 22-17. Warning Message ** Warning 25 ** Blank continuation line Table 22-3. Compiler Directives That Produce Optional Warnings Directive Produces warnings for ... DIAGNOSE-74 Statements that might behave differently in HP COBOL and COBOL 74 DIAGNOSE-85* Statements that might behave differently when compiled by the COBOL85 and NMCOBOL compilers DIAGNOSEALL Multiple references to undefined identifiers (instead of the first one only) FIPS Statements as required by the Federal Information Processing Standard (FIPS) SUBSET HP extensions to ANSI COBOL and obsolete elements * For NMCOBOL compiler only. For more information about the directives in Table 22-3, see Compiler Directives. Compiler Error Messages An error message reports a serious violation of HP COBOL syntax or semantics. At the first error message, the compiler stops generating code for the current program unit and deletes any code that it has already generated for that program unit. You cannot suppress error messages. Example 22-18. Error Message ** Error 44 ** Syntax error detected at token COUNTER Like many error messages, this example reports the identifier that the compiler was processing or seeking when it detected the error (in this case, COUNTER). HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -50 Creating and Compiling HP COBOL Source Programs Diagnostic Messages Although the compiler stops generating code when it encounters the first error, it continues with the compilation, reporting as many diagnostic messages as it can. Because an error can leave the compiler with incorrect or incomplete information, the compiler might report errors in later statements that are actually correct. (The later errors are side effects of the earlier ones.) If you do not understand certain error messages, fix the errors you do understand and the others might disappear or be expressed in an understandable way in the next compilation. For the COBOL85 compiler, if the IN file contains more than one separately compiled program, errors in one program do not prevent the others from being compiled. The object file will contain only the object programs for the programs that compiled without errors. You can recompile the entire set of programs, or you can fix the erroneous statements, recompile only the programs that did not compile the first time, and use the BIND utility to combine the two object files into one. If the NMCOBOL compiler finds errors in any program in the IN file, it does not produce any object programs (that is, it produces no object file). Compiler Failure Messages A failure message reports a condition so severe that the compiler is unable to continue. Any code that the compiler has already generated during the current compilation session is lost. You cannot suppress failure messages. Example 22-19. Failure Message For the COBOL85 compiler: ** Failure message-number ** message-text For the NMCOBOL compiler: *** Failure: --> message-text [Warning message-number] The brackets are part of the message, not indicators that the bracketed material is optional. INSPCI Error Messages A message of the form **** INSPCI ERROR AT P=%nnnnn ... or PCI FATAL ERROR: nnn AT P = %nnnnnn ... (where n is a digit) means that an error occurred in the communication mechanism between the COBOL85 compiler and Binder (the PDT-compiler interface, or PCI). Report the error to your service provider. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -51 Creating and Compiling HP COBOL Source Programs Diagnostic Messages Binder Messages A Binder message begins with one of these strings: **** Binder WARNING nnn **** **** Binder ERROR nnn **** **** Binder FATAL ERROR nnn **** (where n is a digit). For information about specific Binder messages, see the Binder Manual. Error Files The compiler directive ERRORFILE causes the compiler to document its warning and error messages in an error file. For each compiler warning or error message, the compiler writes one record to the error file. Each record contains this information: • The fully qualified, local file name of the source file in which the warning or error occurred If you specified a DEFINE name for the name of the source file, then this entry is the file name that the DEFINE produced. • • • The line number that the HP editor (EDIT or TEDIT) assigned to the line in which the warning or error occurred The column number in which the warning or error occurred The warning or error message text The error file is not an EDIT file; it is of type 106. You can use it only with the TACL macro FIXERRS. For information about the FIXERRS macro, see FIXERRS Macro. In this example, the error file is ERRORS on the default volume and subvolume: 90> COBOL85 /IN XYZ, OUT $SPX/ XYZOBJ; ERRORFILE ERRORS 90> NMCOBOL /IN XYZ, OUT $SPX/ XYZOBJ; ERRORFILE ERRORS If the file ERRORS does not exist, the compiler creates an entry-sequenced file of type 106 and names it ERRORS. If ERRORS does exist, and is of type 106, the compiler replaces its contents with the new error file. If ERRORS exists but is not of type 106, the compiler terminates with the message: ERRORFILE not created HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -52 Creating and Compiling HP COBOL Source Programs Symbol Table Listing Symbol Table Listing The compiler lists the symbol table if you explicitly request it with the MAP directive. The symbol table lists, in alphabetic order, each identifier in the program. For each identifier, the listing shows: • • • • • • The group(s) of which it is a member The type of entity it identifies (its level number) The address (including possible offset) with which it is associated The size of the entity it identifies, if applicable The category of the entity it identifies (such as numeric or alphanumeric) The usage of the entity it identifies (such as COMPUTATIONAL or DISPLAY) Most identifiers in a program identify data items. Example 22-20 and Example 22-21 show a few lines of a symbol table listing of the program in Example 14-14 on page 14-22. Example 22-20. Symbol Table Listing (COBOL85 Compiler) ... CPU OF CPU-PIN 05 L+006,S 0 2 NM COMP CPU-PIN 01 L+006,S 0 8 AN GROUP CREATOR-ACCESSOR-ID 01 L+011 0 2 NM COMP CREATOR-EDITED 01 L+013,S 0 1 AN GROUP CREATOR-GROUP OF CREATOR-EDITED 05 L+013,S 6 3 NME DISPLY CREATOR-MEMBER OF CREATOR-EDITED 05 L+013,S 18 3 NME DISPLY 01 L+022 0 2 NM DISPLY ERROR-RETURN EXPLAIN-MYSELF PARAGRAPH %000413 HOME-TERMINAL 01 L+020,S 0 24 AN DISPLY HOME-TERMINAL-LEN 01 L+021 0 2 NM NATIVE 05 L+007,I 0 1 AN DISPLY LEFT-BYTE OF CONSECUTIVE-BYTES ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -53 Creating and Compiling HP COBOL Source Programs Octal Code Listing Example 22-21. Symbol Table Listing (NMCOBOL Compiler) ... CPU 05 NM COMP OF CPU-PIN H"350 H"2 01 AN GROUP H"350 H"8 01 NM COMP H"350 H"2 01 AN GROUP H"350 H"15 05 NME DISPLY OF CREATOR-EDITED H"356 H"3 05 NME DISPLY OF CREATOR-EDITED H"362 H"3 01 NM DISPLY H"350 H"2 PARAGRAPH H"34F H"FFFFFFFF 01 AN DISPLY H"350 H"18 01 NM NATIVE H"350 H"2 05 AN DISPLY OF CONSECUTIVE-BYTES H"350 H"1 CPU-PIN CREATOR-ACCESSOR-ID CREATOR-EDITED CREATOR-GROUP CREATOR-MEMBER ERROR-RETURN EXPLAIN-MYSELF HOME-TERMINAL HOME-TERMINAL-LEN LEFT-BYTE ... Octal Code Listing Note. This topic applies only to the COBOL85 compiler. The NMCOBOL compiler does not produce an octal code listing. If you need to display a native object file, use the noft utility (see the nld Manual). The COBOL85 compiler lists the octal instructions of the object program if you explicitly request it with the CODE directive. Example 22-22 shows a few lines of an octal code listing of the program in Example 31-13. Example 22-22. Octal Code Listing ... 00160 00200 00220 00240 00260 00300 00320 00340 00360 00400 00420 00440 00460 00500 00520 00540 00560 024700 010460 051511 000025 002747 010410 020030 020013 067141 100000 046571 026040 044006 071040 100000 071151 024722 127002 001770 047106 003754 027005 000406 100001 100001 066545 100777 020143 100032 002015 044504 100777 067562 100002 000100 001050 047440 100023 100005 044440 005001 005001 062040 024722 071145 005002 040006 020151 024722 064564 100000 000266 070740 071145 026040 024700 060555 024722 024722 000025 027004 060564 024722 100015 071440 027004 074440 100777 170424 003001 072165 100046 117531 020160 170411 040006 003773 002735 067562 170417 074006 000025 002755 064563 024722 020014 044006 071156 005002 100006 071157 100004 100004 100004 070740 020141 100025 000130 003762 070740 020171 027004 117566 002023 062544 024722 024700 061545 020023 074006 026040 003001 061543 100000 010415 100015 003001 000025 002762 170424 040006 020141 170424 117527 071563 024722 000130 100010 044006 062563 024722 046571 026040 044006 003767 070740 00170 00210 00230 00250 00270 00310 00330 00350 00370 00410 00430 00450 00470 00510 00530 00550 00570 020011 100023 067040 100002 070740 020233 020022 010412 005002 002015 071557 100002 020160 100032 002010 100010 003001 117564 074006 062562 005310 003001 000025 100001 024233 024722 040006 071040 100000 071157 005002 040006 026040 044006 ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -54 000264 000130 071157 024722 044006 003770 005001 160040 170410 100015 044504 100777 061545 024722 100010 100017 002014 ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... Creating and Compiling HP COBOL Source Programs Symbolic Code Listing Symbolic Code Listing The COBOL85 compiler lists the instructions of the object program in symbolic (mnemonic) form after the source program listing if you explicitly request it with the ICODE directive (see Example 22-23). The NMCOBOL compiler lists the instructions of the object program in symbolic (mnemonic) form after each source statement if you explicitly request it with the INNERLIST directive (see Example 22-24). Note. In a symbolic code listing for a very large program, lines at the end of the program have asterisks in place of line numbers. Example 22-23. Symbolic Code Listing (COBOL85 Compiler) (page 1 of 3) 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 ?ENV COMMON;ICODE IDENTIFICATION DIVISION. PROGRAM-ID. TESTT. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. ABD. OBJECT-COMPUTER. ABD. DATA DIVISION. WORKING-STORAGE SECTION. 01 D PICTURE 9 USAGE COMPUTATIONAL. 01 STD-DATE PICTURE 9(8) USAGE COMPUTATIONAL. PROCEDURE DIVISION. STARTT. PERFORM VARYING STD-DATE FROM 19970618 BY 1 UNTIL STD-DATE > 19970624 DISPLAY STD-DATE MOVE FUNCTION REM (FUNCTION INTEGER-OF-DATE (STD-DATE) 7) TO D IF D = 0 THEN DISPLAY " SUNDAY" ELSE IF D = 1 THEN DISPLAY " MONDAY" ELSE IF D = 2 THEN DISPLAY " TUESDAY" ELSE IF D = 3 THEN DISPLAY " WEDNESDAY" ELSE IF D = 4 THEN DISPLAY " THURSDAY" ELSE IF D = 5 THEN DISPLAY " FRIDAY" ELSE IF D = 6 THEN DISPLAY " SATURDAY" END-IF END-IF END-IF END-IF END-IF END-IF END-IF END-PERFORM. STOP RUN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -55 Creating and Compiling HP COBOL Source Programs Symbolic Code Listing Example 22-23. Symbolic Code Listing (COBOL85 Compiler) (page 2 of 3) * 000036 STARTT 14. 15. 16. 17. 17. 18. 18. 19. 19. 20. 20. 000000 000006 000014 000022 000030 2 LDI 000044 000052 000060 000066 7 CON %000000 7 CON %000000 7 PCAL 000 7 BAZ +007 7 PCAL 000 +007 7 MOVW 3 LDA 2 LDLI +040 2 EXCH 0 LOAD G+000,7 7 7 0 0 7 CON %000040 CON %000000 LWP -007 LDI +177 PCAL 000 047 0 LADR 3 DLRS 01 2 ORRI 040 3 LDI +001 1 LDLI +264 000072 000100 000106 000114 000122 000130 000131 000137 000145 000153 000161 0 2 0 3 0 7 1 3 1 5 7 LDLI LDLI LDI LDD LDI ADDS LDD PUSH DSUB LDI STOR +001 +001 +000 L+007,I +010 -004 L+007,I 333 0 2 1 5 2 ORRI ORRI LADR CDQ ONED 060 060 S-000 1 3 1 6 3 LDLI LDLI LADI LDRA LDLI 2 1 3 3 LDI DDIV DDUP DMPY +002 7 3 4 1 PUSH 722 ... POP 331 ... LDI +000 ... DSUB ... 000162 000164 000172 000200 000206 000214 000217 000225 000233 000241 0 0 1 2 3 0 0 1 2 3 LOAD LDI BUN LADI LDLI LOAD LDI BUN LADI LDLI L+006 +000 +004 -005 +350 L+006 +000 +004 -005 +350 7 1 1 2 4 7 1 1 2 4 BANZ +030 LADR S-000 CON %020040 LLS 01 LDI -005 CMPI +001 LADR S-000 CON %020040 LLS 01 LDI -005 1 1 3 7 7 1 1 3 7 LADI +001 ... CON %051525 ... LDI +010 ... PUSH 744 ... BNEQ +030 LADI +001 ... CON %046517 ... LDI +010 ... PUSH 744 ... 000247 000252 000260 000266 000274 000302 000304 000307 000315 000323 000331 0 0 1 2 2 7 0 0 1 1 0 LOAD L+006 LDI +000 BUN +005 RDP ONED BUN +162 LOAD L+006 LDI +000 BUN +006 CON %054440 LDI +013 7 1 1 2 3 7 7 1 1 2 2 CMPI +002 LADR S-000 CON %020040 LADI -006 LDLI +350 INDC %000167 CMPI +003 LADR S-000 CON %020040 RDP ONED 7 1 1 2 4 BNEQ +032 LADI +001 ... CON %052125 ... LLS 01 ... LDI -005 ... 7 1 1 2 3 BNEQ +032 LADI +001 ... CON %053505 ... LADI -007 ... LDLI +350 ... +012 L+006 Y 7 CON %020040 0 LDI +000 7 STAR 7 2 ZERD 7 ADDS +007 L+000 ... 2 STAR 2 3 LDRA 1 1 MOVW 001 0 LOR +272 +272 +001 1 +350 ... ... ... ... ... ... ... ... ... ... ... ... ... ... w HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -56 Creating and Compiling HP COBOL Source Programs Symbolic Code Listing Example 22-23. Symbolic Code Listing (COBOL85 Compiler) (page 3 of 3) 21. 21. 22. 22. 23. 23. 30. 31. 000341 000344 000352 000360 000366 000374 000376 000401 000407 000415 000423 000431 0 0 1 2 2 7 0 0 1 2 3 7 LOAD L+006 LDI +000 BUN +005 RDP ONED BUN +070 LOAD L+006 LDI +000 BUN +004 LADI -005 LDLI +350 INDC %000034 7 1 1 2 3 7 7 1 1 2 4 CMPI +004 LADR S-000 CON %020040 LADI -006 LDLI +350 INDC %000070 CMPI +005 LADR S-000 CON %020040 LLS 01 LDI -005 000432 000435 000443 000451 000457 000465 000472 0 0 1 2 2 1 7 LOAD LDI BUN RDP ONED LDD PCAL 7 1 1 2 3 3 7 CMPI +006 LADR S-000 CON %020040 LADI -006 LDLI +350 ONED PCAL 000 L+006 +000 +005 L+007,I 000 7 1 1 2 4 BNEQ +032 LADI +00 ... CON %052110 ... LLS 01 ... LDI -005 ... 7 1 1 3 7 BNEQ +031 LADI +001 ... CON %043122 ... LDI +010 ... PUSH 744 ... 7 1 1 2 4 1 7 BNEQ +030 LADI +001 ... CON %051501 ... LLS 01 ... LDI -005 ... DADD ... INDC %177403 8 Example 22-24. Symbolic Code Listing (NMCOBOL Compiler) (page 1 of 6) 1. 2. 2. 2. 2. 2. 2. 2. 2. 2. 2. 2. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. ?ENV COMMON;INNERLIST IDENTIFICATION DIVISION. 00000000 27bdffb0 addiu sp,sp,0xffffffb0 00000004 afbf0014 sw ra,0x14(sp) 00000008 3c010000 lui at,0 0000000c 24260000 addiu a2,at,0 00000010 3c04c000 lui a0,0xc000 00000014 0c00fffa jal COBLIB_INITIALIZER_ 00000018 00002825 move a1,zero 0000001c 8fbf0014 lw ra,0x14(sp) 00000020 00000000 nop 00000024 03e00008 jr ra 00000028 27bd0050 addiu sp,sp,0x50 PROGRAM-ID. TESTT. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. ABD. OBJECT-COMPUTER. ABD. DATA DIVISION. WORKING-STORAGE SECTION. 01 D PICTURE 9 USAGE COMPUTATIONAL. 01 STD-DATE PICTURE 9(8) USAGE COMPUTATIONAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -57 Creating and Compiling HP COBOL Source Programs Symbolic Code Listing Example 22-24. Symbolic Code Listing (NMCOBOL Compiler) (page 2 of 6) 12. 12. 12. 12. 12. 12. 12. 12. 12. 12. 12. 12. 12. 12. 12. PROCEDURE DIVISION. 00000000 27bdfe38 addiu sp,sp,0xfffffe38 00000004 3c010000 lui at,0 00000008 3c0f0000 lui t7,0 0000000c 25ef0014 addiu t7,t7,0x14 00000010 242e0000 addiu t6,at,0 00000014 afbf001c sw ra,0x1c(sp) 00000018 afae0058 sw t6,0x58(sp) 0000001c afaf0054 sw t7,0x54(sp) 00000020 0c00ffec jal COBLIB_INITIALIZATION_COMPLETE_ 00000024 00002025 move a0,zero 00000028 3c010000 lui at,0 0000002c 9438001e lhu t8,0x1e(at) 00000030 afa00080 sw zero,0x80(sp) 00000034 33198000 andi t9,t8,0x8000 12. 12. 12. 12. 12. 12. 12. 12. 12. 12. 12. 14. 14. 12. 12. 00000038 0000003c 00000040 00000044 00000048 0000004c 00000050 00000054 00000058 0000005c 00000060 00000064 00000068 0000006c 00000070 13. 14. 14. 14. 14. 14. 14. 14. 14. + + 13200008 00000000 3c048000 2405007f 00003025 0c00ffe1 00003825 0c00ffdf 00002025 3c010000 9428001e 3c0a0130 354aba3a 3509b400 a429001e beq nop lui li move jal move jal move lui lhu lui ori ori sh t9,zero,0x5c a0,0x8000 a1,0x7f a2,zero COBLIB_ERROR_ a3,zero COBLIB_ABEND_ a0,zero at,0 t0,0x1e(at) t2,0x130 t2,t2,0xba3a t1,t0,0xb400 t1,0x1e(at) STARTT. PERFORM VARYING STD-DATE FROM 19970618 BY 1 UNTIL STD-DATE > 19970624 00000074 af8a0004 sw t2,0x4(gp) 00000078 8f8b0004 lw t3,0x4(gp) 0000007c 3c010130 lui at,0x130 00000080 3421ba41 ori at,at,0xba41 00000084 0161082a slt at,t3,at 00000088 102000a2 beq at,zero,0x314 0000008c afab0044 sw t3,0x44(sp) HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -58 Creating and Compiling HP COBOL Source Programs Symbolic Code Listing Example 22-24. Symbolic Code Listing (NMCOBOL Compiler) (page 3 of 6) 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. DISPLAY STD-DATE 00000090 afa0002c sw zero,0x2c(sp) 00000094 8fae002c lw t6,0x2c(sp) 00000098 8f8d0004 lw t5,0x4(gp) 0000009c afae0034 sw t6,0x34(sp) 000000a0 afad0030 sw t5,0x30(sp) 000000a4 8faf0030 lw t7,0x30(sp) 000000a8 8fb80034 lw t8,0x34(sp) 000000ac 27ac0040 addiu t4,sp,0x40 000000b0 afac003c sw t4,0x3c(sp) 000000b4 07010007 bgez t8,0xd4 000000b8 afaf0038 sw t7,0x38(sp) 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. 000000bc 000000c0 000000c4 000000c8 000000cc 000000d0 000000d4 000000d8 000000dc 000000e0 000000e4 000000e8 000000ec 2419002d a1990000 8fa8003c 00000000 25090001 afa9003c 8faa0034 8fab0038 afaa002c afab0030 8fa50030 8fa4002c 8fa6003c li t9,0x2d sb t9,0(t4) lw t0,0x3c(sp) nop addiu t1,t0,0x1 sw t1,0x3c(sp) lw t2,0x34(sp) lw t3,0x38(sp) sw t2,0x2c(sp) sw t3,0x30(sp) lw a1,0x30(sp) lw a0,0x2c(sp) lw a2,0x3c(sp) 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. 15. 000000f0 000000f4 000000f8 000000fc 00000100 00000104 00000108 0000010c 00000110 00000114 00000118 0000011c 0c00ffb8 24070008 8fad003c 27af0040 25ae0008 afae003c 01cf3023 01e02825 3c04d000 00003825 0c00ffae afa00010 jal $n_CQA_T1 li a3,0x8 lw t5,0x3c(sp) addiu t7,sp,0x40 addiu t6,t5,0x8 sw t6,0x3c(sp) subu a2,t6,t7 move a1,t7 lui a0,0xd000 move a3,zero jal COBLIB_DISPLAY_ sw zero,0x10(sp) 16. MOVE FUNCTION REM (FUNCTION INTEGER-OF-DATE (STD-DATE) 7) TO D 00000120 8f980004 lw t8,0x4(gp) 00000124 3c04c000 lui a0,0xc000 00000128 24060002 li a2,0x2 0000012c afb80038 sw t8,0x38(sp) 00000130 0c00ffa8 jal COBLIB_FUNC_DATES_ 00000134 03002825 move a1,t8 00000138 afa20034 sw v0,0x34(sp) 0000013c 8fb90034 lw t9,0x34(sp) 00000140 24010007 li at,0x7 00000144 0321001a div t9,at 16. 16. 16. 16. 16. 16. 16. 16. 16. 16. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -59 Creating and Compiling HP COBOL Source Programs Symbolic Code Listing Example 22-24. Symbolic Code Listing (NMCOBOL Compiler) (page 4 of 6) 16. 16. 16. 16. 16. 16. 16. 16. 16. 16. 16. 16. 00000148 0000014c 00000150 00000154 00000158 0000015c 00000160 00000164 00000168 0000016c 00000170 00000174 2401000a 240c0007 afac003c afb90040 00004012 000848c0 01284823 03295023 0141001a afaa0044 00005812 000b6880 li li sw sw mflo sll subu subu div sw mflo sll at,0xa t4,0x7 t4,0x3c(sp) t9,0x40(sp) t0 t1,t0,3 t1,t1,t0 t2,t9,t1 t2,at t2,0x44(sp) t3 t5,t3,2 16. 16. 16. 16. 16. 16. 17. 17. 17. 16. 00000178 0000017c 00000180 00000184 00000188 0000018c 00000190 00000194 00000198 0000019c 01ab6821 000d6840 014d7023 05c10002 01c07825 000e7823 000fc400 00186403 1580000a a78f0000 addu sll subu bgez move subu sll sra bne sh t5,t5,t3 t5,t5,1 t6,t2,t5 t6,0x190 t7,t6 t7,zero,t6 t8,t7,16 t4,t8,16 t4,zero,0x1c4 t7,0(gp) + + + 17. 17. 17. 17. 17. 17. 17. 17. 17. 17. IF D = 0 THEN 000001a0 3c010000 000001a4 24250028 000001a8 3c04d000 000001ac 24060008 000001b0 00003825 000001b4 0c00ff87 000001b8 afa00010 000001bc 1000004d 000001c0 00000000 18. 18. 18. 18. 18. 18. 18. 18. 18. 18. 18. 18. 18. 18. 000001c4 000001c8 000001cc 000001d0 000001d4 000001d8 000001dc 000001e0 000001e4 000001e8 000001ec 000001f0 000001f4 DISPLAY " SUNDAY" ELSE lui at,0 addiu a1,at,0x28 lui a0,0xd000 li a2,0x8 move a3,zero jal COBLIB_DISPLAY_ sw zero,0x10(sp) b 0x2f4 nop IF D = 1 THEN DISPLAY " MONDAY" ELSE 87880000 lh t0,0(gp) 24010001 li at,0x1 1501000a bne t0,at,0x1f8 a7a80044 sh t0,0x44(sp) 3c010000 lui at,0 24250030 addiu a1,at,0x30 3c04d000 lui a0,0xd000 24060008 li a2,0x8 00003825 move a3,zero 0c00ff7a jal COBLIB_DISPLAY_ afa00010 sw zero,0x10(sp) 10000040 b 0x2f4 00000000 nop HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -60 Creating and Compiling HP COBOL Source Programs Symbolic Code Listing Example 22-24. Symbolic Code Listing (NMCOBOL Compiler) (page 5 of 6) 19. 19. 19. 19. 19. 19. 19. 19. 19. 19. 19. 19. 19. 19. 000001f8 000001fc 00000200 00000204 00000208 0000020c 00000210 00000214 00000218 0000021c 00000220 00000224 00000228 IF D = 2 THEN DISPLAY " TUESDAY" ELSE 87990000 lh t9,0(gp) 24010002 li at,0x2 1721000a bne t9,at,0x22c a7b90044 sh t9,0x44(sp) 3c010000 lui at,0 24250038 addiu a1,at,0x38 3c04d000 lui a0,0xd000 24060009 li a2,0x9 00003825 move a3,zero 0c00ff6d jal COBLIB_DISPLAY_ afa00010 sw zero,0x10(sp) 10000033 b 0x2f4 00000000 nop 20. 20. 20. 20. 20. 20. 20. 20. 20. 20. 20. 20. 20. 20. 0000022c 00000230 00000234 00000238 0000023c 00000240 00000244 00000248 0000024c 00000250 00000254 00000258 0000025c IF D = 3 THEN DISPLAY " WEDNESDAY" ELSE 87890000 lh t1,0(gp) 24010003 li at,0x3 1521000a bne t1,at,0x260 a7a90044 sh t1,0x44(sp) 3c010000 lui at,0 24250044 addiu a1,at,0x44 3c04d000 lui a0,0xd000 2406000b li a2,0xb 00003825 move a3,zero 0c00ff60 jal COBLIB_DISPLAY_ afa00010 sw zero,0x10(sp) 10000026 b 0x2f4 00000000 nop 21. 21. 21. 21. 21. 21. 21. 21. 21. 21. 21. 21. 21. 21. 00000260 00000264 00000268 0000026c 00000270 00000274 00000278 0000027c 00000280 00000284 00000288 0000028c 00000290 IF D = 4 THEN DISPLAY " THURSDAY" ELSE 878b0000 lh t3,0(gp) 24010004 li at,0x4 1561000a bne t3,at,0x294 a7ab0044 sh t3,0x44(sp) 3c010000 lui at,0 24250050 addiu a1,at,0x50 3c04d000 lui a0,0xd000 2406000a li a2,0xa 00003825 move a3,zero 0c00ff53 jal COBLIB_DISPLAY_ afa00010 sw zero,0x10(sp) 10000019 b 0x2f4 00000000 nop HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -61 Creating and Compiling HP COBOL Source Programs Symbolic Code Listing Example 22-24. Symbolic Code Listing (NMCOBOL Compiler) (page 6 of 6) 22. 22. 22. 22. 22. 22. 22. 22. 22. 22. 22. 22. 22. 22. 00000294 00000298 0000029c 000002a0 000002a4 000002a8 000002ac 000002b0 000002b4 000002b8 000002bc 000002c0 000002c4 IF D = 5 THEN DISPLAY " FRIDAY" ELSE 878a0000 lh t2,0(gp) 24010005 li at,0x5 1541000a bne t2,at,0x2c8 a7aa0044 sh t2,0x44(sp) 3c010000 lui at,0 2425005c addiu a1,at,0x5c 3c04d000 lui a0,0xd000 24060008 li a2,0x8 00003825 move a3,zero 0c00ff46 jal COBLIB_DISPLAY_ afa00010 sw zero,0x10(sp) 1000000c b 0x2f4 00000000 nop 23. 23. 23. 23. 23. 23. 23. 23. 23. 23. 23. 23. 000002c8 000002cc 000002d0 000002d4 000002d8 000002dc 000002e0 000002e4 000002e8 000002ec 000002f0 878d0000 24010006 15a10008 a7ad0044 3c010000 24250064 3c04d000 2406000a 00003825 0c00ff39 afa00010 24. 25. 26. 27. 28. 29. 30. 30. 30. 30. 30. 30. 30. 30. 30. END-IF END-IF END-IF END-IF END-IF END-IF END-PERFORM. 000002f4 8f8e0004 lw t6,0x4(gp) 000002f8 00000000 nop 000002fc 25cf0001 addiu t7,t6,0x1 00000300 05e10002 bgez t7,0x30c 00000304 01e0c025 move t8,t7 00000308 000fc023 subu t8,zero,t7 0000030c 1000ff5a b 0x78 00000310 af980004 sw t8,0x4(gp) 31. 31. 31. 31. 31. 31. 31. 31. 31. STOP RUN. 00000314 0c00ff2f 00000318 00000000 0000031c 0c00ff2d 00000320 00000000 00000324 8fbf001c 00000328 00000000 0000032c 03e00008 00000330 27bd01c8 IF D = 6 THEN DISPLAY " SATURDAY" END-IF lh t5,0(gp) li at,0x6 bne t5,at,0x2f4 sh t5,0x44(sp) lui at,0 addiu a1,at,0x64 lui a0,0xd000 li a2,0xa move a3,zero jal COBLIB_DISPLAY_ sw zero,0x10(sp) jal COBLIB_STOP_ nop jal COBLIB_STOP_ nop lw ra,0x1c(sp) nop jr ra addiu sp,sp,0x1c8 HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -62 Creating and Compiling HP COBOL Source Programs Cross-Reference Listing Cross-Reference Listing Note. This topic applies only to the COBOL85 compiler. The NMCOBOL compiler does not produce a cross-reference listing. If you need one, use the noft utility with the XREFPROC flag (see the nld Manual). The COBOL85 compiler lists a cross-reference if you explicitly request it with the CROSSREF directive; however, generating a cross-reference this way slows down the compilation and, if the program has errors, the cross-reference listing might also have errors. A better way to get the cross-reference listing is by using the CROSSREF utility, after you rid the program of errors. For information about the CROSSREF utility, see the CROSSREF Manual. Example 22-25. Cross-Reference Listing ... EXPLAIN-MYSELF PROBE[1] 86 PROBE[1] PARA %000262 80 M FILE-NAME OF PROGRAM-FILE-NAME PROBE[1] 58 PROBE[1] 134 05 AN DISP WSS SIZE=8 OFFSET=16 HOME-TERMINAL PROBE[1] 59 PROBE[1] 01 AN DISP WSS SIZE=24 OFFSET=0 AN GROUP WSS SIZE=2 OFFSET=0 76 M LEFT-BYTE OF SEPARATED-BYTES PROBE[1] 32 PROBE[1] 35 M ... 104 05 Load Maps Note. This topic applies only to the COBOL85 compiler. The LMAP and NOLMAP directives determine which load maps the compiler obtains from BINSERV. The NMCOBOL compiler does not use BINSERV. The compiler lists the load maps (also called Binder maps) if you explicitly request them with the LMAP directive. With options, you can select any or all of these load maps (to select all, specify LMAP): LMAP Option Load Map ALPHA Programs and subprograms, sorted alphabetically by program name LOC Programs and subprograms, sorted by location (starting address) XREF Cross-reference listing of entry-point and data-block names The LMAP or NOLMAP directive that is active when the compiler detects the end of a source program and starts creating an object program is the one that determines which load maps appear in the compiler listing. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -63 Creating and Compiling HP COBOL Source Programs Compilation Summary Example 22-26 is an ALPHA load-map for the program in Example 31-13. Example 22-26. Load-Map (ALPHA) PAGE 10 $MYDSC.PROBSBV.PROBE Tandem COBOL85 ENTRY POINT MAP BY NAME SP PEP BASE LIMIT ENTRY ATTRS 00 002 000003 002243 000051 M $MYDSC.PROBSBV.PROBE NAME PROBE DATE TIME LANGUAGE SOURCE FILE 1/02/93 13:14 COBOL - - - - - - - - - - - - - new page - - - - - - - - - - - - - - - - - - - - - - - - PAGE 11 $MYDSC.PROBSBV.PROBE DATA BLOCK MAP BY NAME BASE LIMIT TYPE MODE NAME DATE TIME LANGUAGE SOURCE FILE 000000 000017 SPECIAL $MYDSC.PROBSBV.PROBE WORD #G0 1/02/93 13:14 COBOL 100222 SPECIAL $MYDSC.PROBSBV.PROBE WORD #HIGHBUF 1/02/93 13:14 COBOL 100000 100114 SPECIAL $MYDSC.PROBSBV.PROBE WORD #RUCB 1/02/93 13:14 COBOL 000127 000153 SPECIAL $MYDSC.PROBSBV.PROBE WORD #STACK 1/02/93 13:14 COBOL 000020 000126 OWN $MYDSC.PROBSBV.PROBE STRING PROBE 1/02/93 13:14 COBOL 100115 100221 SPECIAL $MYDSC.PROBSBV.PROBE WORD PROBE# 1/02/93 13:14 COBOL Compilation Summary The compilation summary is the last page of every compiler listing. The COBOL85 and NMCOBOL compilers produce different compilation summaries: • • COBOL85 Compiler NMCOBOL Compiler HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -64 Creating and Compiling HP COBOL Source Programs Compilation Summary COBOL85 Compiler Example 22-27. COBOL85 Compilation and BINSERV Summary Binder - OBJECT FILE Binder - T9621D20 - (8JUN92) Object file name is $SECOND.AA9210.OWOMBAT Number of Binder errors = 0 Number of Binder warnings = 0 Code size = 118 words Primary data = 16 words Secondary data = 61 words Code area size = 1 pages Resident code size = 0 pages Data area size = 33 pages Number of code spaces = 1 space SYSTEM \BACH COBOL85 - T9257D20 - (8JUN92) The object file is executable on a TNS or a TNS/II Number of COBOL errors = 0 Number of COBOL warnings = 0 Number of source lines read = 56 Maximum symbol table size = 864 words Elapsed time 0:00:19 These lines show that the program that produced Example 22-27 had no compilation errors or warnings: Number of compiler errors = 0 Number of compiler warnings = 0 These lines show that the program that produced Example 22-27 had no Binder errors: Number of Binder errors = 0 Number of Binder warnings = 0 If the COBOL85 compiler or Binder had reported any errors, the summary would have contained lines like these: COBOL85 - T9257D20 - (8JUN92) No object file produced ***** Number of COBOL errors = 6 Number of COBOL warnings = 2 Last message on page 2 Number of source lines read = 57 Maximum symbol table size = 840 words Elapsed time 0:00:29 HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -65 Creating and Compiling HP COBOL Source Programs Compilation Summary NMCOBOL Compiler Example 22-28. NMCOBOL Compilation Summary COBOL - T8107D99 - (30 APR 97) No failures detected. No errors detected. No warnings reported. No remarks issued. Maximum symbol table size = 135998 bytes NLD - NATIVE MODE LINKER - T6017D42 - 03JUN96 Copyright Tandem Computers Incorporated 1993-1996 NLD's command line was: \node1.$system.sys01.nld -o RUNUNIT RUNUNIT \NODE1.$SYSTEM.SYS01.ECOBSRL \NODE1.$SYSTEM.SYS01.ECRESRL NLD reported 0 errors. NLD reported 0 warnings. NLD reported 0 informational messages. NLD created this type of object file: RUNUNIT (ELF, executable) NLD Timestamp: Elapsed time: 16APR97 16:34:34 00:00:03 Object file: RUNUNIT Compiler driver: \NODE1.$SYSTEM.SYS01.NMCOBOL COBOL SRL: \NODE1.$SYSTEM.SYS01.ZCOBSRL CRE SRL: \NODE1.$SYSTEM.SYS01.ZCRESRL NMCOBEXT: \NODE1.$SYSTEM.SYS01.NMCOBEXT Compiler statistics phase CPU seconds elapsed time file name COBOLFE 0.1 00:00:04 \NODE1.$SYSTEM.SYS01.COBOLFE UGEN 0.1 00:00:03 \NODE1.$SYSTEM.SYS01.UGEN AS1 0.1 00:00:04 \NODE1.$SYSTEM.SYS01.AS1 total 0.4 00:00:11 These lines show that the program that produced the Example 22-28 had no compilation errors or warnings: No errors detected. No warnings detected. This line shows that, in Example 22-28, the FIPS directive identified no language elements: No remarks issued. HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -66 Creating and Compiling HP COBOL Source Programs Compilation Summary If the NMCOBOL compiler had reported any errors, the summary would have contained lines like these: COBOL - T8107D99 - (01 APR 97) No object file produced ***** Number of COBOL errors = 6 Number of COBOL warnings = 2 Last message on page 2 Number of source lines read = 57 Maximum symbol table size = 840 words Elapsed time 0:00:29 HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -67 Creating and Compiling HP COBOL Source Programs HP COBOL Manual for TNS and TNS/R Programs —522555-006 22 -68 Compilation Summary 23 Calling Other Programs and Routines Note. This section applies to the Guardian environment. For information on mixed-language programming in the OSS environment, see Mixed-Language Programs and Utility Routines. Your TNS HP COBOL program can call other TNS programs and routines, and your native HP COBOL program can call other native programs and routines. TNS and native programs cannot call each other. A HP COBOL program that calls one or more non-COBOL routines is called a mixedlanguage program (as is a non-COBOL program that calls one or more COBOL programs). Mixed-language programs are less restricted and execute more efficiently in the CRE. The CRE is available in the Guardian environment and the OSS environment. A HP COBOL program’s mode and operating environment determine what types of non-COBOL routines it can call, as Table 23-1 shows. Table 23-1. Effect of Mode and Environment on Calling Non-COBOL Programs Mode Environment HP COBOL program can call programs written in ... TNS Guardian TNS HP C, TNS HP C++, FORTRAN, Pascal, TAL OSS TNS HP C, TNS HP C++, TAL Guardian or OSS Native HP C, native HP C++, pTAL Native A called routine can have an ordinary, VARIABLE, or EXTENSIBLE parameter list. Topics: • • • • Run-Time Environment Calling Other COBOL Programs Calling Non-COBOL Routines Passing Parameters To call your HP COBOL program from a non-COBOL program, use the non-COBOL language’s method of calling an external routine. The method varies from language to language; see the reference manual for the appropriate non-COBOL language. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23- 1 Calling Other Programs and Routines Run-Time Environment Run-Time Environment Native programs (compiled with the NMCOBOL compiler) always run in the CRE. Programs compiled with the COBOL85 compiler can run in either the CRE or the nonCRE (COBOL-specific) environment. The non-CRE environment is the default for nonnative HP COBOL programs, but with the compiler directive ENV COMMON, you can request the CRE instead. HP COBOL programs running in the non-CRE environment can call non-COBOL routines, but the non-COBOL routines run in the unique run-time environments defined by their respective run-time libraries. These language-specific run-time environments are often incompatible with each other, because each language’s run-time library is unaware of other run-time libraries. This incompatibility severely limits the potential for creating useful mixed-language programs. In the non-CRE environment, the nonCOBOL routines that your HP COBOL program calls have limited access to their runtime libraries. In the CRE, each routine in the program appears to be running in its own languagespecific run-time environment, regardless of the language of the main routine. For example, if the main routine of a mixed-language program is written in HP COBOL, an HP C routine still has complete access to the HP C run-time library. All routines in a program must be compiled to run in the same environment (either their own language-specific run-time environment or the CRE). Table 23-2 lists the run-time environments available for the TNS version of each language. All native languages run only in the CRE. Table 23-2. Run-Time Environments for TNS Languages TNS Language Environments Available HP C CRE HP COBOL CRE or HP COBOL run-time environment FORTRAN CRE or FORTRAN run-time environment Pascal CRE TAL CRE or TAL run-time environment The CRE library, a collection of routines that implements the CRE, enables the language-specific run-time libraries to coexist peacefully with each other. User routines and run-time libraries call CRE library routines to access shared resources managed by the CRE, such as the standard files (input, output, and log) and the user heap, regardless of language. The CRE does not support all possible operations. For example, the CRE supports file sharing only for the three standard files: standard input, standard output, and standard log. The language-specific run-time libraries access all other files by calling run-time procedures directly, whether or not a program uses the CRE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23- 2 Calling Other Programs and Routines Calling Other COBOL Programs For more information about writing programs that use the services provided by the CRE, see the CRE Programmer’s Guide. Calling Other COBOL Programs A HP COBOL program calls another HP COBOL program with a CALL statement. The called program can be either a separately compiled HP COBOL program or a nested HP COBOL program. A nested program is usually accessible to more calling programs if it is a common program. If a called program is an initial program, its program state is initialized whenever it is called. The CALL statement can call another program statically (with the program specified at compilation time) or dynamically (with the program specified at run time). The former is more efficient; the latter is more flexible. The CALL statement can pass parameters from the calling program to the called program either by reference (the default) or by content. Topics: • • • • • • Separately Compiled HP COBOL Programs Nested HP COBOL Programs Common Programs Initial Programs Static Calls Dynamic Calls Separately Compiled HP COBOL Programs A separately compiled program is an HP COBOL source program that is not nested within any other program. A compilation unit—a collection of source statements presented to a compiler in one compilation—contains one or more separately compiled programs. Separately compiled programs in the same compilation unit can call each other. Any separately compiled program with no Linkage Section can be a main program (that is, the program with which execution begins). If more than one of the programs in a compilation unit has no Linkage Section, one program must include a MAIN directive to identify it as the main program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23- 3 Calling Other Programs and Routines Nested HP COBOL Programs Nested HP COBOL Programs Nested HP COBOL programs are contained in other HP COBOL programs. Nested programs can be directly or indirectly contained. In Figure 23-1, the compilation unit contains two separately compiled programs (Mane and Sub), which contain nested programs, and the programs have these relationships: The program ... Directly contains ... And indirectly contains ... Mane Aaa, Bbb Ccc, Ddd Aaa Nothing Nothing Bbb Ccc Ddd Ccc Ddd Nothing Ddd Nothing Nothing Sub Nothing Nothing Figure 23-1. Directly Contained Programs and Indirectly Contained Programs Program: Mane Program: Aaa Program: Bbb Program: Ccc One separately compiled program One run unit Program: Ddd Program: Sub Another separately compiled program VST501.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 23- 4 Calling Other Programs and Routines Common Programs An HP COBOL program can call any program directly contained within itself and any other separately compiled program. It cannot call a program indirectly contained within itself. The programs in Figure 23-1 can call each other: Can call the program ... The program ... Mane Mane Aaa Bbb X X Ccc Ddd Sub X Aaa X Bbb X Ccc X X Ddd X X Sub X Common Programs If a program has the COMMON clause in its Identification Division, it is called a common program, and it can be called by any program directly or indirectly contained in the program that directly contains it. In Figure 23-1, if Aaa, Bbb, and Ccc are common, the programs in Figure 23-1 can call each other: Can call the program ... The program ... Mane Mane Aaa Bbb X X X X X Aaa Bbb X Ccc X X Ddd X X Sub Ccc Ddd X X X X Sub X X X You gain no performance benefits by making Ddd common. Initial Programs If a program has the INITIAL clause in its Identification Division, it is an initial program. Its program state is initialized whenever it is called. The data in its Working-Storage Section is allocated when it is called rather than being statically allocated. For more information about initial programs, see Initial Programs. Static Calls A static call is achieved with the statement CALL program-name, where programname is an alphanumeric literal whose value is known at compilation time. programname is the PROGRAM-ID of the called program, and it can be qualified with the phrase OF file-mnemonic or IN file-mnemonic. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23- 5 Calling Other Programs and Routines Dynamic Calls Quotation marks around program-name are not required, but are recommended. If, in some eventual program maintenance, someone adds a variable named APROG to a program that already calls a program named APROG, and the name APROG is not in quotation marks, the compiler assumes that APROG refers to the variable. At run time, if the variable APROG does not contain the name of a valid program that is included in the object file, the program terminates with the error message “Called program not found.” If APROG is enclosed in quotes, the compiler recognizes it as a program name rather than a variable. A static call is more efficient than a dynamic call, but a dynamic call is more flexible. Dynamic Calls To perform a dynamic call, use the statement CALL identifier, where identifier is an alphanumeric data item whose value is not known until run time. The value of identifier is the PROGRAM-ID of the called program, but it cannot be qualified with the phrase OF file-mnemonic or IN file-mnemonic. Example 23-1 shows a CALL identifier statement in context. The identifier is ROUTINE, and at run time its value will be either POSRTN or NEG0RTN, depending on the value of TALLY. Example 23-1. CALL Identifier Statement DATA DIVISION. 01 ROUTINE PICTURE X(7). ... PROCEDURE DIVISION. ... IF TALLY IS GREATER THAN 0 MOVE "POSRTN" TO ROUTINE ELSE MOVE "NEG0RTN" TO ROUTINE CALL ROUTINE ... A program that is to be called with a CALL identifier statement cannot use standard (16-bit) addressing. The compilation is unable to validate the parameters of dynamic calls (that is, to determine whether the actual parameters of the calling program correspond to the formal parameters of the called program). Every program that a dynamic call could possibly call (in the preceding example, the programs POSRTN and NEG0RTN) must be bound or linked into the run unit or user library before you execute the program (see Binding or Linking Programs to Be Called Dynamically). HP COBOL Manual for TNS and TNS/R Programs —522555-006 23- 6 Calling Other Programs and Routines Calling Non-COBOL Routines If you want an HP COBOL program to be entirely free to call any other COBOL program that is prepared to be called, make the programs separate processes. Separate processes communicate through the file process $RECEIVE—the sender writes to a named process, and the receiver reads a file named $RECEIVE. For more information about $RECEIVE, see $RECEIVE. Calling Non-COBOL Routines The way an HP COBOL program can call a non-COBOL routine depends on its environment and whether the calling program was compiled with the PORT directive. An HP COBOL program that was not compiled with the PORT directive calls a nonCOBOL routine with the ENTER statement. An HP COBOL program that was compiled with the PORT directive and runs in the CRE calls a non-COBOL routine with either the ENTER statement or the CALL statement, which behaves like an X/Open CALL statement. Note. If the types of the actual and formal parameters do not match, the ENTER statement attempts to convert the actual parameters to the types of the formal parameters; the X/Open CALL statement reports an error instead. Applying a CANCEL statement to a non-COBOL routine that was called with an X/Open CALL statement terminates the run unit. Topics: • • • • • • • • ENTER Statement X/Open CALL Statement Functions (Routines That Return Values) Operating System Routines HP COBOL Run-Time Routines COBOL Utility Routines ENFORM Programs Restrictions on Calling Non-COBOL Routines ENTER Statement Topics: • • TNS Programs Native Programs HP COBOL Manual for TNS and TNS/R Programs —522555-006 23- 7 Calling Other Programs and Routines ENTER Statement TNS Programs If a TNS HP COBOL program is not compiled with the PORT directive, it can call routines written in TNS HP C, TNS HP C++, FORTRAN, Pascal, and TAL by using the ENTER statement. In the ENTER statement, you can specify the language of the called routine. Although you can specify the language COBOL, the COBOL85 compiler ignores any ENTER COBOL statements it encounters (to call another COBOL program, use the CALL statement). The COBOL85 compiler reports an error if the called routine was not written in the specified language, except when the specified language is HP C and the routine was written in HP C++, which the COBOL85 compiler handles as if it were HP C. The COBOL85 compiler has no way to declare that it is calling a routine that is written in an unspecified language. If you do not specify a language in the ENTER statement, you are declaring that the called routine is a TAL procedure that uses FORTRAN protocol for passing string parameters (that is, a routine that can be called by both COBOL and FORTRAN programs). The Saved Message Utility (SMU) routines are in this category. Any non-COBOL routine called by an HP COBOL program must have already been compiled, and its object program forms must be available to the COBOL85 compiler through one of the standard library files or through the SEARCH, LIBRARY, or CONSULT directive. In the non-CRE environment, if any program or routine in a loadfile is an HP COBOL program, the main program must be an HP COBOL program. In the CRE, the main program can be written in any language that runs in the CRE (that is, HP COBOL, HP C, FORTRAN, Pascal, or pTAL). Native Programs If a native HP COBOL program is not compiled with the PORT directive, it can call routines written in native HP C, native HP C++, and pTAL by using the ENTER statement. In the ENTER statement, you do not need to specify the language of the called routine, because the NMCOBOL compiler can determine the language in which the program is written. If you do specify the language, it must be C or TAL. If you specify TAL, the NMCOBOL compiler expects a pTAL program (it does not accept TAL programs). If you specify FORTRAN or Pascal, the NMCOBOL compiler reports an error. If you specify C, the compiler expects a routine written in either HP C or HP C++. Although a native HP COBOL program can use the ENTER statement to call HP C++ and pTAL programs, you cannot specify the language C++ or pTAL. Any non-COBOL routine called by an HP COBOL program must have already been compiled, and its object program forms must be available to the NMCOBOL compiler through an SRL or object file, specified through the SEARCH or CONSULT directive. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23- 8 Calling Other Programs and Routines X/Open CALL Statement X/Open CALL Statement If an HP COBOL program is compiled with the PORT directive and runs in the CRE, it can call non-COBOL routines with the CALL statement, which behaves like an X/Open CALL statement. If the called program is a function and it was compiled either by the COBOL85 compiler with the ENV COMMON directive or by the NMCOBOL compiler, the X/Open CALL statement returns its value in the special register RETURN-CODE. For more information, see Special Register RETURN-CODE. Caution. If a program compiled with the PORT directive calls a program not compiled with the PORT directive, differences in the way BINARY/COMPUTATIONAL/COMP data items are aligned in the two programs can cause data to be misread. Functions (Routines That Return Values) A function is a routine that returns a value to the calling program. COBOL has no mechanism for returning a function’s value to the calling program, but HP COBOL has two: • • GIVING Phrase Special Register RETURN-CODE GIVING Phrase The GIVING phrase allows you to specify a data item, return-value, to hold the value that the function returns. The storage operation is performed after any necessary scaling and follows the rules for an elementary MOVE TO statement (for these rules, see MOVE TO). Special Register RETURN-CODE The special register RETURN-CODE is accessible to an HP COBOL program that was compiled with the PORT directive and uses the X/Open CALL statement to call a function if either: • • The HP COBOL program and the function are TNS programs that run in the CRE, and the HP COBOL program was compiled with the ENV COMMON directive (not the LIBRARY directive). The HP COBOL program and the function are native programs. The value of the function is returned in the special register RETURN-CODE, whose description is: 01 RETURN-CODE EXTERNAL PICTURE S9(5) COMPUTATIONAL. If the value of the function is greater than 99,999, arithmetic overflow occurs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23- 9 Calling Other Programs and Routines Operating System Routines If the calling program cannot access RETURN-CODE, the value of RETURN-CODE is unchanged. Operating System Routines Operating system routines are written in TAL, pTAL, HP C, and HP C++. The language in which an operating system routine is written does not matter to the HP COBOL program that calls it. Operating system routines execute in system code space, using both system data space (for system tables) and user data space (for temporary storage). When an HP COBOL program calls an operating system routine, it uses the ENTER statement. Some operating system routines never need to be called by HP COBOL programs— file system routines, for example. File system routines are called by the HP COBOL run-time routines to do their input and output operations. Although it is possible to call file system routines explicitly from an HP COBOL program, you are advised not to apply both HP COBOL I-O statements and explicit calls to file system routines to the same file, as the HP COBOL run-time routines do significant preprocessing and postprocessing. Note. If you use operating system routines to do nowait I-O (you call a routine to do an input or output operation and then call AWAITIO to wait for the operation to finish), be aware that the HP COBOL run-time routines perform nowait I-O in some cases. The AWAITIO routine can wait for any I-O operation to complete, or wait for the I-O operation on a specific file to complete. It is best to apply AWAITIO to a specific file. Using the command PARAM WAITEDIO ON allows you some latitude, however. Examples of operating system routines that are useful to an HP COBOL program are ABEND, which signals an abnormal termination, and PURGEDATA, which erases all data in a file but does not purge the file itself. Topics: • • • • Parameters Resolution Extensible and Variable Parameter Lists Generations of Operating System Routines Parameters Guardian operating system routines are documented in the Guardian Procedure Calls Reference Manual. When calling system routines from an HP COBOL program, use Table 23-3 to determine the appropriate form for the COBOL parameters. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -10 Calling Other Programs and Routines Operating System Routines You must verify that the actual parameters in the ENTER statement (including return-value in the GIVING phrase) are of the HP COBOL types that correspond to the TAL types of the formal parameters in the operating system routine. The compiler performs the necessary conversions of sending parameters. Parameters passed by reference must match exactly. The HP COBOL data type INDEX does not correspond to any TAL or pTAL data type. Table 23-3. HP COBOL and TAL or pTAL Parameter Correspondence (page 1 of 2) TAL or pTAL Data Type COBOL Data Category Passed by Reference Passed by Value Alphabetic STRING Not applicable HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -11 Calling Other Programs and Routines Operating System Routines Table 23-3. HP COBOL and TAL or pTAL Parameter Correspondence (page 2 of 2) TAL or pTAL Data Type COBOL Data Category Passed by Reference Passed by Value Numeric COMP 9 (1) - 9 (4) INT INT INT(32) FIXED REAL REAL(64) COMP 9 (5) - 9 (9) INT(32) INT INT(32) FIXED REAL REAL(64) COMP 9 (10) - 9 (18) FIXED INT INT(32) FIXED REAL REAL(64) NATIVE-2 INT INT INT(32) FIXED REAL REAL(64) NATIVE-4 INT(32) INT INT(32) FIXED REAL REAL(64) NATIVE-8 FIXED INT INT(32) FIXED REAL REAL(64) DISPLAY STRING INT INT(32) FIXED REAL REAL(64) INDEX Not applicable Not applicable Numeric Edited STRING Not applicable Alphanumeric Edited STRING Not applicable Alphanumeric STRING Not applicable HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -12 Calling Other Programs and Routines Operating System Routines Resolution The compiler leaves operating system routines unresolved, and the loader resolves them during fixup (see Fixup). The compiler is able to leave references to operating system routine calls unresolved because a file named COBOLEXT (for the COBOL85 compiler) or NMCOBEXT (for the NMCOBOL compiler), which is part of every HP COBOL RVU, contains dummy versions of all the operating system routines. Another file, EXTDECS, contains TAL or pTAL external declarations for the environment routines and is part of every operating environment RVU. A third file, ZSYSCOB, contains HP COBOL source declarations of data items and structures for Guardian procedures and operating environment messages. There are two reasons to have your system manager change the files COBOLEXT (for the COBOL85 compiler) or NMCOBEXT (for the NMCOBOL compiler) and EXTDECS: • • You have additional routines that you want to be left unresolved until fixup (ask your system manager to add dummy versions of them to the COBOLEXT, NMCOBEXT, or EXTDECS file). The formal parameter list of one or more system routines changes from extensible to variable, in which case the EXTDECS file and the COBOLEXT or NMCOBEXT file must also change. For more information on the ZSYSCOB file, see the Guardian Application Conversion Guide. Extensible and Variable Parameter Lists An operating system routine can have an extensible or a variable parameter list. Both extensible and variable parameter lists allow you to omit unnecessary actual parameters in the ENTER statement. The difference between extensible and variable parameter lists is in what happens when new formal parameters are added to the routine, as sometimes happens to operating system routines with a new RVU of the operating environment. When new formal parameters are added to an operating system routine that has an extensible parameter list, you do not have to recompile programs that call the routine. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -13 Calling Other Programs and Routines Operating System Routines If an operating system routine’s formal parameter list changes from variable to extensible, the code that was compiled to expect a variable parameter list can usually call the new version of the routine that has an extensible parameter list (at a slight performance penalty). For more information about variable and extensible parameter lists, see the TAL Reference Manual (for TNS programs) or the pTAL Reference Manual (for native programs). Generations of Operating System Routines Like the file COBOLEXT and NMCOBEXT, the files COBOLEX1, COBOLEX0, NMCOBEX1, and NMCOBEX0 are part of every HP COBOL RVU. Like the file EXTDECS, the files EXTDECS1 and EXTDECS0 are part of every operating environment RVU. This table shows the relationship between these files. File of Operating System Routine Declarations Generation of Operating System Routines EXTDECS0 File of Dummy Versions of operating system routines COBOL85 Compiler NMCOBOL Compiler Latest COBOLEX0 NMCOBEX0 EXTDECS1 Next-to-latest COBOLEX1 NMCOBEX1 EXTDECS Second-next-to-latest COBOLEXT NMCOBEXT Different generations of the same operating system routine might have different formal parameter lists (see Extensible and Variable Parameter Lists). Because of this, programs compiled with COBOLEX0 or NMCOBEX0 might execute only on the very latest RVU of the operating environment, programs compiled with COBOLEX1 or NMCOBEX1 might execute only on the two most recent RVUs of the operating environment, and programs compiles with COBOLEXT or NMCOBEXT might execute only on the three most recent RVUs of the operating environment. Your system manager must verify that the appropriate file has the name COBOLEXT or NMCOBEXT when you compile your program. Any of the files COBOLEX0, COBOLEX1, or COBOLEXT can be named COBOLEXT. Any of the files NMCOBEX0, NMCOBEX1, or NMCOBEXT can be named NMCOBEXT. If you need to use a version of the COBOLEXT or NMCOBEXT file that is available on your system under a name other than COBOLEXT or NMCOBEXT, there are two ways to do it: • Create a subvolume containing the COBOL85 or NMCOBOL compiler and all the files it needs. Install the appropriate version of COBOLEXT or NMCOBEXT in that subvolume, under the name COBOLEXT or NMCOBEXT. Use this subvolume for your compilations; that is, instead of using a compilation command like COBOL85 /IN XYZ/ or NMCOBOL /IN XYZ/ HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -14 Calling Other Programs and Routines HP COBOL Run-Time Routines use a compilation command like RUN MYCOBVOL.COBOL85 /IN XYZ/ or RUN MYCOBVOL.NMCOBOL /IN XYZ/ where MYCOBVOL is the subvolume you created. • Use the system volume for your compilations, but use a CONSULT directive to tell the compiler to resolve external references from a file other than COBOLEXT or NMCOBEXT. HP COBOL Run-Time Routines Your HP COBOL program calls HP COBOL run-time routines implicitly, not with ENTER statements. For TNS programs, HP COBOL run-time routines are in the system library. Their names begin with “C85LIB^” or “C85LIB_.” They execute in the system library. For native programs, HP COBOL run-time routines are in the shared run-time library ZCOBSRL. Their names begin with “COBLIB_.” They execute in SRL code space. COBOL Utility Routines HP provides many COBOL utility routines that your COBOL program can call with the ENTER statement. These routines are described in Section 13, Libraries and Utility Routines. ENFORM Programs ENFORM, a component of the Encompass distributed database management system, is a powerful nonprocedural language for querying or developing reports on a relational database. If your database is described in the Data Definition Language (DDL), you can write an ENFORM query to specify the records you want from the database and the order in which you want ENFORM to deliver them. You then compile that ENFORM query into a disk file and include code in a COBOL program to start ENFORM as a separate process. The operating environment procedure ENFORMSTART initiates the query processor. Each time the ENFORMRECEIVE procedure executes, it accepts either a record that ENFORM built and transmitted to the program through the interprocess message system or an error value. The ENFORMFINISH procedure terminates the processing with the query processor. This mechanism is called the host-language interface and is documented in the ENFORM User’s Guide. You cannot use this mechanism from a Pathway server if the ENFORM routines use $RECEIVE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -15 Calling Other Programs and Routines Restrictions on Calling Non-COBOL Routines Restrictions on Calling Non-COBOL Routines TNS HP COBOL programs can call only TNS programs, and native HP COBOL programs can call only native routines. This means that a TNS HP COBOL program can call routines written in TNS HP C, FORTRAN, Pascal, and TAL, and that a native HP COBOL program can call routines written in native HP C, native HP C++, and pTAL. These topics explain the restrictions on calling non-COBOL routines from HP COBOL. For information about passing HP COBOL parameters to such routines, see Passing Parameters to Non-COBOL Routines. Topics: • • • • • HP C Routines HP C++ Function Name Consideration FORTRAN Routines Pascal Routines TAL Routines HP C Routines An HP COBOL program running in the non-CRE environment cannot call any HP C function that directly or indirectly allocates or deallocates memory or performs HP C input-output operations. Similarly, an HP COBOL program must not call an HP C function that directly or indirectly accesses the HP C function getenv. An HP COBOL program running in the CRE indirectly calls HP C functions that allocate and deallocate memory and perform HP C input-output operations. Do not directly call the HP C function getenv from an HP COBOL program. If a program has a COBOL MAIN program, and calls HP C or HP C++ functions that perform HP C or HP C++ I/O operations on the standard files stdin, stdout, or stderr, the HP C library function fopen_std_file must be called before any such operations take place. You need fopen_std_file (0,x ) for input, fopen_std_file (1,x ) for output, and fopen_std_file (2,x ) for the stderr. This function must be called from an HP C or HP C++ routine. Also, the HP C program must be compiled “with extensions” if you are going to call this function. See the Guardian Native C Library Calls Reference Manual for more information on the fopen_std_file function. In both the non-CRE environment and the CRE, an HP COBOL program cannot call an HP C function that has these characteristics: • • Has lowercase letters in its name, if the HP C function is called by ENTER (the compiler upshifts them). This restriction does not apply to HP C functions called by CALL. Has a variable parameter list. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -16 Calling Other Programs and Routines • • Restrictions on Calling Non-COBOL Routines Returns a structured value. Specifies a formal parameter whose type has no corresponding HP COBOL type (to see which HP C types have corresponding HP COBOL types, see Appendix B, Data Type Correspondence. A HP COBOL program and an HP C program can share data under these conditions: • • • • • • • The HP COBOL and HP C programs are compiled with compilers of RVU D20.00 or later. The HP COBOL and HP C programs run in the CRE. If the HP COBOL program is compiled with the COBOL85 compiler (as opposed to the NMCOBOL compiler), its external data is in the Extended-Storage Section. Level-01 HP COBOL data items are described with the EXTERNAL clause. HP C data names that the HP COBOL program references have no lowercase letters or underscores. For TNS processes, the HP C program uses the large memory model (because HP COBOL passes all parameter addresses in 32 bits). (All native languages pass parameter addresses in 32 bits.) If the HP COBOL and HP C programs are sharing strings, the strings end in the zero byte that HP C expects. In Example 23-2, the HP COBOL and HP C programs share the data item MYVAR. Example 23-2. HP COBOL and HP C Programs Sharing Data HP COBOL Code: * The SEARCH directive references the HP C object file. ?SYMBOLS; ENV COMMON; SEARCH SHOWEXTO IDENTIFICATION DIVISION. PROGRAM-ID. TEST-EXTERNAL. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES. SYMBOLIC NULLCHAR IS 1. DATA DIVISION. EXTENDED-STORAGE SECTION. 01 MYVAR EXTERNAL. 05 DATA-01 PIC X(20). 05 NULL-TERM PIC X. PROCEDURE DIVISION. STARTIT. MOVE "abcdefghijlmnopqrstu" TO DATA-01. MOVE NULLCHAR TO NULL-TERM. ENTER C "SHOWEXT". DISPLAY "Back in COBOL: " DATA-01. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -17 Calling Other Programs and Routines Restrictions on Calling Non-COBOL Routines Example 23-2. HP COBOL and HP C Programs Sharing Data HP C Code: #includenolist extern char MYVAR[21]; void SHOWEXT(void){ int i; /* In the Guardian environment, the call to fopen_std_file is needed because the main program is in HP COBOL. In the OSS environment, comment out or delete the call to fopen_std_file */ fopen_std_file(1, 1); /* stdout, die_on_error = TRUE */ printf(" Input value: %s\n", MYVAR); for ( i=0; i < 20; i++) MYVAR[i] -= 32; printf(" Output value: %s\n", MYVAR); } /* shift case */ HP C++ Function Name Consideration When a COBOL program calls a function compiled by HP C++, the function definition must include the extern "C" specification for the function name to be used in its original form. HP C++, by default, adjusts function names to accommodate generic functions and class methods. For example, a definition such as: void EXT(char *p) {} results in the creation of an entry point called EXT_FPc; however, a definition of the form: extern "C" void EXT(char *p) {} produces an entry point called EXT. This is true for both COBOL85 and NMCOBOL, in both the Guardian environment and the OSS environment. FORTRAN Routines Only TNS HP COBOL programs in the Guardian environment can call FORTRAN routines. If you want your native HP COBOL program to call a FORTRAN routine, convert the FORTRAN routine to native HP COBOL, native HP C, native HP C++, or pTAL. In the non-CRE environment, if an HP COBOL program calls a FORTRAN routine, process termination must be handled by an HP COBOL routine. If execution terminates in FORTRAN code, the run-time routines do not have a chance to complete any possible pending input-output operations, and lines of printer or terminal output are likely to be lost. This restriction does not apply in the CRE, because HP COBOL and FORTRAN routines can share IN, OUT, and $RECEIVE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -18 Calling Other Programs and Routines Passing Parameters In both the non-CRE environment and the CRE, if a program includes both HP COBOL and FORTRAN routines, all input-output operations done on a particular file must be performed within one language, or by routines provided by HP. Pascal Routines Only TNS HP COBOL programs in the Guardian environment can call Pascal routines. If you want your native HP COBOL program to call a Pascal routine, convert the Pascal routine to native HP COBOL, native HP C, native HP C++, or pTAL. In the non-CRE environment, an HP COBOL program must not call any Pascal procedure or function that directly or indirectly allocates or deallocates controlled storage or performs Pascal input-output operations. In both the non-CRE environment and the CRE, in order for an HP COBOL program to call a Pascal routine, the Pascal routine must be exported (declared in an EXPORT list in its own Pascal module). TAL Routines Only TNS HP COBOL programs can call TAL routines. If you want your native HP COBOL program to call a TAL routine, convert the TAL routine to pTAL (see the pTAL Conversion Guide). In the non-CRE environment, if a TAL routine is available to both COBOL and FORTRAN programs (as the SMU routines before RVU D20.00 are), do not specify the language (TAL) after the keyword ENTER. By omitting the language specifier, you declare that you are calling a routine that was compiled by the TAL compiler but uses FORTRAN protocol for passing string parameters. In the CRE, specifying “TAL” after the keyword ENTER is recommended. Passing Parameters Topics: • • • • • • • TNS Addressing Modes Native Addressing Modes What HP COBOL Can Pass by Content What HP COBOL Can Pass by Reference What HP COBOL Can Pass by Value. Passing Parameters to COBOL Programs Passing Parameters to Non-COBOL Routines HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -19 Calling Other Programs and Routines TNS Addressing Modes TNS Addressing Modes TNS HP COBOL programs use standard (16-bit) addressing for all items in the File Section, all items in the Working-Storage Section, and items in the Linkage Section for which standard access mode is specified. HP COBOL programs use extended (32-bit) addressing for all items in the Extended-Storage Section and all items in the Linkage Section for which the standard access mode is not specified. Programs written in languages other than COBOL use both 16-bit and 32-bit addressing, with certain data structures always using 32-bit addressing. When a formal reference parameter (in the called routine) is 16-bit-addressed, the corresponding actual parameter (in the calling routine) can be any HP COBOL data item except a special register or an item declared in the Linkage Section or ExtendedStorage Section. When a formal reference parameter (in the called routine) is 32-bit-addressed, the corresponding actual parameter (in the calling routine) can be any HP COBOL data item except a special register. When an HP COBOL program passes a 32-bit-addressed parameter to a routine that expects a 16-bit-addressed parameter, the COBOL85 compiler performs the necessary conversion. The passed data item must begin in the leftmost byte of a word. If the data item begins (or can begin) in a byte other than the leftmost byte, the compiler delivers a warning, and it is your responsibility to verify that the addressing is correct. In a called routine, the code that handles actual parameters from the calling routine is generated according to the addressing mode that the called routine specifies for the formal parameters. This code can include both instructions that use 16-bit addressing and instructions that use 32-bit addressing. Instructions that use 16-bit addressing execute faster, but cannot address items in extended memory. Native Addressing Modes Native programs use 32-bit addressing for all data items. Many HP COBOL data items are byte-addressed. Some data items in other languages are 2-byte addressed. When you pass a byte-addressed item to a routine that expects a 2-byte-addressed parameter, the data item must be aligned on a 2-byte boundary; otherwise, problems can arise, because the called routine is expecting an aligned parameter. Special registers are not addressable data items. If passed as parameters, they must be passed by value. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -20 Calling Other Programs and Routines What HP COBOL Can Pass by Content What HP COBOL Can Pass by Content An HP COBOL program can pass these types of items to non-COBOL routines by content: • • • • • Elementary Data Items Tables Numeric Literals Values of Arithmetic Expressions HP COBOL File Names Elementary Data Items The most practical categories and sizes for elementary data item parameters to be passed by content are: Parameter Category and Size USAGE Numeric 2-byte NATIVE-2 Numeric 4-byte NATIVE-4 Numeric 8-byte NATIVE-8 Alphanumeric PICTURE X(n ) The names of elementary data item parameters can be qualified, subscripted, or both, but cannot include reference modifiers. Passing a COMPUTATIONAL numeric data item as a parameter is not recommended. Although a data item described as PICTURE S9(4) USAGE COMPUTATIONAL is allocated 2 bytes, the value that can be stored in them must be in the COMPUTATIONAL range -9999 through 9999. Anything outside that range is truncated on the left by the MOVE operation. The compiler generates any code necessary to convert numeric actual parameters to the form required by the external routine, including scaling and conversion to the required storage size and data type. Similarly, the compiler generates any code that is necessary to convert the numeric value that an external routine returns to the form required by the data item in the GIVING phrase of the HP COBOL program’s ENTER statement. The other CRE languages handle nonnumeric data items as strings. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -21 Calling Other Programs and Routines What HP COBOL Can Pass by Content Tables To pass a table (an array) by content, you must create a data structure that consists solely of the array elements and pass the name of that data structure. The corresponding formal parameter must be defined to use a content parameter. For example, to pass the table of Cs in Example 23-3, you must pass the name C-ARRAY. Example 23-3. Record Containing a Table 01 A-RECORD. 03 A PIC S999V99. 03 B PIC S999V99. 03 C-ARRAY. 05 C OCCURS 7 TIMES USAGE NATIVE-2. 03 D PIC X(15). HP COBOL handles any data structure as a stream of characters, so the compiler does not perform numeric conversions on table elements. If you have a table of elements whose descriptions do not match those of their corresponding formal parameters, you must create a new table whose element descriptions match exactly, copy the values form the original table to the new table, and pass the name of the new table as the actual parameter. Numeric Literals HP COBOL can pass numeric literals, but not nonnumeric literals, as content parameters. The compiler generates any code that is necessary to convert them to the form required by the external routine. Values of Arithmetic Expressions TNS HP COBOL can pass the value of an arithmetic expression to HP C, Pascal, and TAL (but not FORTRAN) routines by content. Native HP COBOL can pass the value of an arithmetic expression to native HP C, native HP C++, and pTAL routines by content. The compiler generates any code that is necessary to convert the value of an arithmetic expression to the form required by the external routine. HP COBOL File Names HP COBOL can pass COBOL file names to COBOLLIB and ZCOBSRL routines that accept them. The COBOL file name is the file name recognized by the HP COBOL program’s input-output statements, not the file name recognized by the operating environment. The data structures that enable the COBOLLIB and ZCOBSRL routines to accept COBOL file names are proprietary to HP and are not available to users. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -22 Calling Other Programs and Routines What HP COBOL Can Pass by Reference What HP COBOL Can Pass by Reference An HP COBOL program can pass these to non-COBOL routines by reference: • • Elementary Data Items Records Elementary Data Items The only elementary data items that HP COBOL programs can always pass by reference are NATIVE-2, NATIVE-4, NATIVE-8, and PICTURE X (n ) data items. If an external routine stores an integer value in a COMPUTATIONAL numeric data item, and that value exceeds HP COBOL’s limits (4 decimal digits for 16 bits of storage, 9 decimal digits for 32 bits of storage, and 18 decimal digits for 64 bits of storage), results from using the contents of that data item are unpredictable—the program might work as expected, not work as expected, or terminate abnormally. HP COBOL programs can also pass by reference a numeric data item with a PICTURE containing V or P, but only if the corresponding formal parameter is the equivalent of an 8-byte integer and the HP COBOL program and external routine agree on an interpretation. Some values on NonStop systems that fit into a HP COBOL data item described as PICTURE S9(n -s)V9(s ) COMPUTATIONAL exceed HP COBOL’s limits. More importantly, HP COBOL generates computational code based on the descriptions of data items, so if an external routine installs a value in a PICTURE S9(n -s )V9(s ) COMPUTATIONAL field that HP COBOL could not have stored, the computational results could be invalid. Records HP COBOL programs must pass record parameters by reference. What HP COBOL Can Pass by Value A HP COBOL program can pass these types of items to non-COBOL routines by value: • • • • Numeric literals Numeric data items Special registers Arithmetic expressions If a parameter is passed by value, it is evaluated, scaled, and converted to the storage size and type of the formal parameter. The resulting value is passed to the called routine. This conversion might cause an arithmetic overflow. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -23 Calling Other Programs and Routines Passing Parameters to COBOL Programs Passing Parameters to COBOL Programs A COBOL program can pass parameters to another COBOL program with the CALL statement. A non-COBOL routine can pass parameters to a COBOL program with the nonCOBOL language’s method of calling an external routine. The method varies from language to language; see the reference manual for appropriate non-COBOL language. Topics: • • From HP COBOL Programs From Non-COBOL Routines From HP COBOL Programs By default, the CALL statement passes parameters by reference. This means that the called program can change the value of the parameter that is stored in the calling program. You can specify that the CALL statement is to pass a parameter by content instead of by reference. This means that the called program cannot change the value of the parameter that is stored in the calling program. To specify that a parameter is to be passed by content, specify CONTENT in a USING phrase in the CALL statement. A COBOL program can pass a program name (a program-name in a PROGRAM-ID paragraph) as a parameter to another COBOL program (see Dynamic Calls). From Non-COBOL Routines When calling a COBOL program from a non-COBOL program, remember that: • • • A non-COBOL program must pass any parameters to COBOL program by reference. A non-COBOL program cannot pass a program name (a program-name for a PROGRAM-ID paragraph) to a COBOL program as a parameter. COBOL has no single-byte numeric data type that corresponds to: ° ° ° HP C and C++ data types char and unsigned char Pascal data type BYTE pTAL data types UNSIGNED(8) and STRING Enabling HP COBOL to obtain a numeric value from a single byte requires a workaround in the HP COBOL program. In your HP COBOL program, define a corresponding parameter and a temporary storage area, as in Example 23-4. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -24 Calling Other Programs and Routines Passing Parameters to Non-COBOL Routines Example 23-4. TAL/pTAL Structures for Passing Parameters to COBOL Program TAL or pTAL declaration: STRUCT M; BEGIN INT X; STRING Y; UNSIGNED(8) Z; END; Corresponding HP COBOL parameter: 01 STRUCT-M. 03 X USAGE NATIVE-2. 03 YZ. 05 Y PIC X. 05 Z PIC X. HP COBOL temporary storage area: 01 TEMP-COMP. 03 ONE-WORD-NUMERIC USAGE NATIVE-2. 03 CHEATER REDEFINES ONE-WORD-NUMERIC. 05 FILLER PIC X. 05 LOW-HALF PIC X. In Example 23-4, when a non-COBOL routine (or a READ statement) has delivered a value to STRUCT-M, the HP COBOL program must move a numeric zero to ONEWORD-NUMERIC and move the single-byte numeric value from either Y or Z into LOW-HALF. Then the HP COBOL program can use ONE-WORD-NUMERIC as a numeric value. For example, this code tests whether the value of Y is greater than 9: MOVE ZEROS TO ONE-WORD-NUMERIC. MOVE Y TO LOW-HALF IF ONE-WORD-NUMERIC > 9 ... Passing Parameters to Non-COBOL Routines Whether the ENTER statement passes parameters by reference or by value depends on what the called routine requires. The compiler determines whether the called routine requires a reference parameter or a value parameter. If the called routine requires a reference parameter, the compiler generates code that passes an address; if the called routine requires a value parameter, the compiler generates code that passes a value. (A called program can change the value of a reference parameter but not a value parameter.) If the compiler cannot locate the object form of the called program or routine, or at least a dummy version that describes the expected parameters, then it cannot determine whether the parameters are to be passed by reference; therefore, it cannot generate the appropriate code, so it reports an error and does not produce an object program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -25 Calling Other Programs and Routines Passing Parameters to Non-COBOL Routines If a parameter is passed by reference so that the called routine can return a value to the calling program, the parameter declaration must match the expectation of the called routine, because HP COBOL code does not convert the values upon return from the routine. A COBOL program cannot pass a program name (a program-name in a PROGRAMID paragraph) to a non-COBOL routine as a parameter. Topics: • • • • HP C or HP C++ FORTRAN Pascal TAL and pTAL HP C or HP C++ In the large-memory model and the wide-data model, all pointers are 32 bits. In both the non-CRE environment and the CRE: • • • • • • A HP COBOL program can pass numeric arguments to an HP C or HP C++ routine either by reference or by value. A HP COBOL program must pass nonnumeric arguments to an HP C or HP C++ routine by reference. If the data type of a value parameter differs from the data type of the corresponding formal parameter, the compiler converts the value of the value parameter to the data type of the formal parameter. If the value is outside the range of values allowed for the HP C or HP C++ data type, an arithmetic trap occurs. The compiler cannot convert reference parameters to different data types. A HP COBOL program can pass an integer (NATIVE-2, NATIVE-4, or NATIVE-8) data item to an HP C or HP C++ routine either as a reference parameter or by an external declaration. In both cases, the HP C or HP C++ routine receives the integer as a pointer type. The GIVING phrase cannot be specified in an ENTER statement that accesses an HP C or HP C++ function whose type is a pointer or whose type designation includes the modifier “unsigned.” The type “char” is included in this prohibition, because both the HP C compiler and the HP C++ compiler interpret it as equivalent to the type “unsigned char.” The type “signed char” is acceptable. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -26 Calling Other Programs and Routines Passing Parameters to Non-COBOL Routines HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -27 Calling Other Programs and Routines • Passing Parameters to Non-COBOL Routines When the formal parameter for an HP C or HP C++ function is a scalar variable, its type designation cannot include the modifier “unsigned.” When the COBOL parameter is numeric, the type “char” is included in this prohibition, because the HP C or HP C++ compiler interprets it as equivalent to the type “unsigned char.” The type “signed char” is acceptable. When the COBOL parameter is not numeric, the type “char” is acceptable. For more information about HP C or HP C++ routines and modules, see the C/C++ Programmer’s Guide and the Guardian Native C Library Calls Reference Manual. In Example 23-5, an HP COBOL program uses reference parameters to pass integer data items to a C routine. On return from the ENTER statement in the HP COBOL code, SQ contains the product of PAR1, PAR2, and PAR3, and the value of PAR3 is 25. Example 23-5. Using Reference Parameters to Pass Integers to C Routine HP COBOL code: 01 PARAMS. 03 PAR1 USAGE IS NATIVE-2. 03 PAR2 USAGE IS NATIVE-4. 03 PAR3 USAGE IS NATIVE-8. 01 SQ USAGE IS NATIVE-8. ... ENTER C "blog" USING PAR1 PAR2 PAR3 GIVING SQ ... C code: long long blog (int *a, long *b, long long *c) { long long result; ... result = *a * *b * *c; c = 25; return result; } In Example 23-6, an HP COBOL program uses external declarations to pass integer data items to a C routine. If the C routine was compiled for the small memory model, the values are manipulated with explicit casts to pointers. Example 23-6. Using External Declarations to Pass Integers to C Routine (page 1 of 2) External declarations in HP COBOL: 01 FLIP USAGE IS NATIVE-2 EXTERNAL. 01 FLAP USAGE IS NATIVE-4 EXTERNAL. 01 FLOP USAGE IS NATIVE-8 EXTERNAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -28 Calling Other Programs and Routines Passing Parameters to Non-COBOL Routines Example 23-6. Using External Declarations to Pass Integers to C Routine (page 2 of 2) C code: char *work; /* global to share with HP COBOL program */ int x; ... work = (char*)malloc(2); ... x = *(int*)flip; *(int*)flip++; y = ... Example 23-7. Passing a String to a C Routine HP COBOL code: DATA DIVISION. WORKING-STORAGE SECTION. 01 A-STRING PICTURE X(25). ... PROCEDURE DIVISION. ... ENTER C "FUNCT1" USING A-STRING C routine: FUNCT1 (char *d) ... return void; FORTRAN Note. This topic applies only to TNS HP COBOL programs. Native HP COBOL programs cannot call FORTRAN routines. If you want your native HP COBOL program to call a FORTRAN routine, convert the FORTRAN routine to native HP C, native HP C++, or pTAL. By default, FORTRAN routines use 16-bit addressing for parameters. You can specify 32-bit addressing using either of two FORTRAN compiler directives: EXTENDEDREF or LARGECOMMON (LARGECOMMON also specifies that common blocks are to be allocated in extended memory). Each FORTRAN routine uses the same addressing mode for all parameters it receives or passes. All FORTRAN routines bound into one object file must use the same addressing mode. You must pass parameters to FORTRAN routines by reference. To pass a noninteger numeric value to a FORTRAN routine, an HP COBOL program must pass a COMPUTATIONAL item of 2, 4, or 8 bytes and either pass a scale factor (power of 10) as a separate parameter or have an agreed-upon scale factor for the item. The FORTRAN program must receive the parameter as an integer of the appropriate size and perform the corresponding scaling operation explicitly. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -29 Calling Other Programs and Routines Passing Parameters to Non-COBOL Routines In both the non-CRE environment and the CRE: • • An HP COBOL program cannot pass anything to a formal FORTRAN parameter of the type COMPLEX. FORTRAN stores multidimensional arrays in column-major order and HP COBOL stores them in row-major order. To illustrate, FORTRAN declares the array DIMENSION X (3,2) and allocates memory for its elements in this order: X(1,1), X(2,1), X(3,1), X(1,2), X(2,2), X(3,2) HP COBOL would allocate memory for the same array (table) elements in this order: X(1,1), X(1,2), X(2,1), X(2,2), X(3,1), X(3,2) For more information about FORTRAN routines, see the FORTRAN Reference Manual. Example 23-8. Passing Parameters to a FORTRAN Routine COBOL95 code: ... * DOUBLEWORDS, SCALED BY 1000, SO THAT THE VALUE DELIVERED * IS THE NUMBER OF THOUSANDTHS 01 THE-PARAMETER USAGE IS COMPUTATIONAL. 03 BASE PICTURE S9(5)V9(3). 03 POWER PICTURE S9(5)V9(3). 03 RAISED PICTURE S9(5)V9(3). ... MOVE 89 TO BASE. MOVE .5 TO POWER ENTER FORTRAN "ROUTINEX" USING BASE POWER GIVING RAISED. ... FORTRAN code: C C INTEGER*4 FUNCTION ROUTINEX ( IA, IB ) INTEGER*4 IA, IB DOUBLE PRECISION DA, DB SCALE DOWN DA = DBLE (IA) / 1000 DB = DBLE (IB) / 1000 RAISE TO POWER AND SCALE UP BEFORE GOING ON ROUTINEX = INT4 ( (DA ** DB) * 1000.D0) RETURN END HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -30 Calling Other Programs and Routines Passing Parameters to Non-COBOL Routines Pascal Note. This topic applies only to TNS HP COBOL programs. Native HP COBOL programs cannot call Pascal routines. If you want your native HP COBOL program to call a FORTRAN routine, convert the Pascal routine to native HP C, native HP C++, or pTAL. By default, Pascal routines use 16-bit addressing for parameters and pointer allocation (the “small-memory model”). You can specify 32-bit addressing by using the Pascal compiler directive XMEM (the “large memory model”), but whatever the addressing mode is, it applies to the entire Pascal module. All Pascal modules that are bound into one object file must use the same addressing mode. In both the non-CRE environment and the CRE: • • The default addressing mode is extended (32-bit) in HP COBOL but 16-bit in Pascal. You can specify standard (16-bit) addressing in HP COBOL with an ACCESS MODE clause, and you can obtain 32-bit addressing (among other things) in Pascal with an XMEM directive. Verify that each actual HP COBOL parameter uses the same addressing mode as its corresponding formal Pascal parameter. In HP Pascal for NonStop systems (“HP Pascal”), if you declare a routine itself to be EXTENSIBLE, then in its routine header, you can explicitly declare each formal parameter to be optional (meaning that the calling program need not supply an actual parameter for it). If an HP COBOL program calls an extensible Pascal routine, the HP COBOL program must use the keyword OMITTED in place of each omitted optional parameter, except in the case of trailing omitted optional parameters. For example, if the Pascal routine header is MY_PROC ( R : INTEGER; OPTIONAL O1, O2 : INTEGER); an HP COBOL program can call the Pascal routine with any of these statements: ENTER ENTER ENTER ENTER PASCAL PASCAL PASCAL PASCAL "MY_PROC" "MY_PROC" "MY_PROC" "MY_PROC" USING USING USING USING A A B A B C A OMITTED C HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -31 Calling Other Programs and Routines Passing Parameters to Non-COBOL Routines Example 23-9. Passing Parameters to a Pascal routine HP COBOL code: DATA DIVISION. WORKING-STORAGE SECTION. 01 ONE-WORD USAGE NATIVE-2. 01 TWO-WORD USAGE NATIVE-4. 01 FOUR-WORD USAGE NATIVE-8. 01 A-STRING PICTURE X(25). ... PROCEDURE DIVISION. ... ENTER PASCAL "FUNCT1" USING ONE-WORD TWO-WORD FOUR-WORD A-STRING Pascal routine: FUNCT1 ( a: b: c: d: begin ... end; integer, longint, int64, fstring (25) ); TAL and pTAL Every TAL or pTAL procedure specifies, for each of its parameters, whether the parameter is to be passed by value or by reference and, for TAL, whether it is to be accessed using a 16-bit or 32-bit address. If a TAL or pTAL parameter is to be passed by value, an HP COBOL program can pass a numeric literal, a numeric data item, or the value of an arithmetic expression. The compiler generates code that evaluates, scales, and converts the value to the form that the called TAL or pTAL procedure expects. If a TAL or pTAL parameter is to be passed by reference, an HP COBOL program can pass an FD file name (to pass the address of the file control block) or a data item (to pass the address of the data item). An HP COBOL program that calls a TAL or pTAL procedure can omit any optional parameters, substituting the keyword OMITTED for each omitted optional parameter. In both the non-CRE environment and the CRE: • In HP COBOL, the default addressing mode is extended (32-bit). In TAL or pTAL, the addressing mode is explicitly declared for each reference parameter. Standard indirect addressing is indicated by type.identifier ; for example: INT .i; HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -32 Calling Other Programs and Routines Passing Parameters to Non-COBOL Routines Extended indirect addressing is indicated by type.EXT identifier ; for example: INT .EXT i; You can specify standard (16-bit) addressing in HP COBOL with an ACCESS MODE clause. Verify that each actual HP COBOL parameter uses the same addressing mode as its corresponding formal TAL or pTAL parameter. • In TAL or pTAL, if you declare a routine to be EXTENSIBLE or VARIABLE, its formal parameters are optional (meaning that the calling program need not supply the actual parameters). If an HP COBOL program calls an extensible or variable TAL or pTAL routine, the HP COBOL program must use the keyword OMITTED in place of each omitted optional parameter, except in the case of trailing omitted optional parameters. For example, if the TAL procedure declaration is: PROC my_proc (a, b, c) VARIABLE; INT .EXT a; INT .EXT b; INT .EXT c; BEGIN ... END; Then an HP COBOL program can call the TAL routine with any of these statements: ENTER ENTER ENTER ENTER • TAL TAL TAL TAL "MY_PROC" "MY_PROC" "MY_PROC" "MY_PROC" USING USING USING USING A A B A B C A OMITTED C TAL and pTAL have a parameter type called string:length that is defined: a^proc (a^string:length) string .ext a^string int length; An HP COBOL program that calls a TAL or pTAL routine that has a string :length parameter only passes one parameter, the string part. The compiler computes the length of the string and passes it to the TAL or pTAL routine. For example, suppose that your HP COBOL program calls the TAL or pTAL routine FILE_GETINFOBYNAME_, which has the parameter file-name :maxlen. To have your HP COBOL program pass the entire item, you can use this code: 01 A-FILENAME PIC X(20) ... ENTER "FILE_GETINFOBYNAME_" USING A-FILENAME ... To have your HP COBOL program pass part of the item, you can use either reference modification or an OCCURS clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -33 Calling Other Programs and Routines Passing Parameters to Non-COBOL Routines The code for reference modification is: 01 A-FILENAME PIC X(20) ... MOVE 0 TO A-COUNT INSPECT FUNCTION REVERSE (A-FILENAME) TALLYING A-COUNT FOR LEADING SPACES ENTER "FILE_GETINFOBYNAME_" USING A-FILENAME (1: FUNCTION LENGTH (A-FILENAME) - A-COUNT) ... The code for using an OCCURS clause is: 01 01 A-FILENAME. 02 PIC X OCCURS 1 TO 20 TIMES DEPENDING ON A-FILENAME-LENGTH. A-FILENAME-LENGTH PIC 99 COMP. Set A-FILENAME-LENGTH to the right length and call FILE_GETINFOBYNAME_ without using reference modification. For more information about TAL procedures, see the TAL Programmer’s Guide. For more information about pTAL procedures, see the pTAL Reference Manual. Example 23-10. Passing Parameters to a TAL Routine HP COBOL code: DATA DIVISION. WORKING-STORAGE SECTION. 01 ONE-WORD USAGE NATIVE-2. 01 TWO-WORD USAGE NATIVE-4. 01 FOUR-WORD USAGE NATIVE-8. 01 A-STRING PICTURE X(25). ... PROCEDURE DIVISION. ... ENTER TAL "proc1" USING ONE-WORD TWO-WORD FOUR-WORD A-STRING TAL routine: PROC proc1 (a, b, c, d); INT a; INT(32) b; FIXED(0) c; STRING .d; -- pointer to array BEGIN ... END; HP COBOL Manual for TNS and TNS/R Programs —522555-006 23 -34 24 Issues Related to Binding and Linking Note. Most of this section applies to the Guardian environment. If you are binding HP COBOL programs in the OSS environment, see Section 19, Using HP COBOL in the OSS Environment and Mixed-Language Programs. Topics: • • • • • • • Concepts and Terms Binding or Linking HP COBOL Programs Binding or Linking Mixed-Language Programs Accelerating TNS HP COBOL Programs Designing Programs With Large Amounts of Code Designing Programs With Large Amounts of Data COBOL Segmentation Concepts and Terms These the concepts and terms are relevant to binding and linking: • • • • • Memory Areas Code and Data Blocks Binding or Linking Loadfiles, Linkfiles, and Processes Fixup Code and Data Blocks The compiler accepts HP COBOL source code and produces code and data blocks. The code blocks can call each other. Topics: • • How the Compiler Produces Code and Data Blocks How One Code Block Calls Another HP COBOL Manual for TNS and TNS/R Programs —522555-006 24- 1 Issues Related to Binding and Linking Code and Data Blocks How the Compiler Produces Code and Data Blocks To understand how the compiler produces code and data blocks from HP COBOL source code, you must know about separately compiled programs and compilation units. A separately compiled program is an HP COBOL source program that is not nested within any other program. It can have other HP COBOL source programs nested within it. A compilation unit is a collection of source statements presented to a compiler in one compilation. It contains one or more separately compiled programs. For each compilation unit, the compiler produces a single object file. For each separately compiled program in the compilation unit, the object file contains one relocatable code block for the outermost source program, one relocatable code block for each program nested inside the outermost source program, and one or more data blocks. Each nest of programs produces an indivisible nest of code blocks. In the object file, the code and data blocks exist solely as named code blocks and data blocks; they do not have a collective identity. Figure 24-1. Code and Data Blocks Code Block A Separately compiled program A Separately compiled program B Compiler Code Block B Data Block Code Block C Data Block Code Block D Nested program C Nested program D Data Block Data Block Data Block VST702.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 24- 2 Issues Related to Binding and Linking Code and Data Blocks These compilers also produce one object file per compilation unit: • • • • • • • • TNS HP C TNS HP C++ FORTRAN Pascal TAL Native (TNS/R and TNS/E) HP C Native (TNS/R and TNS/E) HP C++ pTAL The object file contains one relocatable code block for each procedure and zero or more data blocks. How One Code Block Calls Another At the source program level, one program calls another with a CALL or ENTER statement; at the object program level, the calling program’s code block calls the called program’s code block. A CALL statement calls another COBOL program. Each CALL statement in a compilation unit makes either an internal reference (calling another program in the compilation unit) or an external reference (calling a program that is not part of the compilation unit). In Figure 24-2, the first CALL statement makes an internal reference, and the second CALL statement makes an external reference. An ENTER statement calls a non-COBOL program. Each ENTER statement makes an external reference. Figure 24-2. Internal and External References IDENTIFICATION DIVISION. PROGRAM-ID. X. ENVIRONMENT DIVISION. DATA DIVISION. PROCEDURE DIVISION. . . . CALL "Y". CALL "Z". IDENTIFICATION DIVISION. PROGRAM-ID. Y. ENVIRONMENT DIVISION. DATA DIVISION. PROCEDURE DIVISION. External Reference (to Z) Code X Compiler Data ≡ Data Internal Reference Code Y Data ≡ Data COBOL Object File COBOL Source File VST703.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 24- 3 Issues Related to Binding and Linking Binding or Linking When external references in two code blocks are resolved to entry points in each other, the two code blocks are called “crossbound.” The system code block and the system library blocks are all crossbound—a routine in any of these blocks can call a routine in any other of these blocks. The blocks of a multiblock user code space are all crossbound, as are the blocks of user library space. Binding or Linking Binding (the TNS term) or linking (the native term) is the operation of examining, collecting, and modifying code and data blocks from one or more object files to produce a single object file. Two important aspects of binding or linking a program are: • • Validating references to other programs or routines—determining whether the actual parameters of the calling program or routine correspond to the formal parameters of the called program or routine. Resolving references to other programs or routines—generating the code that will transfer control from the calling program or routine to the called program or routine at execution time. A typical compilation resolves some references and leaves others unresolved. (In Figure 24-2, the reference to program Y is resolved, and the reference to program Z is unresolved.) Topics: • • • • • • Binder BINSERV BIND Linker How the Compiler Validates and Resolves References Unresolved References Binder Note. This topic applies only to the COBOL85 compiler. The NMCOBOL compiler does not use Binder, it uses the Linker. The COBOL85 compiler validates and resolves internal and external references with the help of Binder, the HP object file building utility. Binder accepts commands that direct it to read, operate on, and produce object files. Binder has two forms, BINSERV and BIND. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24- 4 Issues Related to Binding and Linking Binding or Linking BINSERV BINSERV, which runs as a separate process during a compilation, performs these tasks: • • • • Builds lists of references that must be resolved Tries to locate the required code blocks and reports its success or failure to do so Gives the compiler information about the code blocks it finds. This information enables the compiler to verify that: ° The list of actual parameters that the calling program is passing to the called program is appropriate ° The language attribute of the code block matches the language specification in the CALL or ENTER statement Either creates an object file or reports its failure to do so BIND BIND, which is interactive, allows you to examine, modify, and combine object files. Suppose you have an object file containing blocks from several programs and you want to replace one version of program Q with another version. Using BIND, you can copy all blocks but those of program Q into a new object file and then copy the new set of blocks for the new version of Q into the new object file. For more information on Binder, see the Binder Manual. Linker Note. This topic applies only to the NMCOBOL compiler. The COBOL85 compiler does not use the linker, it uses Binder. The NMCOBOL compiler validates and resolves internal and external references with the help of the COBOLFE process and the linker. The linker accepts commands that direct it to read, operate on, and produce object files. The linker links one or more object files to produce either a loadfile or a linkfile. The linker that the NMCOBOL compiler uses depends on the CALL-SHARED, NONSHARED, and SHARED directives: Directive Linker Linker Documentation NON-SHARED nld utility nld Manual CALL-SHARED SHARED ld utility ld Manual HP COBOL Manual for TNS and TNS/R Programs —522555-006 24- 5 Issues Related to Binding and Linking Binding or Linking How the Compiler Validates and Resolves References The compiler translates each CALL statement and each ENTER statement in an HP COBOL source program into an external reference. When the compiler generates an implicit call to a routine that is to execute in another memory area, the parameters match those expected by the routine. When you explicitly call a routine that is to execute in another memory area (with an ENTER or X/Open CALL statement), the compiler must verify that the parameters in the ENTER or X/Open CALL statement match those expected by the external routine. To verify this, the compiler searches for the routine (and as Figure 24-3 illustrates): • • • • • • If the ENTER or X/Open CALL statement identifies the file that contains the routine with a mnemonic name, the compiler searches that file only. If the compiler does not find the routine in that file, it reports an error. If the compiler does not identify the file that contains the routine, it searches for the routine in the files on the primary search list if one exists. (One or more SEARCH directives build the primary search list; see Putting an Object File on the Primary Search List.) If the compiler does not find the routine in a file on the primary search list, it searches for the routine in the user library, if one exists; see Making an Object File the User Library. If the compiler does not find the routine in the user library, it searches for the routine in the files on the tertiary search list if one exists. (One or more CONSULT directives build the tertiary search list; see Putting an Object File on the Tertiary Search List.) If the compiler does not find the routine in a file on the tertiary search list, it searches for the routine in the file COBOLEXT (for a TNS program) or NMCOBEXT, ZCOBSRL, and ZCRESRL (for a native program). If the compiler does not find the routines in COBOLEXT or NMCOBEXT, it reports an error. If the compiler cannot validate the parameters of an ENTER statement in a program unit, it does not produce an object file for that program unit. When the compiler generates an implicit reference to one of its own run-time routines or to an operating system routine, the compiler leaves these references unresolved so that the code of the corresponding routines will execute in system code space. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24- 6 Issues Related to Binding and Linking Binding or Linking Figure 24-3. How External References Are Resolved Enter Mnemonic name? TRUE Search specified file FALSE Find routine? TRUE FALSE Issue error message Primary search list? TRUE Search files on primary search list in order FALSE TRUE Find routine? FALSE TRUE User library? TRUE Find routine? Search user library FALSE (always false for native programs) Tertiary search list? TRUE Search files on tertiary search list in order TRUE Find routine? FALSE FALSE Search COBOLEXT, NMCOBEXT, ZCOBSRL, or ZCRESRL FALSE Find routine? FALSE Issue error message TRUE Exit VST704.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 24- 7 Issues Related to Binding and Linking Loadfiles, Linkfiles, and Processes Unresolved References If an external reference in an object file refers to an entry point that is not among the code blocks in that object file, the external reference is called unresolved. Unresolved external references cause warning messages, but are allowed. They are expected to be resolved by the fixup operation of the system loader. If the compiler cannot resolve an external reference to a non-COBOL routine, it must at least be able to validate it. When the compiler processes a CALL statement that calls another COBOL program, but cannot find the other COBOL program, it delivers a warning message and produces an object file. When the compiler processes an ENTER statement that calls a routine, but cannot find the routine, it delivers an error message and does not produce object code for the calling program. The reason that the compiler cannot produce object code for the calling program is that the compiler is unable to verify that the parameters of the call match those expected by the routine (and, where necessary, to generate code that converts parameters in the HP COBOL program into the form required by the routine). For more information, see: • • How the Compiler Resolves Unqualified References How the Compiler Resolves Unqualified References. Loadfiles, Linkfiles, and Processes The single object file that results from binding or linking is a loadfileloadfile if exactly one program in it is a main program; otherwise, it is a linkfile A single execution of a loadfileloadfile is called a process. The operating environment creates a process by loading a loadfileloadfile into memory, creating entries for the process in various operating environment tables, and transferring control to the entry point of the main routine of the process. In memory, a process occupies code spaces, data spaces, and a process file segment. The code spaces and data spaces (memory areas) are described in Table 13-2. The process file segment is an extended data segment available only to the operating environment, which uses it for things such as managing the status of communication with files. Fixup The first time you instruct the operating environment to execute a loadfile as a process, the system loader performs a fixup operation on the file and attempts to resolve all unresolved external references. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24- 8 Issues Related to Binding and Linking Binding or Linking HP COBOL Programs External references call routines in: • • • • Other code blocks in the same user code space or user library space Code blocks in user library space The system code space Code blocks in system code extension To enable the system loader to fix up references to routines in user library space, you must provide the name of the user library file. The three ways to do this, in order of preference, are: 1. Designate the file in a LIBRARY directive in the compilation. 2. Designate the file in a LIB option in the RUN command. 3. Designate the file as the second file name in the first parameter (file-names ) of a call to the NEWPROCESS routine. If the system loader cannot resolve an external reference, it reports that there are still unresolved externals (?EXT: name ). The process executes until it attempts to call an unresolved external procedure, and then it calls the selected debugger (see Debugger Selection). The fixup operation is the reason that the first execution of a newly compiled program is less efficient than subsequent executions. After the system loader has performed the fixup, subsequent executions of the program do not need this operation until the contents of the loadfile are changed or the operating environment is changed. This run-time resolution helps to reduce object file size and compilation times. It also reduces the likelihood that you will have to recompile an HP COBOL program when a run-time routine that it calls is enhanced or corrected. Binding or Linking HP COBOL Programs A TNS HP COBOL program can be bound automatically, as part of compilation, or with BIND, after compilation. A native HP COBOL program can be linked automatically, as part of compilation: If you specify the RUNNABLE or SEARCH directive when creating a non-PIC loadfile, the NMCOBOL compiler also calls the nld utility. If you specify the RUNNABLE or SEARCH directives when creating a PIC loadfile (CALL-SHARED) or when creating a DLL library (SHARED), the NMCOBOL compiler also calls the ld utility. If you do not link the program automatically, you must use the nld or ld utility to link it after compilation. Topics: • • • Binding or Linking Automatically Binding or Linking Programs to Be Called Dynamically Binding With BIND HP COBOL Manual for TNS and TNS/R Programs —522555-006 24- 9 Issues Related to Binding and Linking Binding or Linking Automatically Binding or Linking Automatically By default, the COBOL85 compiler automatically binds the program, interacting with the BINSERV process as explained under Binder. If you specify the RUNNABLE directive but not the CALL-SHARED or SHARED directive, the NMCOBOL compiler automatically links the program, interacting with the COBOLFE process and the nld utility. If you specify the RUNNABLE directive and either the CALL-SHARED or SHARED directive, the NMCOBOL compiler automatically links the program, interacting with the ld utility. For simplicity, this explanation attributes actions of BINSERV, COBOLFE, and the nld utility to the compiler. Unless all the external routines that your program calls are in the file COBOLEXT (for TNS programs) or NMCOBEXT, ZCOBSRL, or ZCRESRL (for native programs), you must tell the compiler which object files contain the external routines that your program calls. There are several ways to tell the compiler about a specific object file: • • Establish a mnemonic name for the object file and use it in CALL or ENTER statements. Put the object file’s name on the primary search list. If the COBOL85 compiler finds an external routine in an object file on the primary search list, it validates the routine’s parameters and includes the routine in your program’s object file. If the NMCOBOL compiler finds an external routine in an object file on the primary search list, it validates the routine’s parameters and includes the entire object file in your program’s object file. • For a TNS program, make the object file the TNS user library (the only file on the secondary search list). For a native program, make the object file the user library. If the COBOL85 compiler finds an external routine in the user library, it validates the routine’s actual parameters but does not include the routine in your program’s object file. The system loader resolves the routine at fixup. You can only specify one user library, so if your program calls external routines from more than one object file (excluding COBOLEXT or NMCOBEXT), you must establish mnemonic names for the other object files or put each of them on a search list. • Put the object file’s name on the tertiary search list. If the compiler finds an external routine in an object file on the tertiary search list, it validates the routine’s actual parameters but does not include the routine in your program’s object file. The system loader resolves the routine at fixup. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -10 Issues Related to Binding and Linking Binding or Linking Automatically You can use a predefined DEFINE, =_OBJECT_SEARCH, to specify one or more subvolumes for the compiler to search for unqualified object files (see Specifying Subvolumes to Be Searched for Unqualified Files). Topics: • • • • Establishing a Mnemonic Name for an Object File Putting an Object File on the Primary Search List Making an Object File the User Library Putting an Object File on the Tertiary Search List Establishing a Mnemonic Name for an Object File If a CALL or ENTER statement contains a mnemonic name that specifies the object file that contains the called program, the compiler searches that file (and only that file) for the specified routine. If the compiler does not find the routine, it reports an error. You establish a mnemonic name for an object file with a File-Mnemonic clause in the SPECIAL-NAMES paragraph of the Environment Division. Suppose that the object file has the system file name MYLIB and you want to give it the mnemonic name HERLIB. The File-Mnemonic clause is: FILE "MYLIB" IS HERLIB. Note. MYLIB must be a PIC file if the object file being created will be a PIC file. Suppose that MYLIB contains a COBOL program named APROG. Your HP COBOL program can call APROG with the statement: CALL "APROG" OF HERLIB. Suppose that MYLIB is a TNS HP COBOL program and it contains a FORTRAN program named APROG. Your HP COBOL program can call APROG with the statement: ENTER FORTRAN "APROG" OF HERLIB. Quotation marks around the program name (APROG) are not required, but are recommended. If, in some eventual program maintenance, someone adds a variable named APROG to a program that already calls a program named APROG, and the name APROG is not in quotation marks, the compiler assumes that APROG refers to the variable. At run time, if the variable APROG does not contain the name of a valid program that is included in the object file, the program terminates with the error message “Called program not found.” If APROG is enclosed in quotes, the compiler recognizes it as a program name rather than a variable. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -11 Issues Related to Binding and Linking Binding or Linking Automatically Putting an Object File on the Primary Search List If a CALL or ENTER statement does not contain a mnemonic name that specifies the object file that contains the called program, the compiler searches for the called routine in the object files on the primary search list. If the COBOL85 compiler finds the routine, it validates the routine’s actual parameters and includes the routine in your object file. If the NMCOBOL compiler finds the routine, it validates the routine’s actual parameters and includes the entire object file (from the primary search list) in the object file that it is creating. You can put one or more object files on the primary search list with one or more SEARCH directives. The first SEARCH directive establishes the primary search list and adds files to it in the specified order. Subsequent SEARCH directives append files to the primary search list in the specified order. The compiler searches the object files of the primary search list in order. If the compiler finds the routine, it stops searching for it. Suppose that the object code for most of the external routines that your TNS HP COBOL program calls is in four different object libraries: CBLRTNS, an HP COBOL object file; CRTNS, an HP C object file; FTNRTNS, a FORTRAN object file; and PSCRTNS, a Pascal object file. Suppose that most of the external routines that your program calls are in CBLRTNS, almost equal numbers are in FTNRTNS and CRTNS, and very few are in PSCRTNS. For greatest efficiency, put CBLRTNS first on the primary search list, then FTNRTNS and CRTNS (in either order), and finally PSCRTNS. You can use the directive: ?SEARCH CBLRTNS,FTNRTNS,CRTNS,PSCRTNS Alternatively, you can use multiple SEARCH directives, which can appear anywhere in your HP COBOL program. This code produces the same primary search list as the preceding directive: ?SEARCH CBLRTNS ?SEARCH FTNRTNS,CRTNS ?SEARCH PSCRTNS If you put a SEARCH directive on the compilation command line when you compile your program, the compiler sees that SEARCH directive first, so the primary search list begins with that SEARCH directive’s object files. Making an Object File the User Library If the compiler does not find an external routine in any of the files on the primary search list, it searches for the routine in the user library. A loadfile can have only one user library. If the compiler finds the routine in the user library, it validates the routine’s actual parameters but does not include the routine in your object file. The system loader resolves the routine at fixup. If the compiler finds the routine in the user library, it stops searching for it. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -12 Issues Related to Binding and Linking Binding or Linking Automatically To make a TNS object file the user library, see LIBRARY. To make a native object file the user library, see Specifying a User Library. Putting an Object File on the Tertiary Search List If the compiler does not find an external routine in the user library, it searches for the routine in the object libraries on the tertiary search list. If the compiler finds the routine in a library on the tertiary search list, it validates the routine’s actual parameters but does not include the routine in your object file. The system loader resolves the routine at fixup. You can put one or more object libraries on the tertiary search list with one or more CONSULT directives. The first CONSULT directive establishes the tertiary search list, adding files to it in the specified order. Subsequent CONSULT directives append libraries to the tertiary search list in the specified order. The compiler searches the libraries of the tertiary search list in order. If the compiler finds the routine, it stops searching for it. Object libraries on the tertiary search list are not bound into the loadfile. Suppose that the files RTNS1985 and RTNS1988 contain object code for external routines that your HP COBOL program calls, and that most of the external routines that your program calls are in RTNS1988. For greatest efficiency, put RTNS1988 first on the tertiary search list. You can use the directive: ?CONSULT RTNS1988,RTNS1985 You could also use multiple CONSULT directives, which can be anywhere in your HP COBOL program. This code produces the same tertiary search list as the preceding directive: ?CONSULT RTNS1988 ?CONSULT RTNS1985 If you also put a CONSULT directive on the compilation command line when you compile your program, the compiler sees it first, so the tertiary search list begins with the object libraries in the CONSULT directive on the compilation command line. If the compiler does not find the routine in any object file on the tertiary search list, it searches for the routine in the file COBOLEXT (for TNS programs) or NMCOBEXT, ZCOBSRL, or ZCRESRL (for native programs). If BINSERV or the NMCOBOL compiler does not find the routine in COBOLEXT, NMCOBEXT, ZCOBSRL, or ZCRESRL, the compiler reports an error. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -13 Issues Related to Binding and Linking Binding or Linking Programs to Be Called Dynamically Binding or Linking Programs to Be Called Dynamically A dynamic call is one in which the name of the called program is not known until run time (see Dynamic Calls). Every program that a dynamic call could possibly call must be bound into the run unit or user library before you execute the program. There are several ways to do this: • • • • Compile all the programs in the run unit from a single source file. For a TNS program, use BIND to build the required program units into the run unit or user library (see the Binder Manual). For a native program, use the linker to build the required program units into the run unit. Refer to each possible called program explicitly in the source program—in a paragraph that is not executed—and then call the ones you want with CALL identifier statements. At run time, if identifier specifies the name of a program that is unavailable, the run-time routines raise an exception. Binding With BIND Note. This topic applies only to TNS programs. For native programs, see the nld Manual or the ld Manual. You can also bind a TNS HP COBOL program with BIND (the interactive form of Binder, the HP object file building utility). One of the most common reasons to use BIND is to replace one version of a program within an object file with a different version of that program. Topics: • • • Two Ways to Run BIND Replacing a Code Block With One From Another Language Replacing a Code Block With One With Different Parameters Two Ways to Run BIND Suppose you have an object file, BIGOBJ, made up of 15 separately compiled HP COBOL programs. You have recompiled one of them, PART7, into the object file OPART7. You want to create a new copy of BIGOBJ in which the old PART7 is replaced by the new PART7. You can run BIND interactively, giving BIND commands from a terminal (as in Example 24-1), or you can run BIND noninteractively, letting it read its commands from an OBEY command file (as in Example 24-2). The BIND prompt is @. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -14 Issues Related to Binding and Linking Binding With BIND Example 24-1. Interactive BIND Session :BIND Binder - OBJECT FILE Binder - T9621D20 - (8JUN92) @ADD * FROM BIGOBJ @REPLACE * FROM OPART7 @BUILD NUBIGOBJ @EXIT SYSTEM \AB Example 24-2. OBEY File Equivalent of Example 24-1 1 2 3 4 ADD * FROM BIGOBJ REPLACE * FROM OPART7 BUILD NUBIGOBJ EXIT In Example 24-2, the ADD command adds all the code and data blocks from BIGOBJ to the BIND lists, the REPLACE command replaces all the code and data blocks in the BIND lists that match blocks in OPART7, the BUILD command builds a new object file named NUBIGOBJ, and the EXIT command exits BIND. To direct BIND to use an OBEY command file, either start the BIND process with a RUN command that specifies the OBEY command file as the IN file, or use an OBEY command that specifies the OBEY command file to the executing BIND process. For more information about OBEY command files, see the Guardian User’s Guide. Replacing a Code Block With One From Another Language BIND allows you to replace one code block with another without regard for the language attribute of either. This is a potential source of problems, because not all languages have the same protocol for passing string parameters. HP COBOL uses the TAL protocol for passing string parameters; that is, HP COBOL passes only the character-string (by reference), not its length. FORTRAN uses its own FORTRAN protocol, passing a CHARACTER parameter and its length. If you use BIND to replace an HP COBOL code block (or any code block that uses TAL protocol) with a FORTRAN code block, any CHARACTER parameters will not have the associated lengths that the FORTRAN routine expects. The reverse case—replacing a FORTRAN code block with an HP COBOL code block (or any code block that uses TAL protocol)—is not a significant problem. The additional stack locations used for string-length values waste some stack space, but are ignored. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -15 Issues Related to Binding and Linking Binding or Linking Mixed-Language Programs Replacing a Code Block With One With Different Parameters Unless you have explicitly disabled parameter checking, BIND reports an error if you try to replace one code block with a code block that: • • Expects a different number of parameters Has has parameters that do not match those of the calling code block in size or mode (content or reference) For more information about the preceding topics and the many other features of BIND, see the Binder Manual. Binding or Linking Mixed-Language Programs If you intend to bind or link routines written in different languages into a single object file, you must either compile all the routines for the CRE or compile all the routines to use their own language-specific environments. The former strategy is highly recommended. Before binding a mixed-language program, see these documents: Program Type Document TNS Binder Manual Native non-PIC nld Manual Native PIC ld Manual Accelerating TNS HP COBOL Programs Note. This topic applies only to TNS programs. Native HP COBOL programs do not need to be (and cannot be) accelerated. Consider converting your TNS HP COBOL program to TNS/R native mode rather than accelerating it—see Section 33, Migrating TNS Programs to Native Programs. The Accelerator enables you to increase the execution speed of programs that run on TNS/R systems. The Accelerator optimizes TNS programs to take advantage of the TNS/R architecture. Most TNS object code that has been accelerated runs faster on TNS/R systems than TNS object code that has not been accelerated. Most programs written for TNS systems do not require changes to run on TNS/R systems, either with or without acceleration. The Accelerator takes a TNS loadfile as input and produces an accelerated object file as output. The accelerated object file contains both the original TNS code and the logically equivalent optimized RISC instructions—accelerated object code. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -16 Issues Related to Binding and Linking Designing Programs With Large Amounts of Code To accelerate an HP COBOL program, follow these steps: 1. Compile and bind the program. 2. Debug the program. 3. Run the Accelerator. If the Accelerator reports an error, the Accelerator does not produce an output file. Correct the error and run the Accelerator again. 4. If the program contains embedded SQL/MP or SQL/MX statements, run the SQL/MP or SQL/MX compiler. 5. Perform final testing on the accelerated program. See the Accelerator Manual for a complete description of accelerating programs for TNS/R systems. Topics covered include: • • • • • • Determining which programs to accelerate Preparing programs for the Accelerator Specifying Accelerator AXCEL command line syntax Setting Accelerator options Increasing the execution speed of accelerated programs Debugging accelerated programs Designing Programs With Large Amounts of Code Note. This topic applies only to TNS programs. The code space limit for a native HP COBOL program cannot be changed (it is 32 megabytes). A TNS run unit that includes HP COBOL code blocks consists of up to 16 code segments of up to 128 KB each. Each code segment contains one or more code blocks, a PEP table, and a block of space reserved for the XEP table, as Figure 24-4 illustrates. (Figure 24-4 is not drawn to scale; it shows components, not relative sizes.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -17 Issues Related to Binding and Linking Separate Programs Figure 24-4. Run Unit Containing HP COBOL Code Blocks Code Segment Code Segment Code Segment XEP Table XEP Table XEP Table Code Block Code Block ... Code Block Code Block Code Block Up to 64K words Code Block PEP Table PEP Table PEP Table Up to 16 VST705.vsd The maximum size of a code block depends on the language. The maximum size of an HP COBOL code block is 128 KB minus the number of bytes that the PEP and XEP tables occupy. If any HP COBOL code block in a segment exceeds 64 KB, the PEP table for that segment is automatically allocated 1024 bytes. If your program does not fit in one code block, do one or more of: • • • • Design the program as a family of Separate Programs Design the program as a family of Separate Processes Put eligible routines into a file, compile it, and declare it the TNS User Library Compile the program with the directive LESS-CODE 1 (see LESS-CODE Directive) It is easier to design a program as a family of separate programs or processes than it is to design a large, monolithic program only to find that it does not fit into one code block, and you must break it into separate programs or processes. Separate Programs If you can divide your programming task into a group of HP COBOL programs, one program can use the CALL statement to call others, and the programs can share resources. (For information about how programs share resources, see How Programs Share Resources.) You can compile the individual programs as separately compiled programs in a single compilation, or you can compile them in multiple compilations and then use BIND to bind them. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -18 Issues Related to Binding and Linking Separate Processes Separate Processes You can break a batch program into a requester and one or more servers. In a Pathway environment, servers can have their own servers. A Pathway server can create another process and communicate with it through a READ statement with a PROMPT phrase (an HP COBOL extension). For information about COBOL85 requester-server pairs, see Simple Server Example. TNS User Library If your program does not fit in user code space, you can put some of the routines in the TNS user library. The routines will then execute in an additional code space called user library space. User library space consists of one or more (a maximum of 16) separate user library code segments of 128 KB each. The system loader resolves references to routines in user library space at fixup. To enable the system loader to fix up references to routines in user library space, you must provide the name of the user library file (see Fixup). Topics: • • • Routines That Can Be Placed in the TNS User Library Best Candidates for the TNS User Library Putting Routines in the TNS User Library Routines That Can Be Placed in the TNS User Library The language in which a routine is written determines whether you can place it in the TNS user library (whether it can execute in user library space): Language in Which Routine is Written Routine Can Be Placed in the TNS User Library (Routine Executes in TNS User Library Space) HP COBOL Yes, if the ENV LIBRARY directive is specified HP C Yes, if the ENV LIBRARY pragma is specified FORTRAN Yes, but then it cannot have any COMMON, DATA, or SAVE statements Pascal No TAL Yes, if no global blocks are defined HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -19 Issues Related to Binding and Linking TNS User Library You can compile an HP COBOL routine with the ENV LIBRARY directive and put it into the user library if the program satisfies these criteria: • • • • • • • • It is not a main program. It is an initial program (its PROGRAM-ID paragraph specifies INITIAL). It is a separately compiled program (it is not embedded in another program). It does not contain any other programs. It does not specify the GLOBAL phrase on any level-01 record descriptions. It does not reference any external data items or external files. It does not have an Extended-Storage Section. It does not have a PROGRAM COLLATING SEQUENCE clause. If a routine does not meet the preceding criteria and you try to compile it with the ENV LIBRARY directive, the compiler issues a diagnostic message. If you compile a routine with the ENV LIBRARY directive: • • • ASSIGN and PARAM commands for the files in the routine are ignored. The compiler does not create data blocks or references to data blocks for the routine. Instead, the operating environment creates these at run time. The routine requires more time to start when called and might execute slightly more slowly. The routine, which executes in user library space, cannot call routines that execute in user code space. Best Candidates for the TNS User Library Of the routines that you can place in the TNS user library (see Routines That Can Be Placed in the TNS User Library), the best candidates are the routines that many programs share. Putting commonly used routines in the TNS user library packages them neatly and can reduce the storage space required for object code on disk and in main memory. Putting Routines in the TNS User Library To put routines in TNS user library space: 1. Put the source code for the routines in a file. 2. Compile the file of routines with the directive ENV LIBRARY. 3. Either make the resulting object file the user library (see Making an Object File the User Library), or use BIND to bind the resulting object file to the existing TNS user library (see the Binder Manual). HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -20 Issues Related to Binding and Linking Designing Programs With Large Amounts of Data Designing Programs With Large Amounts of Data For TNS programs, the address-space limitation is 128 KB. TNS HP COBOL reserves the upper 64 KB of the address space for its own use and reserves some of the lower 64 KB also. If the space reserved for your program data (user data space) is not enough, you can put some data in the Extended-Storage Section (user extended space). You can also reduce code size with the directive LESS-CODE 1, but at the expense of program execution time. The data space limit of approximately 60 KB sections of a TNS process does not apply to native HP COBOL programs. The Working-Storage Section and the ExtendedStorage Section are the same in native HP COBOL. There is a limit on what is called the “small data space,” but you can avoid that limit by using the directive LARGEDATA. Topics: • • Extended-Storage Section LESS-CODE Directive Extended-Storage Section Note. This topic applies only to TNS programs. Native HP COBOL does not need an Extended-Storage Section. The NMCOBOL compiler handles any data items that are described in the Extended-Storage Section as if they were described in the Working-Storage Section. For TNS programs, data declared in the Extended-Storage Section is stored in user extended space. The main HP COBOL program statically allocates a single segment of user extended space in which the Extended-Storage Sections of the component HP COBOL programs are consolidated. The size of user extended space is the sum of the sizes of the Extended-Storage Sections of the component programs, plus some space that the HP COBOL run-time environment allocates and manages. The maximum size of the segment that the main HP COBOL program allocates is 134,217,726 bytes. When declaring data in the Extended-Storage Section, be aware that: • • • Instructions that operate on items in the Extended-Storage Section take somewhat more execution time and storage space. An individual data item in the Extended-Storage Section (including a record) cannot exceed 134,217,726 bytes. A table in the Extended-Storage Section cannot exceed 134,217,726 bytes, because it must be contained within a record. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -21 Issues Related to Binding and Linking • • • • LESS-CODE Directive Records declared in the File Section are allocated in user data space, but you can move them to the Extended-Storage Section (user extended space) and back again with the MOVE statement, the INTO clause of the READ statement, or the FROM clause of the WRITE or REWRITE statement. In the HP COBOL environment, the CHECKPOINT statement cannot process data items declared in the Extended-Storage Section. The default access mode for data items in the Extended-Storage Section is EXTENDED-STORAGE (extended, or 32-bit, addressing). If these data items are passed as parameters, the corresponding formal parameters must also be 32-bitaddressed. If an HP COBOL program calls a routine (COBOL or non-COBOL) that uses the environment routines ALLOCATESEGMENT and USESEGMENT to alter user extended space, then any extended-storage context the HP COBOL program had is lost upon return from the called program. If you call USESEGMENT, you must save the value of the segment ID number of the segment previously in use (USESEGMENT returns this value) and restore that value before returning to the COBOL code. LESS-CODE Directive When a compiled program is larger than 128 KB, you can recompile it with the directive LESS-CODE 1 to reduce its object code. Because the directive LESS-CODE 1 also slows program execution speed, however, LESS-CODE 1 is recommended only for infrequently called programs. The LESS-CODE directive applies to every program that it precedes it and every program that contains it. If the LESS-CODE directive applies to a main program, the compiler does not generate code to initialize the Working-Storage Section or Extended-Storage Section. The object program executes faster, but the object file is significantly larger because it includes the data for the Working-Storage Section and Extended-Storage Section. If the LESS-CODE directive applies to a subprogram, the compiler generates code to initialize the Working-Storage Section, but not the Extended-Storage Section, when the program is initialized. (An initial program is initialized every time it is called; a noninitial program is initialized only if it is canceled with a CANCEL statement and then called with a CALL statement.) To initialize the Extended-Storage Section, the program calls the operating system routine RESETMEMORY. The program executes more slowly because calling RESETMEMORY (which requires input-output) takes longer than executing code to initialize the Extended-Storage Section. The object program is also larger. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -22 Issues Related to Binding and Linking COBOL Segmentation COBOL Segmentation Note. The 1985 COBOL Standard classifies the segmentation module as obsolete, so you are advised not to use it. HP COBOL ignores segment numbers, but issues warning messages for transfers of control forbidden by the segmentation rules of the ANSI COBOL Standard. HP COBOL also issues warning messages for altered GO TO statements in independent segments, because such alterations will not be restored when control returns to the independent segments. HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -23 Issues Related to Binding and Linking HP COBOL Manual for TNS and TNS/R Programs —522555-006 24 -24 COBOL Segmentation 25 Executing and Debugging HP COBOL Programs Note. This section applies to the Guardian environment. If you are compiling HP COBOL programs in the OSS environment, see Running HP COBOL Programs. After you have compiled and bound your program, you can execute and, if necessary, debug it. Topics: • • • Preparing to Execute an HP COBOL Program Executing an HP COBOL Program Getting a Program to Enter Debugging Mode Preparing to Execute an HP COBOL Program If your program has certain characteristics, or if you want certain things from a particular execution of your program, you must prepare appropriately before you execute your program. Table 25-1. Conditions Requiring Pre-Execution Preparation (page 1 of 2) Condition Preparation Required Before Program Execution Program assigns HP COBOL file names to DEFINE names. Add DEFINEs that have those DEFINE names (see Adding DEFINEs). Program assigns HP COBOL file names to system file names and you want to override those assignments. Override those assignments (see Overriding File Assignments Made at Compilation Time). Program creates some of the files it uses and you want to specify their characteristics. Specify their characteristics (see Specifying Characteristics of Files That a Program Creates). Program has a DEBUGGING MODE clause and debugging declaratives. Enable the debugging declaratives (see Enabling Debugging Declaratives). Program was compiled with a NONSTOP directive that you want to override. Override the NONSTOP directive (see Overriding the NONSTOP Directive). You do not want your home terminal to be the default inputoutput device. Specify the default input-output device that you want (see Specifying a Default Input-Output Device). HP COBOL Manual for TNS and TNS/R Programs —522555-006 25- 1 Executing and Debugging HP COBOL Programs Adding DEFINEs Table 25-1. Conditions Requiring Pre-Execution Preparation (page 2 of 2) Condition Preparation Required Before Program Execution You want the operating environment to return control to your program if a certain printer is unavailable or out of paper. Specify this preference (see Providing for an Unavailable Printer). Program declares external switches in the SPECIALNAMES paragraph and you want some of them to be ON when your program begins to execute. Turn on switches (see Turning On External Switches). You want the program to call a debugger, rather than ABEND, after printing any fatal error messages. Specify this preference (see Requesting a Debugger Instead of ABEND). You want the program to do all of its input-output in wait mode. Specify this preference (see Specifying Waited InputOutput). You want to establish one or more sets of preparation commands for your program and put a set into effect with a single command. Put each set of preparation commands into an OBEY command file and execute the appropriate OBEY command file (see Using OBEY Files to Prepare for Execution). You want to know what preparation commands are already active. Find out what these commands are (see Finding Out What Preparation Commands Are Already Active). You want to change or clear active preparation commands. Clear commands (see Changing or Clearing Unwanted Preparation Commands). Preparation commands stay active until you override them, clear them, or end your TACL session. Adding DEFINEs If your program assigns COBOL file names to DEFINE names, you must add DEFINEs that have those DEFINE names before executing your program. You add a DEFINE with the TACL command ADD DEFINE. Before you can add DEFINEs, you must set your TACL process DEFMODE attribute to ON (the default is OFF) with the TACL command: SET DEFMODE ON Topics: • • DEFINE Names DEFINE Attributes HP COBOL Manual for TNS and TNS/R Programs —522555-006 25- 2 Executing and Debugging HP COBOL Programs Overriding File Assignments Made at Compilation Time DEFINE Names A DEFINE name begins with an equal sign (=) followed by a letter and up to 22 additional characters, which can be letters, digits, hyphens (-), underscores (_), and circumflexes (^). Example 25-1. DEFINE Names =NEWFILE =FILE25 =TAPE-FILE =FTEST_RESULTS =JEFFS^FILE DEFINE Attributes Every DEFINE has a CLASS attribute, which determines its other attributes. For details, see the section of this manual that explains input-output for the system file that you want to associate with the DEFINE name: System file is a ... Section Number and Name Tape file Section 27, Tape Input and Output Disk file Section 28, Disk Input and Output Terminal Section 29, Terminal Input and Output Printer or spooler Section 30, Printer and Spooler Output Overriding File Assignments Made at Compilation Time To override a file assignment made at compile time—an assignment of a COBOL file name to a system file name—you use an ASSIGN command. Suppose that your program, PROG1, assigns the COBOL file name MAJORACCT to the system file name \AKRON.$SLB.MAJ.ACC with this SELECT clause: SELECT MAJORACCT ASSIGN TO "\AKRON.$SLB.MAJ.ACC" When you execute PROG1 and it opens MAJORACCT, the file it actually opens is \AKRON.$SLB.MAJ.ACC. Suppose that you want MAJORACCT to be another file, \NICE.$FRNC.SIGNIF.CUST, instead. You can override the original file assignment before executing PROG1 with the command: ASSIGN PROG1.MAJORACCT,\NICE.$FRNC.SIGNIF.CUST When you execute PROG1 and it opens MAJORACCT, the file it actually opens is \NICE.$FRNC.SIGNIF.CUST rather than \AKRON.$SLB.MAJ.ACC. HP COBOL Manual for TNS and TNS/R Programs —522555-006 25- 3 Executing and Debugging HP COBOL Programs Specifying Characteristics of Files That a Program Creates The number of ASSIGN commands the command interpreter can store is limited by the amount of memory allocated to the command interpreter. The default amount of memory allocated to the command interpreter is 8 pages, which accommodates up to 19 ASSIGN commands. To allocate more memory to the command interpreter, use the MEM option in the RUN command that you use to run the command interpreter. Each additional page of memory allocated to the command interpreter accommodates an additional 19 ASSIGN commands. Specifying Characteristics of Files That a Program Creates If your program is to create a file, you can specify these characteristics of that file with an ASSIGN command: • • • • The actual file name with which the COBOL file name is to be associated The size of the file (extent size) A file code An exclusion mode (EXCLUSIVE, SHARED, or PROTECTED) for reading and writing (but it does not override any exclusion mode that the program explicitly specifies) The ASSIGN command Example 25-2 specifies that the file that the program calls NEWFILE has the system file name \AKRON.$SLB.MAJ.NEWFILE, is allocated five file pages, is an EDIT file (type 101), and EXCLUSIVE exclusion mode (unless the OPEN statement that opens the file specifies a different exclusion mode). Example 25-2. ASSIGN Command ASSIGN PROG1.NEWFILE, \AKRON.$SLB.MAJ.NEWFILE, EXT 5, CODE 101, EXCLUSIVE You can also specify file characteristics with a DEFINE. For details on specifying file characteristics with either the ASSIGN command or DEFINEs, see ASSIGN Command and DEFINEs. Enabling Debugging Declaratives If your program has a DEBUGGING MODE clause and debugging declaratives, you must execute the command PARAM DEBUG ON before executing your program, or your program will not execute the procedures specified in its debugging declaratives. The PARAM DEBUG ON command is: PARAM DEBUG ON For an explanation of debugging declaratives, see Debugging Declaratives. HP COBOL Manual for TNS and TNS/R Programs —522555-006 25- 4 Executing and Debugging HP COBOL Programs Overriding the NONSTOP Directive Overriding the NONSTOP Directive If your program was compiled with a NONSTOP directive (which causes it to execute as a process pair), and you want to override the NONSTOP directive (until you have debugged the program, for example), you must execute the command PARAM NONSTOP OFF before executing your program. The PARAM NONSTOP OFF command is: PARAM NONSTOP OFF You can use a single PARAM command to do several things; for example, this PARAM command overrides the NONSTOP directive and enables USE DEBUGGING SECTIONS: PARAM NONSTOP OFF, DEBUG ON For another example of a PARAM command that does several things, see Specifying Waited Input-Output. Specifying a Default Input-Output Device First, verify that you want to specify a default input-output device. The alternative is to specify separate default input and output devices. The default input device (or the default input-output device) provides input to unqualified ACCEPT statements (those without FROM clauses). The default output device (or the default input-output device) displays run-time diagnostic messages and output from unqualified DISPLAY statements (those without UPON clauses). If a program has unqualified ACCEPT statements, the default input device (or the default input-output device) must be a disk file, terminal, or process. If a program has unqualified DISPLAY statements, the default output device (or the default input-output device) must be a disk file, terminal, process, or printer. If a program has both unqualified ACCEPT statements and unqualified DISPLAY statements, the default input-output device must be a terminal or process. If you want separate default input and output devices, do not specify a default inputoutput device. See Specifying Default Input and Output Devices. In the non-CRE environment, if you want a default input-output device other than your home terminal, specify it before executing your program with the command PARAM EXECUTION-LOG. The new default input-output device can be a system file name, a DEFINE name, or an asterisk (*). In the CRE, specify the default input-output device as explained in the CRE Programmer’s Guide. If default input-output device is a system file name, the file must exist before you execute the program. If the default input-output device is a DEFINE name, you must add it before you execute the program (see Adding DEFINEs). If default input-output device is an asterisk, all run-time messages are discarded. HP COBOL Manual for TNS and TNS/R Programs —522555-006 25- 5 Executing and Debugging HP COBOL Programs Providing for an Unavailable Printer This command specifies the default input-output device \AKRON.$SLB.MAJ.ERRMSG: PARAM EXECUTION-LOG \AKRON.$SLB.MAJ.ERRMSG This command specifies the DEFINE name =ERRORS as the default input-output device. You must add the DEFINE name =ERRORS before you execute the program. PARAM EXECUTION-LOG =ERRORS ADD DEFINE =ERRORS, FILE \AKRON.$SLB.MAJ.ERRMSG This command causes all run-time messages to be discarded: PARAM EXECUTION-LOG * Providing for an Unavailable Printer If you want the operating environment to return control to your program if a certain printer is unavailable or out of paper, you must execute a PARAM PRINTERCONTROL command before executing your program. This command specifies that control is to return to the program if the printer assigned to THE-PRINTER is unavailable or out of paper: PARAM PRINTER-CONTROL THE-PRINTER Turning On External Switches If your program declares external switches in the SPECIAL-NAMES paragraph and you want any of them to be in the ON position when your program begins to execute, you must turn them on with PARAM SWITCH-nn commands before executing your program. You can turn on several switches with a single PARAM SWITCH-nn command or use multiple PARAM SWITCH-nn commands. This command turns on SWITCH-1, SWITCH-4, and SWITCH-15: PARAM SWITCH-1 ON, SWITCH-4 ON, SWITCH-15 ON This series of commands is equivalent to the previous command: PARAM SWITCH-1 ON PARAM SWITCH-4 ON PARAM SWITCH-15 ON Requesting a Debugger Instead of ABEND If you want your program to call a debugger, rather than ABEND, after printing any fatal error messages, you must execute a PARAM INSPECT ON command before executing your program. The PARAM INSPECT ON command is: PARAM INSPECT ON HP COBOL Manual for TNS and TNS/R Programs —522555-006 25- 6 Executing and Debugging HP COBOL Programs Specifying Waited Input-Output Specifying Waited Input-Output To cause your HP COBOL program to do all its input-output in the wait mode, execute the command PARAM WAITED-IO ON before you execute the program. For more information, see PARAM Command. Using OBEY Files to Prepare for Execution If you expect to have to enter the same set of preparation commands repeatedly, you can save time by putting those commands in an OBEY command file. You can create an OBEY command file with an HP editor (see the example in Running the Compiler). Suppose that you almost always need to execute these preparation commands before executing your program, PROG1, so you put them into an OBEY command file named PREP1: ADD DEFINE =BIGCUST, FILE \AKRON.$SLB.MAJ.ACC ASSIGN PROG1.NEWFILE,& \AKRON.$SLB.MAJ.NEWFILE,& EXT 5, CODE 101, EXCLUSIVE PARAM NONSTOP OFF PARAM INSPECT ON PARAM EXECUTION-LOG \AKRON.$SLB.MAJ.ERRMSG PARAM PRINTER-CONTROL THE-PRINTER PARAM SWITCH-1 ON, SWITCH-2 ON Then you can execute all of the preceding commands with the single command: OBEY PREP1 Suppose that you occasionally want to execute PROG1 with the file \NICE.$FRNC.SIGNIF.CUST in place of the file \AKRON.$SLB.MAJ.ACC, have PROG1 create the file \NICE.$FRNC.SIGNIF.NEWFILE instead of the file \AKRON.$SLB.MAJ.NEWFILE, and send run-time library routine messages to the file \NICE.$FRNC.SIGNIF.ERRMSG instead of the file \AKRON.$SLB.MAJ.ERRMSG. You can put these commands in an OBEY command file named PREP1A: DELETE DEFINE =BIGCUST ADD DEFINE =BIGCUST, FILE \NICE.$FRNC.SIGNIF.CUST ASSIGN PROG1.NEWFILE,& \NICE.$FRNC.SIGNIF.NEWFILE,& EXT 5, CODE 101, EXCLUSIVE PARAM EXECUTION-LOG \NICE.$FRNC.SIGNIF.ERRMSG Then you can execute the commands in PREP1 (some of which you still want) and override them with the commands in PREP1A with this command series: OBEY PREP1 OBEY PREP1A HP COBOL Manual for TNS and TNS/R Programs —522555-006 25- 7 Executing and Debugging HP COBOL Programs Finding Out What Preparation Commands Are Already Active You can achieve the same result with one command, OBEY PREP2, by putting these commands in an OBEY command file named PREP2: ADD DEFINE =BIGCUST, FILE \NICE.$FRNC.SIGNIF.CUST ASSIGN PROG1.NEWFILE,& \NICE.$FRNC.SIGNIF.NEWFILE,& EXT 5, CODE 101, EXCLUSIVE PARAM NONSTOP OFF PARAM INSPECT ON PARAM EXECUTION-LOG \NICE.$FRNC.SIGNIF.ERRMSG PARAM PRINTER-CONTROL THE-PRINTER PARAM SWITCH-1 ON, SWITCH-2 ON An equivalent command sequence with the PARAM commands combined is: ADD DEFINE =BIGCUST, FILE \NICE.$FRNC.SIGNIF.CUST ASSIGN PROG1.NEWFILE,& \NICE.$FRNC.SIGNIF.NEWFILE,& EXT 5, CODE 101, EXCLUSIVE PARAM NONSTOP OFF, INSPECT ON, SWITCH-1 ON, SWITCH-2 ON,& EXECUTION-LOG \NICE.$FRNC.SIGNIF.ERRMSG,& PRINTER-CONTROL THE-PRINTER Note. The maximum number of DEFINES, ASSIGN commands, and PARAM commands that can be active at one time depends on the amount of memory allocated to the TACL command interpreter. For more information, see the TACL Reference Manual. Finding Out What Preparation Commands Are Already Active To find out if any DEFINEs are active, use this TACL command: INFO DEFINE =* To find out the characteristics of a DEFINE that you know is active, such as DEFINE FILE $BEA.LEACH.HYER, use either of these commands: SHOW DEFINE FILE SHOW DEFINE * To find out what ASSIGN commands are active, give the ASSIGN command with no parameters: ASSIGN To find out what PARAM commands are active, give the PARAM command with no parameters: PARAM HP COBOL Manual for TNS and TNS/R Programs —522555-006 25- 8 Executing and Debugging HP COBOL Programs Changing or Clearing Unwanted Preparation Commands Changing or Clearing Unwanted Preparation Commands To change or clear a DEFINE, you must use these TACL commands: TACL Command Function ALTER DEFINE Changes the attribute values of an active DEFINE DELETE DEFINE Clears (deletes) an active DEFINE For details on the preceding TACL commands, see the TACL Reference Manual. To change or clear an ASSIGN or PARAM command, you use the TACL command CLEAR. Some examples of the CLEAR command follow. Active Command TACL Command That Clears It ASSIGN PROG1.MAJORACCT,& \NICE.$FRNC.SIGNIF.CUST CLEAR ASSIGN PROG1.MAJORACCT PARAM NONSTOP OFF CLEAR PARAM NONSTOP One or more ASSIGN commands CLEAR ALL ASSIGN One or more PARAM commands CLEAR ALL PARAM One or more ASSIGN or PARAM commands CLEAR ALL Executing an HP COBOL Program You can start your program executing either from a TACL prompt (that is, from your TACL process) or from any other process. In either case, the operating environment creates a new process—your executing program—and that process is affected by any ASSIGN commands, PARAM commands, and DEFINEs that are active when the process is created (see Preparing to Execute an HP COBOL Program). Like every new process, your executing HP COBOL program receives a startup message from the operating environment. The startup message contains names for the IN file, the OUT file, the home terminal, and the default volume and subvolume. As an HP COBOL application programmer, you need not get involved with the startup message itself. If you need to manipulate the startup message, you can use Saved Message Utility (SMU) routines. Topics: • • • • • Starting an HP COBOL Program From a TACL Prompt Specifying Default Input and Output Devices Specifying the Home Terminal Specifying the debugger: see Debugger Selection Naming the New Process HP COBOL Manual for TNS and TNS/R Programs —522555-006 25- 9 Executing and Debugging HP COBOL Programs • • Starting an HP COBOL Program From a TACL Prompt Running the New Process in the Background Run-Time Errors Starting an HP COBOL Program From a TACL Prompt To start an HP COBOL program from the TACL prompt, use the TACL command RUN. In the simplest case, the program retrieves input for unqualified ACCEPT statements from your home terminal and displays run-time diagnostic messages and the output of unqualified DISPLAY statements on your home terminal. If the file ID of your loadfile is $SYSTEM3.COBOL85.PROG1, you can execute your program with this command: RUN $SYSTEM3.COBOL85.PROG1 You can omit the keyword RUN and the subvolume that your program is on if a default subvolume is specified on #PMSEARCHLIST. To specify $VOLUME.SUBVOL as a default on #PMSEARCHLIST, execute this TACL command before starting your program: #SET #PMSEARCHLIST #DEFAULTS $VOLUME.SUBVOL $SYSTEM.SYSTEM Then you can start the program whose file ID is $VOLUME.SUBVOL.PROG1 from the TACL prompt with this command: PROG1 The RUN command has many options, some of which allow you to specify these program attributes: • • • • • Default input and output devices Home terminal Debugger Process name (required if program is to run as a process pair) Ability to run in the background For more information about the RUN command and its options, see the TACL Reference Manual. To start an HP COBOL program from another HP COBOL program, see Initiating a Process From an HP COBOL Program. Specifying Default Input and Output Devices If you want your program to retrieve input for unqualified ACCEPT statements from a device other than your home terminal, you must specify that device. If you want your program to display run-time diagnostic messages and output from unqualified DISPLAY statements to a device other than your home terminal, you must specify that device. HP COBOL Manual for TNS and TNS/R Programs —522555-006 25 -10 Executing and Debugging HP COBOL Programs Specifying the Home Terminal If you want the default input device to be the same as the default output device, you can specify a default input-output device with a PARAM EXECUTION-LOG command before you execute your program (see Specifying a Default Input-Output Device) and ignore the remainder of this topic. If you want separate default input and output devices, you must specify them with the IN and OUT options of the RUN command and must not use a PARAM EXECUTIONLOG command (because the PARAM EXECUTION-LOG command takes precedence over the IN and OUT options of the RUN command). The default input and output devices can be system files (including disk files) or DEFINE names that you have already associated with system files. The default input file must be a terminal, disk file, or process; the default output file must be a terminal, disk file, line printer, or process. This command specifies the default input device INFILE and the default output device OUTFILE for the program PROG1. (Assume that PROG1, INFILE, and OUTFILE are on the default subvolume.) PROG1 /IN INFILE, OUT OUTFILE/ This command specifies the default input device INFILE for the program PROG1 but no default output device. The default output device will be the home terminal. PROG1 /IN INFILE/ This command specifies the default output device OUTFILE for the program PROG1 but no default input device. The default input device will be the home terminal. PROG1 /OUT OUTFILE/ Specifying the Home Terminal By default, the home terminal for your executing HP COBOL program is the same as the home terminal for your TACL process. This is a problem if all of these conditions are true: • • • The default input-output device, default input device, or default output device is the home terminal. The TACL process has control of the home terminal, causing HP COBOL run-time routines to wait for the terminal to become available. One of the waiting routines is a Pathway server. If the suspended Pathway server’s requester is also suspended, the performance of the Pathway application is degraded. If your program has the previously described problem, specify a different home terminal for your COBOL85 or NMCOBOL process with the TERM option of the RUN command. Verify that the new home terminal is available. HP COBOL Manual for TNS and TNS/R Programs —522555-006 25 -11 Executing and Debugging HP COBOL Programs Naming the New Process This command specifies the home terminal $TE1.#E02 for the program PROG1. Because the default input and output devices are not specified, they will be the home terminal, $TE1.#E02, unless an earlier PARAM EXECUTION-LOG command specified a default input-output device. PROG1 /TERM $TE1.#E02/ This command specifies the default input device INFILE for the program PROG1, no default output device, and the home terminal $TE1.#E02. The default output device will be the home terminal, $TE1.#E02. PROG1 /IN INFILE, TERM $TE1.#E02/ To find the name of a terminal, use the TACL command WHO. Example: 223> WHO Home terminal: $TE1.#E02 ... Naming the New Process If your HP COBOL program is to run as a process pair, it must have a process name. If your program is not to run as a process pair, a process name is optional but useful: it allows you to stop the process by name, which is easier than determining its processor and Process Identification Number (PIN) and then stopping it with those. You verify that your program has a process name in either of these two ways: • • Include the NAME Option in the RUN command. Compile the program with the RUNNAMED Directive. NAME Option The NAME option of the RUN command verifies that the program is run as a named process. You can specify the process name or not. If you do, it must begin with a dollar sign ($). (For the syntax of a process name, see the Guardian Programmer’s Guide.) If you do not specify the process name, the operating environment assigns a timestamp process name to the new process. This command assigns the process name “$PROG1” to the process created when you run $VOL1.SUB2.PROG1: RUN $VOL1.SUB2.PROG1 /NAME $PROG1/ This command causes the operating environment to assign a timestamp process name to the process created when you run $VOL1.SUB2.PROG1: RUN $VOL1.SUB2.PROG1 /NAME/ This command runs the program $VOL1.SUB2.PROG1 as an unnamed process (unless you specified RUNNAMED in the object file). RUN $VOL1.SUB2.PROG1 HP COBOL Manual for TNS and TNS/R Programs —522555-006 25 -12 Executing and Debugging HP COBOL Programs Running the New Process in the Background RUNNAMED Directive If you compile your program with the RUNNAMED directive, the operating environment assigns it a timestamp process name when you execute it. You do not need to include the NAME option in the RUN command (but you can, if you want to give it a specific name). The RUNNAMED directive works for the NMCOBOL compiler only if the RUNNABLE directive is active. Running the New Process in the Background By default, your TACL process suspends itself while your HP COBOL program executes. You can prevent this by running your program in the background with the NOWAIT option of the RUN command. Beware of using the NOWAIT option if your program has ACCEPT and DISPLAY statements that use the home terminal. With NOWAIT, your HP COBOL program cannot accept input from, or display output to, the home terminal until you pause the terminal. Without NOWAIT, you can access your TACL process by pressing Break when you are certain that the COBOL-created process is done with the home terminal. This command runs the program PROG1 in the background: PROG1 /NOWAIT/ Run-Time Errors Run-time errors are errors that arise during the execution of a process. Examples of their causes are: • • • The process tries to open a nonexistent file. The process tries to open a file that is inaccessible because another process has it open exclusively. The process tries to call a non-COBOL program that is not in the process’s own loadfile, the system library, or the TNS or user library. Topics: • • Diagnostic Messages Error-Handling Procedures HP COBOL Manual for TNS and TNS/R Programs —522555-006 25 -13 Executing and Debugging HP COBOL Programs Run-Time Errors Diagnostic Messages When a run-time error occurs, the run-time routine that detects it sends a run-time diagnostic message to the default output device. The run-time routine that detects the error is either a HP COBOL run-time routine (if the program is running in the non-CRE environment) or a CRE run-time routine (if the program is running in the CRE). The default output device is the home terminal unless you changed it with the PARAM EXECUTION-LOG command (see Specifying a Default Input-Output Device) or the OUT option of the RUN command (see Specifying Default Input and Output Devices). A run-time diagnostic message identifies the error, the process in which the error occurred, and the loadfile from which the process was loaded. The error number and format of a run-time diagnostic message depend on the run-time environment. For details, see Section 48, Run-Time Diagnostic Messages. One category of run-time diagnostic messages is not reported to the default output device: input-output exceptions with I-O status codes less than “30” that your program handles with its own error-handling procedures. Error-Handling Procedures In your HP COBOL program, you can define error-handling procedures with USE AFTER EXCEPTION statements. When a file system error occurs, control passes to a USE AFTER EXCEPTION statement, which can access two values to determine what action to take. The first value is the I-O status code, which identifies the error; the second value is that of the special register GUARDIAN-ERR, which identifies the cause of the error. One I-O error can have several possible causes; therefore, one I-O code status value can be associated with several GUARDIAN-ERR values. For example, a WRITE statement error (I-O code status value “24”) can be caused by a relative key that is out of bounds (GUARDIAN-ERR value 23), a full file (GUARDIAN-ERR value 45), or an invalid key (GUARDIAN-ERR value 46). The USE AFTER EXCEPTION statement can interpret the value of GUARDIAN-ERR and act accordingly. After a USE AFTER EXCEPTION statement executes, it returns control to the routine that called it, except when the I-O status code is “4x ” or “90,” in which case the process terminates abnormally. For more information about the USE AFTER EXCEPTION statement and diagnosing input-output errors, see USE AFTER EXCEPTION. HP COBOL Manual for TNS and TNS/R Programs —522555-006 25 -14 Executing and Debugging HP COBOL Programs Getting a Program to Enter Debugging Mode Getting a Program to Enter Debugging Mode You can get a program to enter debugging mode (that is, to enter the debugger for which you compiled the program) at any of these times: • • Before Execution During execution: ° ° Programmatically Forcefully For information on specific debuggers, see Section 15, Debugging Tools. Before Execution To have an ordinary HP COBOL program (as opposed to one that is a Pathway server) enter debugging mode before executing any instructions, start it with the RUND command instead of the RUN command. Use the same options that you would use with the RUN command (see Executing an HP COBOL Program). To have a Pathway server enter debugging mode before executing any instructions, use the PATHCOM command SET SERVER DEBUG ON. For considerations regarding errors that can occur when you are debugging a Pathway server, see the TS/MP Pathsend and Server Programming Manual. Programmatically To cause a program to put itself into debugging mode, put this statement at the point in the program where you want to start debugging: ENTER "DEBUG" The process prompts you for debugging commands at its home terminal. Forcefully To force an HP COBOL program to enter debugging mode while it is executing, use the TACL command DEBUG. If you do not have a TACL prompt on your terminal (because you are not running the HP COBOL program in the background), press Break to get a TACL prompt. If you include the TERM option in the RUN command with which you start your program, you can debug the program from a terminal other than the one the program is running on. HP COBOL Manual for TNS and TNS/R Programs —522555-006 25 -15 Executing and Debugging HP COBOL Programs Forcefully If the HP COBOL program is a Pathway server process, you can use the TACL DEBUG command only from a terminal that is connected to a command interpreter, not from a terminal that is configured to run a SCREEN COBOL terminal program. The reason is that you must be able to tell the debugger which process to debug. For considerations regarding errors that can occur when you are debugging a Pathway server, see the TS/MP Pathsend and Server Programming Manual. Note. If you press Break too soon after you start a process, you get the messages: WARNING - STARTUP MESSAGE NOT READ ABENDED: nn,nnn followed by a TACL prompt. The process that you started was not able to complete its initialization and was terminated. HP COBOL Manual for TNS and TNS/R Programs —522555-006 25 -16 26 Input and Output Concepts Input and output are involved in virtually every HP COBOL program. The typical batch HP COBOL program obtains data (input), manipulates it, and produces a report (output). The typical interactive HP COBOL program is a server that obtains a request, collects data (input), and sends a reply (output). Input and output always involve files. Input for an HP COBOL program comes from a disk file or nondisk file (such as a terminal); output from an HP COBOL program goes to a disk file or nondisk file (such as a terminal or printer). Process communication involves files—one process calls another by handling it as a file—and operating system messages. An HP COBOL process ignores operating environment messages unless you arrange to have it intercept them. Topics: • • • Files Processes Handled as Files Intercepting Operating System Messages Files Files of alphanumeric data are ASCII files; that is, they are encoded in American National Standard Code for Information Interchange (ASCII). Files are controlled by a file system, a combination of input-output hardware and operating system routines that mediate between the hardware and application programs. The NonStop operating system supports two file systems: the Guardian file system and the OSS file system. Both file systems recognize a file by its system file name; an HP COBOL program recognizes a file by its COBOL file name, a name that the program defines. For an HP COBOL program to access or manipulate an actual file, the file’s COBOL file name must be associated with a system file name. Under certain conditions, the HP COBOL run-time routines preread file records (starting the read for record n +1 when returning record n to the program), saving execution time by overlapping reading and processing. Topics: • • • • System File Names COBOL File Names Associating COBOL File Names With System File Names Prereading File Records For information about creating files, see the Guardian Programmer’s Guide. HP COBOL Manual for TNS and TNS/R Programs —522555-006 26- 1 Input and Output Concepts System File Names System File Names A system file name is the name by which the Guardian or OSS file system recognizes a system file. That name is unique, not only on the system where the file is physically located, but also within that system’s network. These rules and the remainder of this topic apply to all system file names in the Guardian file system. For information about system file names in the OSS file system, see Files in the OSS Environment. • • System file names are composed of alphanumeric characters and these special characters, which are used as delimiters: ° ° ° ° ° Backward slash (\) Dollar sign ($) Number sign (#) Colon (:) Period (.) System file names are not case-sensitive; \NODE1.$VOLUME1.SUBVOL1.FILE1 and \node1.$volume1.subvol1.file1 refer to the same file. Other rules depend on the category of the system file name. The categories are: • • • Permanent Disk File Names Temporary Disk File Names Nondisk File (Device) Names For information about process file names, see Processes Handled as Files. Permanent Disk File Names Permanent disk files are named when they are created. After being created, a permanent disk file remains on the disk until explicitly purged. ns node-name ns . file-id ns subvolume-name ns volume-name . ns . ns VST617.vsd node-name is a backward slash (\) followed by an alphabetic character and up to six alphanumeric characters. Example: \mynode. Default: default node. HP COBOL Manual for TNS and TNS/R Programs —522555-006 26- 2 Input and Output Concepts System File Names volume-name is a dollar sign ($) followed by an alphabetic character and up to six alphanumeric characters. Example: $volume3. Default: default volume. subvolume-name is an alphabetic character followed by up to seven alphanumeric characters. Example: subvol10. Default: default subvolume. file-id is an alphabetic character followed by up to seven alphanumeric characters. Example: file1234. An example of a permanent disk file name is \mynode.$volume3.subvol10.file1234. If \mynode.$volume3.subvol10 is the default subvolume, then these are equivalent: \mynode.$volume3.subvol10.file1234 $volume3.subvol10.file1234 subvol10.file1234 file1234 The default node, volume, and subvolume are established with the =_DEFAULTS DEFINE and can be changed with TACL commands. For details, see the TACL Reference Manual. Temporary Disk File Names The two ways to create a temporary disk file are: • • In the file-control entry, with the clause SELECT … ASSIGN #TEMP With the TACL command ASSIGN … #TEMP Temporary disk files are named by the file system when a program creates them. The program cannot specify a system file name for a temporary file. When the program closes a temporary disk file, the file system purges it. For more information about temporary disk files, see the Guardian Programmer’s Guide. Nondisk File (Device) Names Nondisk files are devices such as terminals, printers, magnetic tape drives, and data communications lines. A nondisk file can be accessed by its name (the recommended method) or its logical device number, both of which are assigned by system management. ldev-number node-name . device-name qualifier VST641.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 26- 3 Input and Output Concepts COBOL File Names node-name is a backward slash (\) followed by an alphabetic character and up to six alphanumeric characters. Example: \mynode. ldev-number is a dollar sign ($) followed by an integer whose value is less than or equal to 34492. Example: $12345. device-name is a dollar sign ($) followed by an alphabetic character and up to six alphanumeric characters. Example: $printr2. qualifier is a number sign (#) followed by one to seven alphanumeric characters. Example: #PRINTR2. An example of a nondisk file name is \mynode.$printer2.#S. If \mynode is the default node, then these are equivalent: \mynode.$printer2.#S $printer2.#S COBOL File Names A COBOL file name is the name by which a particular HP COBOL program recognizes a system file. It is unique within the HP COBOL program. A COBOL file name is the file-name in the file-control entry (in the Environment Division) and the file description entry (in the Data Division). A file-name must meet these criteria: • • • Consist of one or more (a maximum of 30) alphanumeric characters (letters, digits, and hyphens) Contain at least one nonnumeric character (letter or hyphen) Not begin or end with a hyphen Letters can be uppercase or lowercase. Note. HP COBOL requires a file-name to contain at least one nonnumeric character; COBOL requires a file-name to contain at least one letter. Example 26-1. COBOL File Names MAJRACCT MAJOR-ACCOUNT MajorAccount-3 HP COBOL Manual for TNS and TNS/R Programs —522555-006 26- 4 Input and Output Concepts Associating COBOL File Names With System File Names Associating COBOL File Names With System File Names The file-control entry for a file associates its COBOL file name with one of: • • • System File Name Special Name DEFINE Name If you want to associate the COBOL file name with a system file name at run time, see #DYNAMIC. System File Name The most straightforward way to associate a COBOL file name with a system file name is to use the file-control entry to assign a COBOL file name (the file-name in the SELECT clause) to a system file name (the system-file-name in the ASSIGN clause). These SELECT and ASSIGN clauses associate the COBOL file name MAJRACCT with the system file name \AKRON.$SLB.MAJ.ACC: SELECT MAJRACCT ASSIGN TO "\AKRON.$SLB.MAJ.ACC" When the HP COBOL program opens MAJRACCT, the file it actually opens is \AKRON.$SLB.MAJ.ACC. In the Guardian environment, you can override the file assignment that you made at compilation time before executing the program (see Overriding File Assignments Made at Compilation Time). You cannot do this in the OSS environment. For the syntax of a system file name in the Guardian environment, see the Guardian Programmer’s Guide. For the syntax of a system file name in the OSS environment, see Files in the OSS Environment. Special Name A special name is a place holder for a specific file whose system file name is determined at run time. Table 26-1. Special Names for System Files (page 1 of 2) Special System File Name Place holder for ... #IN In the Guardian file system, the file named in the IN parameter of startup message of current process In the OSS file system, the default input device (FD 0)— do not use it in SELECT clauses or the SPECIAL-NAMES paragraph as you can in the Guardian environment HP COBOL Manual for TNS and TNS/R Programs —522555-006 26- 5 Input and Output Concepts Associating COBOL File Names With System File Names Table 26-1. Special Names for System Files (page 2 of 2) Special System File Name Place holder for ... #OUT In the Guardian file system, the file named in the OUT parameter of startup message of current process In the OSS file system, the default output device (FD 1)— do not use it in SELECT clauses or the SPECIAL-NAMES paragraph as you can in the Guardian environment #TERM Home terminal of current process #TEMP Temporary disk file on default volume #DYNAMIC File name specified with the run-time library routine COBOLASSIGN (in the non-CRE environment) or COBOL_ASSIGN_ (in the CRE) during the execution of the current process In the Guardian environment, you can override the file assignment that you made at compilation time before executing the program (see Overriding File Assignments Made at Compilation Time). The new system-file-name in the overriding ASSIGN command can also be a special name—any special name except #DYNAMIC. #IN In the Guardian environment, #IN represents the file specified as the IN parameter in the startup message of the current process. If you started the current process from a TACL prompt, #IN refers to the file specified by the IN option of the RUN command (or its default). (See Specifying Default Input and Output Devices.) In the program PROG1, these SELECT and ASSIGN clauses associate the COBOL file name MAJRACCT with the special system file name #IN: SELECT MAJRACCT ASSIGN TO #IN Equivalently, these ASSIGN command associates the COBOL file name MAJRACCT with the special system file name #IN: ASSIGN PROG1.MAJRACCT, #IN If you run the program PROG1 with this command, the special name #IN represents the system file INFILE, so INFILE is associated with the COBOL file name MAJRACCT. PROG1 /IN INFILE/ In the OSS environment, #IN is the default input device (FD 0). You cannot use it in SELECT clauses or the SPECIAL-NAMES paragraph as you can in the Guardian environment. HP COBOL Manual for TNS and TNS/R Programs —522555-006 26- 6 Input and Output Concepts Associating COBOL File Names With System File Names #OUT In the Guardian environment, #OUT represents the file specified as the OUT parameter in the startup message of the current process. If you started the current process from a TACL prompt, #OUT refers to the file specified by the OUT option of the RUN command (or its default). (See Specifying Default Input and Output Devices.) In the program PROG1, these SELECT and ASSIGN clauses associate the COBOL file name REPORT with the special name #OUT: SELECT REPORT ASSIGN TO #OUT Equivalently, these ASSIGN command associates the COBOL file name REPORT with the special name #OUT: ASSIGN PROG1.REPORT, #OUT If you run the program PROG1 with this command, the special name #OUT represents the system file OUTFILE, so OUTFILE is associated with the COBOL file name REPORT. PROG1 /OUT OUTFILE/ In the OSS environment, #OUT is the default output device (FD 1). You cannot use it in SELECT clauses or the SPECIAL-NAMES paragraph as you can in the Guardian environment. #TERM The special name #TERM represents the home terminal of the current process. If you started the current process from a TACL prompt, #TERM refers to the file specified in the TERM option of the RUN command (or its default). (See Specifying the Home Terminal.) In the program PROG1, these SELECT and ASSIGN clauses associate the COBOL file name HOME-TERMINAL with the special name #TERM: SELECT HOME-TERMINAL ASSIGN TO #TERM Equivalently, these ASSIGN command associates the COBOL file name HOMETERMINAL with the special name #TERM: ASSIGN PROG1.HOME-TERMINAL, #TERM If you run the program PROG1 with this command, the system file $TE1.#E02 is associated with the special name #TERM and, therefore, with the COBOL file name HOME-TERMINAL. PROG1 /TERM $TE1.#E02/ HP COBOL Manual for TNS and TNS/R Programs —522555-006 26- 7 Input and Output Concepts Associating COBOL File Names With System File Names #TEMP The special name #TEMP represents a temporary disk file on the default volume (which is specified by the program’s startup message). When the program opens a file that is assigned to #TEMP, the HP COBOL run-time routines create a disk file on the default volume. When the program closes a temporary disk file, the file system purges it. For more information about temporary disk files, see the Guardian Programmer’s Guide. In the program PROG1, these SELECT and ASSIGN clauses associate the COBOL file name TEMPFILE with the special name #TEMP, which stands for the system file name that the file system gave the temporary file. SELECT TEMPFILE ASSIGN TO #TEMP Equivalently, this ASSIGN command associates the COBOL file name TEMPFILE with the special name #TEMP: ASSIGN PROG1.TEMPFILE, #TEMP #DYNAMIC The special name #DYNAMIC represents the file specified with the run-time library routine COBOLASSIGN (in the non-CRE environment) or COBOL_ASSIGN_ (in the CRE) during the execution of the current process. If you want your HP COBOL program to accept or construct a file name and then open the file with that name, you must: 1. Assign the COBOL file name to #DYNAMIC (in the file-control entry). 2. Associate #DYNAMIC with a system file name by calling the routine COBOLASSIGN (in the non-CRE environment) or COBOL_ASSIGN_ (in the CRE). 3. Open the file (using its COBOL file name). Suppose that you want your program to use a file that the user specifies at run time. Following Step 1, you assign the COBOL file name (ADJUSTABLE in this example) to the special name #DYNAMIC in the file-control entry: SELECT ADJUSTABLE ASSIGN TO #DYNAMIC. HP COBOL Manual for TNS and TNS/R Programs —522555-006 26- 8 Input and Output Concepts Associating COBOL File Names With System File Names To follow Step 2, you must declare Working-Storage data items to hold the name and the error value returned by the COBOLASSIGN or COBOL_ASSIGN_ routine, prompt the user for a file name, and then call the COBOLASSIGN or COBOL_ASSIGN_ routine: 01 ADJUSTABLE-STUFF. 03 ADJUSTABLE-NAME PICTURE X(34). 03 ADJUSTABLE-ERROR PICTURE S9(4). . . DISPLAY "What file shall I read?". ACCEPT ADJUSTABLE-NAME. ENTER "COBOLASSIGN" USING ADJUSTABLE ADJUSTABLE-NAME GIVING ADJUSTABLE-ERROR. IF ADJUSTABLE-ERROR = ZERO OPEN INPUT ADJUSTABLE ELSE PERFORM ADJUSTABLE-ERROR-ROUTINE ... To lock a file that has been opened with dynamic assignment, use the LOCKFILE statement. You cannot perform a CLOSE WITH LOCK operation on such a file. Note. Do not use #DYNAMIC in the TACL command ASSIGN. You will get an error when you try to assign a system file name to the associated COBOL file name with the COBOLASSIGN or COBOL_ASSIGN_ routine. For further information about the COBOLASSIGN and COBOL_ASSIGN_ routines, see COBOLASSIGN and COBOL_ASSIGN_. DEFINE Name Note. This topic applies only to the Guardian file system. DEFINEs do not accept OSS pathnames. If the file-control entry assigns the COBOL file name (the file-name in the SELECT clause) with a DEFINE name (the define-name-literal in the ASSIGN clause), then you must associate the DEFINE name with a system file name before executing the program (see Adding DEFINEs). Even when the program executes in the OSS environment, the DEFINE must specify a Guardian file name, tape device, or spooler. These SELECT and ASSIGN clauses associate the COBOL file name MAJRACCT with the DEFINE name =BIGCUST: SELECT MAJRACCT ASSIGN TO "=BIGCUST" This command associates =BIGCUST with the system file \AKRON.$SLB.MAJ.ACC: ADD DEFINE =BIGCUST, FILE \AKRON.$SLB.MAJ.ACC HP COBOL Manual for TNS and TNS/R Programs —522555-006 26- 9 Input and Output Concepts Prereading File Records Prereading File Records To save execution time by overlapping reading and processing, the HP COBOL runtime routines perform record prereading (starting the read for record n +1 when returning record n to the program) when all of these conditions are true: • • • • • File access mode is SEQUENTIAL. File open mode is INPUT. File exclusion mode is PROTECTED (for a disk file) or EXCLUSIVE (for a disk or nondisk file). The process is not running as a process pair. The file is not open for timed I-O. Verify that the prereading requirements are not met when the HP COBOL process does any of: • • • Enters a TAL routine to do input or output Executes the read operation as part of a TMF transaction (enters BEGINTRANSACTION, executes a READ statement, then enters ENDTRANSACTION) Executes a CLOSE NO REWIND statement on a tape file and subsequently executes an OPEN NO REWIND statement on the same file to continue from the previous position Processes Handled as Files One process calls another by handling it as a file. If the calling process is an HP COBOL program, it refers to the called process by a COBOL file name. Like COBOL file names of files that are not processes, the COBOL file name of a process must be associated with a file name that the operating environment recognizes (the process name or process descriptor). For more information about processes, see Section 31, Process Initiation, Communication, and Management. Intercepting Operating System Messages The operating system sends messages to processes, reporting such things as: • • • • Break was pressed on a terminal. A descendant process has terminated (normally or abnormally). Another process with which you are communicating has opened you or closed you. ASSIGN, PARAM, and startup messages were sent to you from your parent process (Guardian environment only). HP COBOL Manual for TNS and TNS/R Programs —522555-006 26 -10 Input and Output Concepts Intercepting Operating System Messages An HP COBOL process ignores operating system messages unless you arrange to have it intercept them. To have an HP COBOL process intercept operating system messages, you must include REPORT and MESSAGE SOURCE clauses in its RECEIVE-CONTROL paragraph. The MESSAGE SOURCE clause provides a mechanism through which a COBOL program can discover the sender of each message received. During the successful execution of a read operation on $RECEIVE, the $RECEIVE mechanism places a set of values into the storage space designated in the MESSAGE SOURCE clause. Figure 26-1. MESSAGE SOURCE Format Non-CRE Environment 01 SOURCE-MESSAGE. 05 SYSTEM-FLAG 05 ENTRY-NUMBER 05 05 FILLER PROCESS-ID. 10 PROCESS-NAME 10 CPU-PIN FILLER 05 PICTURE USAGE IS PICTURE USAGE IS PICTURE S9 COMPUTATIONAL. 999 COMPUTATIONAL. X(4). PICTURE PICTURE PICTURE X(6). X(2). X(16). PICTURE USAGE IS PICTURE USAGE IS PICTURE PICTURE PICTURE S9 COMPUTATIONAL. 999 COMPUTATIONAL. X(4). X(20). X(4). CRE 01 SOURCE-MESSAGE. 05 SYSTEM-FLAG 05 ENTRY-NUMBER 05 05 05 FILLER PHANDLE FILLER If the value of SYSTEM-FLAG is -1, the message came from the operating system. For more information about the MESSAGE SOURCE phrase, see MESSAGE SOURCE Phrase. For more information about the Receive-Control paragraph, see Section 31, Process Initiation, Communication, and Management. HP COBOL Manual for TNS and TNS/R Programs —522555-006 26 -11 Input and Output Concepts Intercepting Operating System Messages HP COBOL Manual for TNS and TNS/R Programs —522555-006 26 -12 27 Tape Input and Output HP COBOL batch programs must often read or write files that are on magnetic tape (tape files). Topics: • • • Reading and Writing Tape Files Adding DEFINEs for Tape Files Executing HP COBOL Programs That Use Tape Files If you need further information on reading and writing tape files, see the Guardian Programmer’s Guide. If you want to archive disk files on magnetic tape, use the operating environment’s BACKUP utility. To restore archived disk files from a tape back to a disk (which you must do before an HP COBOL program can read them), use the operating environment’s RESTORE utility. For information on the BACKUP and RESTORE utilities, see the Guardian User’s Guide. Reading and Writing Tape Files An HP COBOL program can read and write unlabeled tape files, labeled tape files, and tape files of types other than HP. Topics: • • • • • Preventing Prereading Saving Tape and Time Unlabeled Tape Files Labeled Tape Files Tape Files of Types Other Than HP By default, the shortest record an HP COBOL program can write to a tape file is 24 bytes. If you need shorter records, use the COBOL_SETMODE_ routine to set function 52 (see the Guardian User’s Guide). Preventing Prereading HP COBOL prereads tapes; that is, it initiates a new read operation after processing the last (or only) record in a block. Prereading can overlap I-O with program processing. If you do not want this to happen, verify that the records of a tape file will not be preread by opening the file for timed I-O (include a TIME LIMITS phrase in the OPEN statement or use the command PARAM WAITED-IO). For an explanation of prereading file records, see Prereading File Records. You cannot give a tape file the access mode I-O or the exclusion mode PROTECTED or SHARED. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27- 1 Tape Input and Output Saving Tape and Time Saving Tape and Time You can save both tape and time by blocking tape file records efficiently—that is, by specifying that each physical record is to contain more than one logical record (the default is one logical record per physical record). Because consecutive physical records are separated by an interrecord gap, longer physical records mean fewer interrecord gaps (less wasted tape). Because the tape drive must start and stop each time you read or write a physical record, having fewer interrecord gaps save time. Interrecord gap size depends on tape drive model, but the typical interrecord gap is about 0.6 inch (1.5 cm). If you are writing 1,600 bytes per inch—19,200 bytes, or characters, per foot (30 cm) of tape—then each interrecord gap occupies 960 bytes (1,600 bytes per inch*0.6 inch = 960 bytes). Suppose that each logical record is 80 bytes. If each physical record contains only one logical record (the default), you can write 18.5 physical records (18.5 logical records) per foot of tape (19,200 bytes/(80 bytes per physical record + 960 bytes per physical record) = 18.5 records). If, instead, you specify 10 logical records per physical record, giving each physical record 800 bytes, you can write 10.9 physical records (109 logical records) per foot of tape. If you specify 50 logical records per physical record, giving each physical record 4 KB, you can write 3.87 physical records (193.5 logical records) per foot of tape. You specify the number of logical records or characters per physical record (block) with a BLOCK CONTAINS clause in the file description entry of the file associated with the tape drive. The BLOCK CONTAINS clause works if these conditions are met: • • • • The file’s organization is sequential. The file has fixed-length records. When the block size is specified in characters, it is a multiple of the number of characters in the logical record size. Also, when a RECORD CONTAINS clause extends the record size, the block size expressed is a multiple of the number of characters in that specified record size. The file description entry does not have a LINAGE or ALTERNATE RECORD KEY clause. On NonStop systems, physical record (block) sizes for tapes range from 24 through 32,767 bytes. The recommended maximum tape block sizes for application programs are: Density (bytes per inch) Block Size (bytes) 800 4,096 1,600 8,192 6,250 32,767 HP COBOL Manual for TNS and TNS/R Programs —522555-006 27- 2 Tape Input and Output Unlabeled Tape Files For further information on the BLOCK CONTAINS clause, see BLOCK CONTAINS Clause. Unlabeled Tape Files An unlabeled tape file is a tape file that does not have standard ANSI or IBM labels. If a HP COBOL program creates a tape file, the tape file is unlabeled, and any other HP COBOL program can easily read or write it. If a system that is not an HP system creates a tape file, a HP COBOL program can still read it, but might encounter features that are not HP features. The first five steps for reading or writing an unlabeled tape file are the same: 1. In the file-control entry: a. Assign the COBOL file name of the tape to either: • • The device name of the tape drive that holds the tape that you want to read or write (established when the system was configured) A DEFINE name b. In the ORGANIZATION clause, declare SEQUENTIAL organization. c. In the ACCESS MODE clause, declare SEQUENTIAL access. 2. If you used dynamic file assignment in Step 1a, then in the Procedure Division, use the COBOLASSIGN or COBOL_ASSIGN_ routine to establish the system file name of the tape at run time (see #DYNAMIC) and go to Step 4. 3. If you used a DEFINE name inStep 1a, add the appropriate DEFINE before executing your program (see Adding DEFINEs for Tape Files) and go to Step 4. 4. Open the file with the appropriate file-specification in the OPEN statement. To prevent prereading of file records, include a TIME LIMITS phrase in the OPEN statement or use the command PARAM WAITED-IO. file-specification Effect INPUT Opens the tape for input so you can read it OUTPUT Opens the tape for output so you can write it, starting with its first record EXTEND Opens the tape for extension so you can write it, starting immediately after its last record (You cannot open a tape with the keyword I-O, which allows both input and output.) 5. If you opened the file for input, read it with the READ statement; if you opened it for output or extension, write it with the WRITE statement. After Step 5, the instructions depend on whether you are reading or writing one file on one tape, several files on one tape, or one file that spans several tapes. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27- 3 Tape Input and Output Unlabeled Tape Files Topics: • • • • How to read or write One File on One Tape How to read or write Several Files on One Tape How to read or write One File on Several Tapes Mount Messages One File on One Tape To read or write one file on one tape, follow Step 1 through Step 5 under Unlabeled Tape Files and then execute this step: Close the file with the CLOSE statement. Do not use a NO REWIND phrase. Use a LOCK phrase if the file was not dynamically assigned and you want to prevent the tape from being reopened (the run-time tape routine ignores LOCK for a dynamically assigned file). Example 27-1 assigns the COBOL file name TAPE1 to the system file name $DRIVE2 (a name that the system administrator assigned to a tape drive) and declares its organization and access modes to be sequential; then it opens TAPE1 for exclusive input, reads, closes, and locks it. Example 27-1. One File on One Tape ... ENVIRONMENT DIVISION. ... INPUT-OUTPUT SECTION. ... FILE-CONTROL SELECT TAPE1 ASSIGN $DRIVE2 ORGANIZATION SEQUENTIAL ACCESS MODE SEQUENTIAL. ... PROCEDURE DIVISION. ... OPEN INPUT TAPE1 EXCLUSIVE READ TAPE1 . . CLOSE TAPE1 LOCK ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 27- 4 Tape Input and Output Unlabeled Tape Files Several Files on One Tape To read or write more than one file on one tape, follow Step 1 through Step 5 under Unlabeled Tape Files and then execute these steps: 1. Close the file with the CLOSE statement, specifying NO REWIND. The NO REWIND phrase prevents the run-time routines from rewinding the tape, so that you can read or write the file that immediately follows the file you just closed. 2. Reopen the file specifying NO REWIND (see Step 4 under Unlabeled Tape Files). 3. Read or write the file again (see Step 5 under Unlabeled Tape Files). 4. Close the file with the CLOSE statement. Do not use a NO REWIND phrase. Use a LOCK phrase if the file was not dynamically assigned and you want to prevent the tape from being reopened (the run-time tape routine ignores LOCK for a dynamically assigned file). Example 27-2 writes two files on one tape and then closes and locks the tape. Example 27-2. Several Files on One Tape ... ENVIRONMENT DIVISION. ... INPUT-OUTPUT SECTION. ... FILE-CONTROL SELECT TAPE1 ASSIGN $DRIVE2 ORGANIZATION SEQUENTIAL ACCESS MODE SEQUENTIAL. ... PROCEDURE DIVISION. ... *WRITE FIRST OPEN OUTPUT WRITE TAPE1 CLOSE TAPE1 FILE TAPE1 EXCLUSIVE ... NO REWIND *WRITE SECOND FILE OPEN OUTPUT TAPE1 EXCLUSIVE NO REWIND WRITE TAPE1 ... CLOSE TAPE1 LOCK ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 27- 5 Tape Input and Output Unlabeled Tape Files One File on Several Tapes To read or write one file that spans several tapes, follow Step 1 through Step 5 under Unlabeled Tape Files and then execute these steps: 1. Close the file with the CLOSE statement, specifying REEL FOR REMOVAL (or UNIT FOR REMOVAL). The REMOVAL phrase rewinds the tape for removal so that you can remove it from the tape drive and replace it with the next tape. 2. Read or write the file again (see Step 5 under Unlabeled Tape Files). 3. Repeat Step 4 and Step 5 under Unlabeled Tape Files and Step 1 above for each tape that contains part of the file. 4. Close the file with the CLOSE statement. Do not use a NO REWIND phrase. Use a LOCK phrase if the file was not dynamically assigned and you want to prevent the tape from being reopened (the run-time tape routine ignores LOCK for a dynamically assigned file). Mount Messages When a run-time routine needs to have a reel of tape mounted, it sends a message to the process’ home terminal. Table 27-1. Mount Messages For an input file: Mount the next reel of fd-name = device-name in sequence For an output file: Mount the next reel of fd-name = device-name, with a write ring Message sent to the home terminal: Type return or $volume (or 'NO' to end input) Respond to the message sent to the home terminal after the next tape reel is mounted. If the next reel is ready on the device named in the mount message, press Return. If the next reel is ready on a different tape device, type that device name (beginning with $) before you press Return. If you do not want to continue with the next reel of tape, type “NO” in response to the message. If the program is reading the tape, the next READ statement will discover an end of file. For example, suppose that a file is stored on three tapes. Its COBOL file name is HUGEFILE. If HP COBOL end-of-tape sequences were used when the tapes were created, HP COBOL automatically asks for each reel; otherwise, you must read and then close each reel. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27- 6 Tape Input and Output Unlabeled Tape Files Example 27-3 assigns the COBOL file name HUGEFILE to the system file name $DRIVE2 (a name that the system administrator assigned to a tape drive) and declares its organization and access modes to be sequential. The first tape is on the tape drive $DRIVE2. The program opens HUGEFILE for exclusive input, reads it, and closes it, rewinding it for removal. You replace the first tape with the second tape, and the program reads it and closes it, rewinding it for removal. You replace the second tape with the third tape, and the program reads, closes and locks it, having now read the entire file. Example 27-3. Multitape File ... ENVIRONMENT DIVISION. ... INPUT-OUTPUT SECTION. ... FILE-CONTROL SELECT HUGEFILE ASSIGN $DRIVE2 ORGANIZATION SEQUENTIAL ACCESS MODE SEQUENTIAL. ... PROCEDURE DIVISION. ... OPEN INPUT HUGEFILE EXCLUSIVE. *READ FIRST TAPE READ HUGEFILE... CLOSE HUGEFILE REEL FOR REMOVAL. *READ SECOND TAPE READ HUGEFILE... CLOSE HUGEFILE REEL FOR REMOVAL. *READ THIRD TAPE READ HUGEFILE... CLOSE HUGEFILE LOCK. ... Avoid having an HP COBOL program read a multitape file that was created by a File Utility Program (FUP). HP COBOL and FUP mark the ends of nonfinal reels of a multiple-reel tape file differently: an HP COBOL program writes an end-of-file (EOF) mark, a trash record, and a pair of consecutive EOF marks; a FUP writes only a pair of consecutive EOF marks. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27- 7 Tape Input and Output Labeled Tape Files If your HP COBOL program must read a FUP-created multitape file, try this: 1. In the SELECT clause of the file-control entry, declare the file to be OPTIONAL. 2. Have the program close and reopen the file when it detects EOF. 3. Have the operator mount the next tape. When the program detects EOF immediately after an OPEN statement, the last reel has been read. 4. When all tapes have been read, have the operator respond NO to the tape mount message to signal the actual end of the file. Labeled Tape Files A labeled tape file is a tape file that has standard ANSI or IBM labels. If a tape file has labels of any other type, an HP COBOL program must bypass them, handling the tape file as unlabeled. Labeled-tape processing on NonStop systems involves these software elements: • • • • • • • ANSI or IBM standard tape labels (which catalog tape files) HP COBOL statements and clauses that describe labeled tape files and operate on them The TACL command DEFINE (which associates the COBOL file name of a labeled tape file with its system file name and defines its attributes) Tape processes (which control tape drives) $ZSVR, the operating environment server for tape processes For D-series software RVUs, the tape utility program TAPECOM, which monitors tape drives; for G-series software RVUs, the MEDIACOM utility is used instead File-system procedures and functions that support labeled-tape processing HP COBOL Manual for TNS and TNS/R Programs —522555-006 27- 8 Tape Input and Output Labeled Tape Files Figure 27-1. Software Involved in Labeled-Tape Processing Home Terminal Command Interpreter Process COBOL Mount Messages COBOL Process File System Tape Process Tape Process $ZSVR Server for Tape Processes Operator's Console ($0) Tape Operation Messages TAPECOM Process Operator Responses and Commands VST706.vsd To use a labeled tape file with an HP COBOL program, you must: 1. Describe the labeled tape file in a file-control entry in the HP COBOL program, assigning the file’s COBOL file name to a DEFINE name. 2. Enable the creation of DEFINEs with the TACL command SET DEFMODE ON. 3. Add a DEFINE that has the name assigned to the file in Step 1 and the appropriate attributes (see Adding DEFINEs for Tape Files). 4. Execute the program (see Executing HP COBOL Programs That Use Tape Files). Topics: • • • Describing Labeled Tape Files in a HP COBOL Program (Step 1) Consistency Checking of Labeled Tape Information Converting HP COBOL Programs to Use Labeled Tape Files HP COBOL Manual for TNS and TNS/R Programs —522555-006 27- 9 Tape Input and Output Labeled Tape Files Describing Labeled Tape Files in a HP COBOL Program In the file-control entry for a labeled tape file, assign the COBOL file name of the labeled tape file to a DEFINE name (for the syntax of a DEFINE name, see DEFINE Names). In the file description entry for a labeled tape file, include a RECORD CONTAINS clause to specify whether the file’s records are of fixed or variable length and to define their size. Example 27-4 assigns the COBOL file name SEQ-FILE to the DEFINE name =PROG1D1 (giving it sequential organization and access mode as required for a tape file) and then describes SEQ-FILE as having fixed-length records of 30 characters each. Example 27-4. Labeled Tape File ENVIRONMENT DIVISION. ... INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT SEQ-FILE ASSIGN TO "=PROG1D1" ORGANIZATION SEQUENTIAL ACCESS MODE SEQUENTIAL. ... DATA DIVISION. FILE SECTION. FD SEQ-FILE RECORD CONTAINS 30 CHARACTERS 01 SEQ-RECORD PIC X(30). ... Consistency Checking of Labeled Tape Information HP COBOL run-time routines check that the HP COBOL program specifications are consistent with these DEFINE attributes: • • • • • • LABELS RECFORM BLOCKLEN RECLEN FILESEQ USE If a program specification is inconsistent with an attribute, an HP COBOL run-time routine takes one of these actions, depending on the attribute: • • Allows the DEFINE attribute to override the program specifications Issues an open error because of inconsistency HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -10 Tape Input and Output Labeled Tape Files The system label-processing software checks that the DEFINE attributes are consistent with the tape label specifications; if they are not, the operating environment issues an open error. If the tape label and the data on the tape are inconsistent (for example, if the tape label specifies fixed-length records but the tape contains variable-length records), results are unpredictable. Converting HP COBOL Programs to Use Labeled Tape Files To convert an HP COBOL program to use a labeled tape file, set up an OBEY command file that: 1. Assigns the file-name in the file description entry to a DEFINE name 2. Enables the creation of DEFINEs 3. Deletes any existing DEFINE that has the name selected in Step 1 4. Creates the DEFINE 5. Runs the program 6. Clears the assignment (from Step 1) and the DEFINE (from Step 4) to prevent their affecting other processes created by the same TACL process In Example 27-5, the commands in the OBEY command file commands convert the HP COBOL program to use a labeled tape file. The file-name in the file description entry is MONTHLY-SALES, the DEFINE name is =SALES^JAN86, and the program name is QUOTAS. The DEFINE in Example 27-5 is for a tape file with ANSI standard labels and fixedlength records 80 characters long. Because the file description entry contains the clause LABEL RECORDS ARE OMITTED, the HP COBOL run-time library sets the file status code, STATUS-KEY, to “97.” If the program does not contain code that takes specific action when STATUS-KEY is “97.” the program can use a labeled tape file without changes to the source code or recompilation. Example 27-5. Converting a COBOL95 Program to Use Labeled Tape Files (page 1 of 2) HP COBOL file-control entry: SELECT MONTHLY-SALES ASSIGN TO $TAPE2 ORGANIZATION SEQUENTIAL ACCESS MODE SEQUENTIAL FILE STATUS IS STATUS-KEY. ... HP COBOL file description entry for a tape file: FD MONTHLY-SALES RECORD CONTAINS 80 CHARACTERS LABEL RECORDS ARE OMITTED. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -11 Tape Input and Output Tape Files of Types Other Than HP Example 27-5. Converting a COBOL95 Program to Use Labeled Tape Files (page 2 of 2) OBEY command file commands: ASSIGN MONTHLY-SALES, =SALES^JAN86 SET DEFMODE ON DELETE DEFINE =SALES^JAN86 ADD DEFINE =SALES^JAN86, CLASS TAPE, LABELS ANSI,& VOLUME SLS1Q86, RECFORM F, RECLEN 80,& BLOCKLEN 4000 RUN QUOTAS CLEAR ASSIGN MONTHLY-SALES DELETE DEFINE =SALES^JAN86 Tape Files of Types Other Than HP If a system that is not an HP system creates a tape file, a HP COBOL program can still read it, but might encounter features that are not HP features, such as: • • • • Labels Extended Binary Coded Decimal Interchange Code (EBCDIC) Packed-decimal or floating-point binary data Variable-length records Labels are explained in Labeled Tape Files. Topics: • • • EBCDIC Files Converting Other Data Types to HP COBOL Data Types Handling Variable-Length Records EBCDIC Files To read an EBCDIC file, an HP COBOL program must include a CODE-SET clause in the file description entry. The CODE-SET clause causes translation between the native USASCII character code convention and the EBCDIC code convention for all inputoutput operations. For more information about the CODE-SET clause—including restrictions—see CODE-SET Clause. If you cannot include a CODE-SET clause in the file description entry for an EBCDIC file, you must copy the EBCDIC file to an ASCII file with the File Utility Program (FUP) COPY command. The ASCII file can be a tape file or an existing disk file. To create a disk file, use the FUP CREATE command. The FUP command in Example 27-6 copies the EBCDIC tape file on tape drive $DRIVE1 to a tape file on tape drive $DRIVE2, converting it to ASCII in the process. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -12 Tape Input and Output Tape Files of Types Other Than HP Example 27-6. Copying an EBCDIC File to a New ASCII File FUP COPY $DRIVE1,$DRIVE2,EBCDICIN The FUP command in Example 27-7 copies the EBCDIC tape file on tape drive $DRIVE1 to the existing disk file $TEN.APP3.PQ5, converting it to ASCII in the process. Example 27-7. Copying an EBCDIC File to an Existing ASCII File FUP COPY $DRIVE1,$TEN.APP3.PQ5,EBCDICIN The FUP command in Example 27-8 creates the disk file $TEN.APP3.PQ5 from an EBCDIC tape file composed of 10K records of 80 characters each. Your HP COBOL program can access $TEN.APP3.PQ5 sequentially. Example 27-8. Copying an EBCDIC File to an Existing ASCII File FUP CREATE $TEN.APP3.PQ5, TYPE E, & EXT (1000 RECS,1000 RECS), REC 80 The preceding discussion does not completely explain FUP. There are many considerations involved in choosing parameters for the COPY and CREATE commands. For details, see the Guardian Programmer’s Guide. Caution. The EBCDIC-to-ASCII conversion mechanism described in this topic handles data of the type DISPLAY, but not data of the type COMPUTATIONAL. If an EBCDIC file does not have a character format, do not use FUP or CODE-SET to change EBCDIC to ASCII, because this disturbs the stored numeric values. Instead, convert directly from the foreign EBCDIC representation to a HP COBOL representation. (See Converting Other Data Types to HP COBOL Data Types.) Converting Other Data Types to HP COBOL Data Types If your HP COBOL program must use packed-decimal or floating-point binary data from a tape file that was not created on an HP system, be aware that the data from the tape file might be represented differently from HP COBOL packed-decimal and floatingpoint binary data. For details on HP COBOL packed-decimal and floating-point binary data representation, see USAGE Clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -13 Tape Input and Output Tape Files of Types Other Than HP HP COBOL data types: • BINARY or COMPUTATIONAL BINARY and COMPUTATIONAL are synonyms. HP COBOL stores a COMPUTATIONAL data item as a 2-byte, 4-byte, or 8-byte binary value, depending on the number of digits in its picture: • Picture Storage S9(01) - S9(04) 1 byte S9(05) - S9(09) 2 bytes S9(10) - S9(18) 4 bytes DISPLAY HP COBOL stores a DISPLAY data item as a sequence of ASCII characters, one for each digit. If the data description entry specifies that the sign is separate from the value, a separate byte is allocated for the sign, which is stored as an explicit plus (+) or a minus (-) character. If the data description entry does not specify that the sign is separate from the value, the sign is stored by setting the high-order bit of one byte of the data item— the high-order byte if the sign is specified as LEADING; the low-order byte otherwise. The value zero has neither a positive nor a negative sign. Some examples of data descriptions and their corresponding stored values are: Data Description Binary Value Stored PIC S99 VALUE 5 00110000 00110101 PIC S99 VALUE -5 00110000 10110101 PIC S99 VALUE 0 00000000 00000000 PIC S99 SIGN LEADING VALUE 5 00110000 00110101 PIC S99 SIGN LEADING VALUE -5 10110000 00110101 PIC S99 SIGN LEADING VALUE -0 00000000 00000000 PIC S99 SIGN TRAILING VALUE 5 00110000 00110101 PIC S99 SIGN TRAILING VALUE -5 00110000 10110101 PIC S99 SIGN TRAILING VALUE 0 00000000 00000000 HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -14 Tape Input and Output • Adding DEFINEs for Tape Files NATIVE-n HP COBOL stores a NATIVE-n data item as a signed, numeric, twos-complement, binary integer. A NATIVE-n data type is stored in n bytes: Data Type Storage NATIVE-2 2 bytes NATIVE-4 4 bytes NATIVE-8 8 bytes Handling Variable-Length Records Software for systems other than NonStop systems sometimes provides a mechanism for writing variable-length blocked records on tape—usually a block-length field at the beginning of each block and a record-length field at the beginning of each record. HP software does not have a similar mechanism. If your HP COBOL program must read a file tape that has variable-length blocked records and was not created on an HP system, you must write HP COBOL or TAL code to deblock the records. It might be easier to produce another tape with fixed-length records (blocked or not) on the system on which the file was created. Adding DEFINEs for Tape Files If your HP COBOL program assigns a tape file to a DEFINE name (which is optional for an unlabeled tape file, but required for a labeled tape file), then you must add that DEFINE name before executing your program, or the program will not be able to open the file. The values of the DEFINE attributes must match corresponding values in the tape label. The tape process compares corresponding values when the program tries to open the tape file, and if any corresponding values do not match, the tape process issues an error message, and the open operation fails (see Consistency Checking of Labeled Tape Information). These topics explain the attributes of DEFINEs for: • • Unlabeled Tape Files Labeled Tape Files In the Guardian environment, you must enable the creation of DEFINEs with the TACL command SET DEFMODE ON before you can add them. In the OSS environment, you can add DEFINEs with the command add_define. An HP COBOL program running in the OSS environment can assign a file to “GUARDIAN tape-device” or “GUARDIAN define-name.” In the latter case, you must use the add_define command to create a TAPE DEFINE before running the program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -15 Tape Input and Output Unlabeled Tape Files Unlabeled Tape Files The attributes of unlabeled tape files are: • • • • • • CLASS Attribute (Required) DEVICE Attribute (Required) BLOCKLEN Attribute (Conditional) LABELS Attribute (Optional) RECFORM Attribute (Optional) RETENTION or EXPIRATION Attribute (Optional) CLASS Attribute (Required) The value of the CLASS attribute must be TAPE. The CLASS attribute must be the first attribute in the ADD DEFINE command, because it determines what other attributes the DEFINE can have and clears any existing attribute settings, including any that precede it in the ADD DEFINE command. DEVICE Attribute (Required) The value of the DEVICE attribute must be the system file name of a tape drive. On a D-series system: Before the HP COBOL process can use the tape, the operator must use the Tape Utility Program (TAPECOM) command ACCEPT to approve opening the tape. Alternatively, the operator uses the TAPECOM command CLEAR NLCHECK to set the system so that processes can open unlabeled tapes without approval. Anyone using TAPECOM from a super-group user ID (255,nnn ) can act as an operator. BLOCKLEN Attribute (Conditional) The BLOCKLEN attribute is required if the tape file has fixed-length records; that is, if the RECORD CONTAINS clause in the file description entry is of the form RECORD CONTAINS length-fixed CHARACTERS the value of the BLOCKLEN attribute must be the same as: • • The block size that the tape label specifies The value of blk-2 in the BLOCK CONTAINS clause (if the tape file description entry has one) If the tape file has variable-length records, omit the BLOCKLEN attribute from the DEFINE. HP COBOL programs cannot process blocked variable-length records. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -16 Tape Input and Output Unlabeled Tape Files LABELS Attribute (Optional) The LABELS attribute must have the value OMITTED. With LABELS OMITTED, the system checks the mounted tape for standard ANSI or IBM labels; if the tape has them, the system rewinds and unloads the tape. The LABELS attribute of the DEFINE overrides any LABEL RECORDS clause in your HP COBOL program. Note. The 1985 COBOL Standard classifies the LABEL RECORDS clause as obsolete, so you are advised not to use it. Table 27-2. Effect of LABELS Attribute and LABEL RECORDS Clause on Unlabeled Tape File LABEL RECORDS Clause LABEL RECORDS STANDARD LABEL RECORDS OMITTED OMITTED HP COBOL sets file status code to 97* and execution proceeds Execution proceeds None (no LABELS attribute) Open error Execution proceeds LABELS Attribute Value * File status code 97 means that the statement executed successfully, but the circumstances were not entirely as expected. RECFORM Attribute (Optional) The value of the RECFORM attribute must correspond to the RECORD CONTAINS clause in the file description entry in the program. Table 27-3. Correspondence Between RECORD CONTAINS Clause and RECFORM Attribute Value Record Length RECORD CONTAINS Clause RECFORM Attribute Value Variable (undefined) RECORD CONTAINS min-length TO max-length CHARACTERS U Fixed RECORD CONTAINS length-fixed CHARACTERS F HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -17 Tape Input and Output Labeled Tape Files RETENTION or EXPIRATION Attribute (Optional) Use the RETENTION or EXPIRATION attribute when you want to save a file for any period of time, even part of a day; otherwise, the file expires as soon as you write it, and the system might overwrite the file. The value of the RETENTION or EXPIRATION attribute is an integer, the number of days before the file expires. Caution. On a multiple-file volume, the system might overwrite an unexpired file that follows an expired one; a volume on which the first file has expired is a scratch volume. Example 27-9 adds a DEFINE for an unlabeled tape file with variable-length records. The file is on the tape on the tape drive named $DRIVE. Example 27-9. DEFINE for Unlabeled Tape File With Variable-Length Records ADD DEFINE =ABC, CLASS TAPE, DEVICE $DRIVE Example 27-10 adds a DEFINE for an unlabeled tape file with fixed-length records. The file is on the tape on the tape drive named $DRIVE, and it will not expire for five days. Example 27-10. DEFINE for Unlabeled Tape File With Fixed-Length Records ADD DEFINE =DEF, CLASS TAPE, DEVICE $DRIVE,& BLOCKLEN 132, RETENTION 5 Labeled Tape Files The attributes of labeled tape files are: • • • • • • • • • • CLASS Attribute (Required) LABELS Attribute (Required) RECFORM Attribute (Conditional) BLOCKLEN Attribute (Conditional) RECLEN Attribute (Conditional) DEVICE Attribute (Conditional) FILESEQ Attribute (Conditional) USE Attribute (Optional) VOLUME Attribute (Optional) RETENTION or EXPIRATION Attribute (Optional) HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -18 Tape Input and Output Labeled Tape Files Figure 27-2. DEFINE Names and COBOL File Names COBOL Source Program . . . SELECT SALES1Q ASSIGN TO " =SALES-1Q86" . . . FD SALES1Q RECORD CONTAINS 60 CHARACTERS BLOCK CONTAINS 3900 CHARACTERS LABEL RECORDS ARE STANDARD . . . OPEN INPUT SALES1Q. . . . DEFINEs Enabled for the Process =SALES-1Q86 CLASS TAPE, LABELS ANSI, VOLUME SLS86, USE IN, RECFORM F, RECLEN 60, BLOCKLEN 3900 =ACCTS-RECEIVABLE ... System Software Automatic Volume Recognition ACCTPY SLS86 COBOL Process ACCTRC VST707.vsd CLASS Attribute (Required) The value of the CLASS attribute must be TAPE. The CLASS attribute must be the first attribute in the ADD DEFINE command, because it determines what other attributes the DEFINE can have and clears any existing attribute settings, including any that precede it in the ADD DEFINE command. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -19 Tape Input and Output Labeled Tape Files LABELS Attribute (Required) The value of the LABELS attribute for a labeled tape file must reflect the type of labels the tape has: Labels LABELS Attribute Value ANSI standard ANSI IBM standard IBM Any other BYPASS BYPASS tells the system to handle a labeled tape file like an unlabeled tape file. The labels are interpreted as data. Use BYPASS if either of these is true: • • The tape has labels that are not ANSI or IBM standard. The HP COBOL program does its own label processing. The LABELS attribute of the DEFINE overrides any LABEL RECORDS clause in your HP COBOL program. Table 27-4. Effect of LABELS Attribute and LABEL RECORDS Clause on Labeled Tape File LABELS Attribute Value LABEL RECORDS Clause LABEL RECORDS STANDARD LABEL RECORDS OMITTED ANSI or IBM Execution proceeds HP COBOL sets file status code to 97* and execution proceeds BYPASS HP COBOL sets file status code to 97*, execution proceeds, and HP COBOL handles any labels as data Execution proceeds and HP COBOL handles any labels as data * File status code 97 means that the statement executed successfully, but the circumstances were not entirely as expected. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -20 Tape Input and Output Labeled Tape Files RECFORM Attribute (Conditional) The RECFORM attribute is required unless you are bypassing labels (the value of the LABELS attribute is BYPASS). The value of the RECFORM attribute must reflect the type of records the tape has and must correspond to the RECORD CONTAINS clause in the file description entry in the program. Table 27-5. Correspondence Between RECORD CONTAINS Clause and RECFORM Attribute Value Record Length RECORD CONTAINS Clause RECFORM Attribute Value Variable (undefined) RECORD CONTAINS min-length TO max-length CHARACTERS U Fixed RECORD CONTAINS length-fixed CHARACTERS F BLOCKLEN Attribute (Conditional) The BLOCKLEN attribute is required if the tape file has variable-length records (the value of the RECFORM attribute is U) or if the tape file has fixed-length records (the value of the RECFORM attribute is F), and the file description entry does not have a BLOCK CONTAINS clause that specifies that the number of records per block is an integer greater than one. If the tape file has variable-length records, the value of the BLOCKLEN attribute depends on the file’s maximum record size and open mode. If the open mode is INPUT, the value of the BLOCKLEN attribute must be less than or equal to the maximum record size; if the open mode is OUTPUT or EXTEND, the value of the BLOCKLEN attribute must be greater than or equal to the maximum record size. If the file has fixed-length records, the value of the BLOCKLEN attribute must be the maximum record size, which is obtained from the BLOCK CONTAINS clause or from the record description entry for the largest record. RECLEN Attribute (Conditional) The RECLEN attribute is required if the file has fixed-length records. Its value must be the same as the value of the BLOCKLEN attribute (that is, the maximum record size). If the record has variable-length records, the RECLEN attribute is unnecessary; if you use it, its value is ignored. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -21 Tape Input and Output Labeled Tape Files DEVICE Attribute (Conditional) The DEVICE attribute is required if you are bypassing labels (the value of the LABELS attribute is BYPASS); otherwise, it is optional. When the DEVICE attribute is required, its value must be the system file name of a tape drive. On a D-series system: Before the HP COBOL process can use the tape, the operator must use the Tape Utility Program (TAPECOM) command ACCEPT to approve opening the tape. Alternatively, the operator uses the TAPECOM command CLEAR NLCHECK to set the system so that processes can open unlabeled tapes without approval. Anyone using TAPECOM from a super-group user ID (255,nnn ) can act as an operator. When the DEVICE attribute is optional, its value overrides the system’s automatic volume recognition. You cannot specify a different device in response to the system mount message. FILESEQ Attribute (Conditional) The FILESEQ attribute is required if the file you want to use is not first on the tape or if your HP COBOL program has a MULTIPLE FILE clause. If you omit FILESEQ and the COBOL program does have a MULTIPLE FILE clause, the open operation fails. Note. The 1985 COBOL standard classifies the MULTIPLE FILE clause as obsolete, so you are advised not to use it. The value of the FILESEQ attribute specifies the position of a labeled tape file on a multiple-file tape. It must be an integer in the range 1 through 9999 (relative file positions are consecutive integers from 1 through 9999) and must match the value in the corresponding field of the tape label. USE Attribute (Optional) The USE attribute prevents inadvertent overwriting of a tape file. The value of the USE attribute must correspond to the tape file’s open mode. Table 27-6. Corresponding Open Modes and USE Attribute Values Open Mode USE Attribute Value INPUT IN or OPENFLAG OUTPUT OUT or OPENFLAG EXTEND EXTEND or OPENFLAG The values IN, OUT, and EXTEND have the same meanings as the corresponding open modes; OPENFLAG means that the file can be opened in any mode that the OPEN statement specifies. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -22 Tape Input and Output Labeled Tape Files VOLUME Attribute (Optional) The VOLUME attribute identifies the tape. The value of the VOLUME attribute must be the name of the tape volume as it appears in the tape label. This automatic volume recognition enables you or the operator to mount the labeled tape on any available tape drive before or after you start your HP COBOL program. After locating the tape volume on a device, the operating environment passes the DEFINE to the tape process that controls the device. The tape process checks the values in the tape labels against the values of the DEFINE attributes. If the values do not match, the operating environment rejects the open request and issues an error message. If the values match, the operating environment approves the open request, and the HP COBOL process can use the tape file. RETENTION or EXPIRATION Attribute (Optional) Use the RETENTION or EXPIRATION attribute when you want to save a file for any period of time, even part of a day; otherwise, the file expires as soon as you write it, and the operating environment might overwrite the file. The value of the RETENTION or EXPIRATION attribute is an integer, the number of days before the file expires. Caution. On a multiple-file volume, the operating environment might overwrite an unexpired file that follows an expired one; a volume on which the first file has expired is a scratch volume. Example 27-11 adds a DEFINE for a labeled tape file with variable-length records whose labels are to be bypassed. The file is on the tape on the tape drive named $DRIVE. Example 27-11. DEFINE for Labeled Tape File With Variable-Length Records and Labels to Be Bypassed ADD DEFINE =ABC, CLASS TAPE, LABELS BYPASS,& BLOCKLEN 132, DEVICE $DRIVE Example 27-12 adds a DEFINE for a labeled tape file with standard IBM labels and variable-length records. The file is on the tape on the tape whose volume ID is 45329, and it will not expire for 100 days. Example 27-12. DEFINE for Labeled Tape File With Variable-Length Records and Standard IBM Labels ADD DEFINE =DEF, CLASS TAPE, LABELS IBM, RECFORM U,& BLOCKLEN 132, VOLUME 45329, RETENTION 100 Example 27-13 adds a DEFINE for a labeled tape file with standard ANSI labels and fixed-length records. The file is the second file on the tape, and it will not expire for 10 days. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -23 Tape Input and Output Executing HP COBOL Programs That Use Tape Files Example 27-13. DEFINE for Labeled Tape File With Fixed-Length Records and Standard ASCII Labels ADD DEFINE =DEF, CLASS TAPE, LABELS ANSI, RECFORM F,& BLOCKLEN 132, RECLEN 132, FILESEQ 2, EXPIRATION 10 Executing HP COBOL Programs That Use Tape Files During execution of an HP COBOL program that uses tape files, the operating environment software and the HP COBOL run-time library monitor: • • • Tape mounting Adherence to rules for using DEFINEs For labeled tapes, consistency of labeled-tape information in the HP COBOL program, DEFINE, and tape label You can mount tapes yourself or have an operator mount them. On a D-series system: To act as the operator, you must use the Tape Utility Program (TAPECOM) from a super-group user ID (255,nnn ). Topics: • • Mount Messages Run-Time Errors Mount Messages Mount messages for unlabeled tape files (and labeled tapes files being handled as such) are issued by an HP COBOL run-time routine; mount messages for labeled tape files are issued by the labeled-tape processing software. Table 27-7. Effect of LABELS Attribute on Mount Messages LABELS Attribute Value Software That Issues Mount Messages None (no LABELS attribute) HP COBOL run-time routine OMITTED HP COBOL run-time routine BYPASS HP COBOL run-time routine ANSI Labeled-tape processing software IBM Labeled-tape processing software HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -24 Tape Input and Output Mount Messages Topics: • • Unlabeled Tapes Labeled Tapes Unlabeled Tapes Without labels, the operating environment cannot use automatic volume recognition to locate the tape, so the mount message from the HP COBOL run-time routine specifies the tape drive on which to mount the tape—the tape drive specified by the DEVICE attribute of the file’s DEFINE. If the mount message appears on a terminal display, you can specify a different tape drive on which to mount the tape. Respond to the mount message by typing the device name of the new tape drive after the colon: TYPE RETURN OR $DEVICE (OR 'NO' TO END INPUT): $TAPE HP COBOL opens the tape drive you specify. If a DEFINE exists for the tape file and you specify a different device in response to an HP COBOL mount message, the HP COBOL run-time library alters the DEVICE attribute of the file’s DEFINE. If no DEFINE exists for the tape file, the HP COBOL run-time library creates a DEFINE with the required attributes (including the DEVICE attribute). The new DEVICE attribute value or the new DEFINE remains active until one of these occurs: • • • The HP COBOL process terminates. The HP COBOL process uses a DEFINE procedure to change the value of the DEVICE attribute or to delete the DEFINE. The HP COBOL run-time library changes the value of the DEVICE attribute when you specify a different device for the file in response to another HP COBOL mount message. Labeled Tapes A mount message from the labeled-tape processing software usually does not specify a device on which to mount the tape. The labeled-tape processing software uses automatic volume recognition to find a tape volume on one of the system’s tape drives, so you or the operator can mount the tape on any available tape drive. For a continuation reel of a multitape file, however, a mount message from the labeled-tape processing software specifies the same device as the first reel. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -25 Tape Input and Output Run-Time Errors Run-Time Errors Table 27-8. Run-Time Errors Specific to Tape File Use Message Number Non-CRE CRE Text of Message (in Non-CRE Environment) 045 170 MULTIPLE FILE TAPE file not on tape 046 171 OPEN positioning for MULTIPLE FILE TAPE failed 093 214 OPEN I-O for file not on input-output device 094 215 Wrong or missing LABELS attribute 095 216 Wrong or missing USE attribute 096 217 Wrong or missing RECFORM attribute 097 218 Wrong or missing RECLEN attribute 098 219 Wrong or missing BLOCKLEN attribute 099 220 Wrong or missing FILESEQ attribute 100 221 Wrong or missing DEVICE attribute 101 222 A DEFINE procedure failed with error nnn 102 223 DEFINE required for LABEL RECORDS STANDARD Input-output errors that are not specific to tape files can also occur. For a complete list of HP COBOL run-time errors and suggestions for recovering from them, see Section 48, Run-Time Diagnostic Messages. HP COBOL Manual for TNS and TNS/R Programs —522555-006 27 -26 28 Disk Input and Output Both batch programs and transaction-supporting servers use disk files. Topics: • • • • • • • • • • • Common Disk File Topics Types of HP Disk Files Creating and Using HP COBOL Sequential Files Creating and Using HP COBOL Relative Files Creating and Using HP COBOL Indexed Files Creating and Using Queue Files Establishing Starting Points in Files Optimizing Disk File Processing Optimizing Disk File Storage Avoiding Deadlock Using Enscribe and Operating System Routines Common Disk File Topics These topics apply to all disk files: • • • • • • • • • • • • • Allocation Partitioned Files Purging Files or Their Data Locking Ownership and Security Fixed-Length and Variable-Length Records Exclusion Modes Time Limits Reading Files From Called Programs Sharing Files Among HP COBOL Programs Sharing Files Among Different-Language Modules Modification Maximum Number of Files HP COBOL Manual for TNS and TNS/R Programs —522555-006 28- 1 Disk Input and Output Allocation Allocation The file system allocates physical storage for a disk file in the form of file extents. A file extent is a contiguous block of storage, starting on a disk sector boundary and containing a multiple of 2,048 bytes (up to 134,215,680 bytes). The file system permits a disk file to have up to 978 extents—one primary extent and up to 977 secondary extents. The primary extent can be a size different from that of the secondary extents. The file system allocates extents only when needed. The file extents that constitute a file are not necessarily contiguous. When all extents are allocated, writing to the file causes I-O file status code “34.” HP COBOL has no mechanism for specifying extents. If an HP COBOL program creates a disk file, it allocates a primary extent of 4 x 2,048 bytes and a secondary extent of 20 x 2,048 bytes. An HP COBOL program can call the routine COBOL_CONTROL_ to allocate and deallocate extents. If you create a disk file outside of HP COBOL and do not specify extents, the file system allocates a primary extent of 2,048 bytes. If you do not explicitly specify a secondary extent, the file system allocates secondary extents, as needed, that are the same size as the primary extent. Partitioned Files An Enscribe disk file can be composed of up to 16 partitions. Every partition consists of a primary extent plus up to 977 secondary extents. Each partition must reside on a different volume. If your system is connected to a network, either through Expand or through the fiber optic extension (FOX) of the interprocessor bus, the partitions can even reside on different systems (at a performance penalty). For information about Expand, see the Expand Network Management and Troubleshooting Guide. An HP COBOL program can read or write a partitioned file but cannot create one. You must use FUP to create a partitioned file; for details, see the Guardian Programmer’s Guide. Partitioned files have these significant advantages: • • • They can be up to 16 times as large as nonpartitioned files. They can be accessed faster because separate read heads are used. The loss of access to a disk need not mean the loss of access to the entire file. Purging Files or Their Data You can purge a file from the disk from your TACL session with the TACL command PURGE. An HP COBOL program can purge a file from the disk by calling the operating system routine PURGE. Purging a file from the disk merely removes the disk file from the directory and frees the disk space for use by other files; it does not erase the data on the disk. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28- 2 Disk Input and Output Locking You can erase the contents of a file without purging the file with the FUP command PURGEDATA. An HP COBOL program erases the contents of a file without purging the file simply by opening the file for output. An HP COBOL program can erase the contents of a file by calling routine COBOL_CONTROL_. The data remains on the disk—only the current-record, next-record, and EOF pointers are reset, and the EOF pointer in the file label on the disk are changed to indicate that the file is logically empty. To erase the data on the disk, you must: 1. Use either the FUP SECURE command with its CLEARONPURGE option or call the routine COBOL_SETMODE_ to set function 52 (see the Guardian User’s Guide). 2. After setting the CLEARONPURGE flag, call the PURGE routine (directly or through FUP). The CLEARONPURGE flag has no effect on the outcome of a PURGEDATA operation performed through FUP or through the CONTROL routine. Locking An HP COBOL program can lock and unlock an entire file with the LOCKFILE and UNLOCKFILE statements. Batch programs lock entire files more often than transaction processing programs do. An HP COBOL program can lock individual records in a file with the LOCK phrase of the READ statement and unlock them with either the UNLOCKRECORD statement or the REWRITE statement with UNLOCK. You must lock files when one process needs exclusive access to a record, a set of records, or an entire file for some logical operation to complete successfully (as in the case of TMF). For more information, see Avoiding Deadlock). Ownership and Security Each disk file on the HP system has an owner and a file security. Initially, the owner is the user who creates the file and the security is the default file security. The owner can transfer ownership to another user with the FUP GIVE command. The owner of a file can change the file’s security with the FUP SECURE command. The security system recognizes a file owner by the user ID, which consists of a group number and a user number. The operating environment obtains the group number and user number from the group name and user name when the user logs on; for example, if you log on as PROJECT3.SANDY, your group name is PROJECT3 and your user name is SANDY, and the operating environment translates these names to their corresponding group number and user number. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28- 3 Disk Input and Output Ownership and Security Topics: • • • Security Attributes Default File Security Accessing Files on Other Nodes Security Attributes Security attributes of a disk file allow the owner to control access to the file. If you own a file, you can change its security at any time with the FUP SECURE command: FUP SECURE file-name,"RWEP" Security Attribute Meaning R Reading W Writing E Executing P Purging The value of each security attribute determines the class of user who has permission to perform the corresponding operation on the file (see Table 28-1). Table 28-1. Security Attributes for Disk Files1 Who Can Perform the Corresponding Operation on the File On Local System Only From Anywhere on Expand Network2 Owner only O U Any member of owner’s user group G C Any user A N Local super ID only - Not applicable 1. Uppercase letters are shown, but the corresponding lowercase letters are equivalent. 2. If your HP system is part of an Expand network. To display a file’s current security attributes, use the FUP INFO command. To alter a file’s security from an HP COBOL program, call the routine COBOL_SETMODE_. Suppose that your HP system is part of an Expand network and you own the disk file FILE3. The command in Table 28-1 prevents everyone but you from reading, writing, executing, or purging FILE3, but you can only read, write, execute, or purge the file on your local system. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28- 4 Disk Input and Output Ownership and Security Example 28-1. File Accessible Only to Owner and Only Locally FUP SECURE FILE3,"OOOO" The command in Table 28-2 is the same as the command in Table 28-1, except that you can read, write, execute, or purge FILE3 from anywhere on the Expand network. Example 28-2. File Accessible Only to Owner FUP SECURE FILE3,"UUUU" The command in Table 28-3 allows any member of your user group to read or execute FILE3 from anywhere on the Expand network, but allows only you to write or purge it, and only from your local system. Example 28-3. File Readable and Executable to Owner’s User Group FUP SECURE FILE3,"COCO" The command in Table 28-4 allows any user to read FILE3, only you to write or purge it, and only a local super ID user to execute it—and these rules apply from anywhere on the Expand network. Example 28-4. File Readable to Any User FUP SECURE FILE3,"NU-U" Default File Security A newly created file has the default file security. You can set the default file security for the duration of your TACL session with the TACL command VOLUME; you can set it until further notice with the TACL command DEFAULT (further notice being another DEFAULT command). The command in Example 28-5 sets the default file security to “UUUU” until you override it with a VOLUME command or another DEFAULT command. Example 28-5. Setting Default File Security to “UUUU” DEFAULT, "UUUU" The command in Example 28-6 sets the default file security to “CUCU” for the duration of your TACL session. If you log off and log back on, the default file security reverts to “UUUU.” Example 28-6. Setting Default File Security to “CUCU” VOLUME, "CUCU" HP COBOL Manual for TNS and TNS/R Programs —522555-006 28- 5 Disk Input and Output Fixed-Length and Variable-Length Records If a Pathway server written in HP COBOL creates a file, the security of the file is that of the DEFAULT command active when the monitor process (PATHMON process) governing the server class starts to execute. Accessing Files on Other Nodes For you, as a user on one node, to have any access at all to a file on another node, even when the file’s security attributes permit it, you must have two remote passwords declared on each node. The TACL command REMOTEPASSWORD enables you to set the remote passwords on your own node. You must arrange with the system manager of the other node to have the same two passwords established on that node. For further information about remote passwords, see the Guardian User’s Guide. Fixed-Length and Variable-Length Records A file has variable-length records if its file description entry has either: • • • A RECORD CONTAINS m TO n CHARACTERS clause A RECORD IS VARYING FROM m TO n clause No RECORD clause and different-sized record descriptions If your source program does not explicitly describe a file as having variable-length records, the HP COBOL run-time write routine writes fixed-length physical records. The length of each physical record in the file is the larger of: • • The length of the longest record description entry for the file The maximum record length explicitly stated in the RECORD clause of the file description entry If a file contains records of different lengths, your program must declare it as having variable-length records to be able to read it. If the program declares the file (explicitly or implicitly) as having fixed-length records, and the program then tries to read a record shorter than the declared length, the read operation succeeds with a file status code “04.” Unstructured files must have fixed-length records. Exclusion Modes The exclusion mode is a feature of a file that determines whether other processes can read or write to the file being opened. If two separate processes are both writing to the same file, it is possible that both will attempt to write the same record and thereby corrupt the database. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28- 6 Disk Input and Output Time Limits Table 28-2. Exclusion Modes and Their Meanings Exclusion Mode While the process that opened the file has it open ... EXCLUSIVE No other process can read or write the file. PROTECTED Any other process can read the file, but no other process can write the file. SHARED Any other process can read or write the file. The exclusion mode can be specified in the OPEN statement or in an ASSIGN command. The exclusion mode in an OPEN statement takes precedence over the exclusion mode in an ASSIGN command. If neither the OPEN statement or ASSIGN command specifies an exclusion mode, the exclusion mode is PROTECTED if the file is being opened for input; EXCLUSIVE otherwise. Most server files have the exclusion mode SHARED so that several servers of the same class can all access the file. The servers use record locking to prevent conflicting write operations to the file. If you have a batch program that needs to open a file that one or more servers have opened for shared access, give careful consideration to whether the batch program should open the file for shared, protected, or exclusive access. If the batch program is doing something that affects the servers, it should probably open the file for exclusive access and thus fail if any server has it open. If the batch program cannot affect the servers, and the activity of the servers does not affect the activity of the batch program, then the batch program can open the file for shared access. Time Limits If you include a TIME LIMITS phrase in an OPEN statement, you can then include a TIME LIMIT phrase in a LOCKFILE, READ, or START statement to cause the statement to be abandoned if it does not finish executing in a certain amount of time. The TIME LIMIT phrase in a LOCKFILE, READ, or START statement sets the file’s status code so that the requester can tell that the data is not currently accessible. This action helps avoid deadlock. Reading Files From Called Programs Two separately compiled programs cannot share files; that is, if one program opens the file and then calls another separately compiled program, the caller cannot pass the file (or access to the file) to the called program. A pair of separately compiled calling and called programs can both have the same disk file open, but each has its own record area, its own current record pointer, its own file status data item, and so on. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28- 7 Disk Input and Output Sharing Files Among HP COBOL Programs When a HP COBOL run unit opens a file, the file remains open until one of these happens: • • • The run unit explicitly closes the file. The calling program cancels the called program that has the file open (with the CANCEL statement). The run unit terminates execution. A well-structured program unit has all the file activity for a certain file within one called program. The other programs in the run unit call that program to open, read, write, position, or close the file. In the called program, include a data item whose initial value indicates that the file is not open. When the program opens the file, set the data item to a value that indicates that the file is open. When the program closes the file, set the data item to a value that indicates that the file is closed. The value of the data item is retained between calls to that program unless a CANCEL statement intervenes. Sharing Files Among HP COBOL Programs Two programs in a run unit can refer to common file connectors in these circumstances: • • Any program that has described an external file connector can refer to that file connector. If a program G is contained within another program H, both programs can refer to a common file connector. They do so by referring to an associated global file name (or associated global record-name, in the case of the WRITE statement) described in either: ° ° The containing program H Any program that directly or indirectly contains H If several programs define a file connector as external (causing its storage location to be a single location outside all programs) and they also define the file connector as having a global name, then all such programs and all programs nested within each of them have access to the file connector. Sharing Files Among Different-Language Modules If your program consists of modules written in different languages, the modules can share the standard files—the predefined files called “standard input,” “standard output,” and “standard log” (except that FORTRAN modules cannot share “standard log” because FORTRAN does not support it). HP COBOL Manual for TNS and TNS/R Programs —522555-006 28- 8 Disk Input and Output Modification If you want to do mixed-language programming, compiling your program to run in the CRE is highly recommended. Although mixed-language programming is possible in the non-CRE environment, it is very limited because of incompatibilities between different languages’ run-time libraries. The CRE supports the languages HP C, HP COBOL, FORTRAN, Pascal, and TAL. For more information about the CRE in general and on mixed-language programs sharing standard files in particular, see the CRE Programmer’s Guide. Modification With the ENABLE utility, you can build a file-maintenance application that allows you to modify a disk file. ENABLE uses a Data Definition Language (DDL) file description to create a Pathway application that you can use to read and change the data in the disk file. For details, see the ENABLE User’s Guide. Maximum Number of Files The maximum number of files on a volume is determined during system configuration. The maximum number of files that a single process can have open concurrently depends on the amount of space available for file control blocks and buffers in the upper 64 KB of the process’s user data space. Types of HP Disk Files NonStop systems provide two types of disk files: • • Unstructured (Sequential) Files Structured Files Unstructured (Sequential) Files An unstructured file consists of a stream of bytes, and Enscribe allows each byte to be addressed directly. The organization of an unstructured file is the responsibility of the program that uses it. An HP COBOL program can only use an unstructured file as a sequential file. Two examples of unstructured files are object code files (file code 100) and EDIT files (file code 101). An EDIT file can have variable-length records, but all other unstructured files must have fixed-length records. No unstructured file can have alternate record keys. A program written entirely in HP COBOL can open an EDIT file for both input and output (or extension). The HP COBOL program cannot access the line numbers of the EDIT file, only the text of the lines themselves. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28- 9 Disk Input and Output Structured Files A program written entirely in HP COBOL can open unstructured files that are not in EDIT format for input or output, but cannot create an unstructured file. To use an existing unstructured file, your HP COBOL program must declare it: • • • • With ORGANIZATION SEQUENTIAL With ACCESS MODE SEQUENTIAL With fixed-length records (if the file is not an EDIT file) Without alternate keys When using an unstructured file, an HP COBOL program still operates on the basis of records, but they are strictly logical records. If one HP COBOL program writes an unstructured file of 80-character records, another program can read it with any record length. If the reading program expects 37-character records, the run-time routines deliver 37-byte pieces of the continuous byte stream. You can rewrite a record with another record of the same length, but you cannot delete a record. The HP COBOL run-time routines that access unstructured disk files manage those files directly. An unstructured file has no records, as far as Enscribe is concerned; the declarations in your HP COBOL program determine how the HP COBOL run-time routines manipulate the unstructured files. Structured Files Structured disk files are either entry-sequenced, relative, or key-sequenced. Table 28-3. Corresponding HP and HP COBOL Disk File Terms HP Term HP COBOL Term Relative Relative Entry-sequenced Sequential Key-sequenced Indexed The HP COBOL run-time routines that access structured disk files (entry-sequenced, relative, and key-sequenced) do so with the help of the operating system routines that are collectively called the Enscribe database record manager. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -10 Disk Input and Output Structured Files Table 28-4. Comparison of Structured File Characteristics Type of Structured File Characteristic Entry-Sequenced (Sequential) Records ordered by ... Order in which they were entered Record number Value of prime record key Access is by ... Record address or alternate record key Record number or alternate record key Prime or alternate record key Maximum alternate record key length = 253 bytes (249 if not unique) Maximum record number = 1,048,575 Maximum prime record key length = 522 bytes Maximum alternatekey length = 253 bytes (249 if not unique). Maximum alternate record key length = 253 bytes (253 minus prime length if not unique) Depends on length specified when record is written Is specified when file is created Depends on length specified when record is written Space occupied by a record ... Maximum logical record length = 4,072 bytes Relative Maximum logical record length = 4,072 bytes Key-Sequenced (Indexed) Maximum logical record length = 2,035 bytes Record can be shortened or lengthened No Yes Yes, and space freed by shortening a record can be reused within its block Record can be deleted No, but its space can be used for another record of the same size Yes, and its space can be reused Yes, and its space can be reused within its block In HP COBOL, the DEPENDING phrase of the RECORD IS VARYING clause enables you to designate a data item to receive the record length upon the successful completion of a READ statement and to control the record length for a WRITE statement. HP COBOL allows writing and reading zero-length records. To write a zero-length record, specify RECORD IS VARYING FROM 0 TO ... DEPENDING ON data-name and move the value zero into data-name before writing. After you read a file with the same record description, data-name has the value zero. TMF writes zero-length records when it backs out of transactions. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -11 Disk Input and Output Structured Files If an HP COBOL program describes fixed-length records, any zero-length records are discarded when read. If an HP COBOL program describes variable-length records, upon return from the READ statement, the entire record area is undefined. For this reason, you are advised to specify the DEPENDING phrase when reading variablelength records, and to process zero-length records appropriately (by ignoring them, for example). Under Enscribe, entry-sequenced files can have alternate keys. You must create these files by calling Enscribe directly in one of these ways: • • From your TACL session, use FUP. From within an HP COBOL program, call the FILE_CREATE_ procedure. Topics: • • • Entry-Sequenced (Sequential) Files Relative Files Key-Sequenced (Indexed or Queue) Files Entry-Sequenced (Sequential) Files An entry-sequenced file created by an HP COBOL program is either a series of fixedlength records or a series of variable-length records. Your program ordinarily reads entry-sequenced files sequentially. You can read the records in the order in which they appear in the file by opening the file for input and reading record after record. You can append records to the file by opening the file with an extension and writing records to the file. Enscribe allows each physical record of an entry-sequenced file to have any length from zero bytes (empty) to the maximum record length that was declared when the file was created. HP COBOL allows each logical record to have any length from zero bytes to the maximum record length declared explicitly in the file description entry or implicitly in the record definitions following the file description entry. If your source program describes the file as having variable-length records, each physical record uses only as many bytes of disk space as needed; therefore, the number of records for each block can vary according to the length of the records in each block (although some space at the end of a block can be wasted). If an entry-sequenced file has alternate keys, you can use a START statement to specify the next record to read. Relative Files Relative files contain records that exist independent of each other. Each record is associated with a unique relative record number—an ordinal number. The first record is number 1, the second is number 2, and so forth. The number exists independent of the contents of the record. You can read any record by number, but the record number is not part of the record. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -12 Disk Input and Output Structured Files The record numbers of a relative file need not be consecutive; Enscribe does not require that there be a record for each ordinal number between that of the first record and the highest number associated with any record in the file. If the HP COBOL runtime routines ask Enscribe for the record associated with a certain number and there is no such record in the file, Enscribe reports that no such record exists, and the HP COBOL run-time routine raises the invalid-key condition (and, if you defined a file status code data item, the run-time routine stores an appropriate value in it). You can also read the file in record-number order. In this case, Enscribe does not report absent records—it returns the records that exist. Enscribe can report the record number of each record as it is read. When you read a relative file this way, the HP COBOL run-time routines set the relative key data item to reflect the record number. Both Enscribe and HP COBOL (as an HP extension) provide two special record numbers: -1 and -2. If you specify record number -1, a record is written at the end of the file; if you specify record number -2, a record is written in the next available position. Enscribe allocates the same fixed amount of disk storage to each record. Each record can vary in length from empty to that fixed limit. In HP COBOL terms, you can write fixed-length records of any length up to the limit, or variable-length records of any length up to the limit. If HP COBOL creates the file for you, that limit is the larger of: • • The length of the longest record description entry for the file The maximum record length explicitly stated in the RECORD clause of the file description entry for the file If a relative file has alternate keys, you can use a START statement not only to specify the next record to read, but also to change the key of reference. You can write anywhere in the file, replacing existing records or installing a record at an ordinal position that had no record associated with it. You can replace an existing record with a record of a different length. You can delete a record. A deleted record is not the same as a record of length zero. A read operation with an invalid key leaves the contents of the record area undefined (that is, unpredictable). Key-Sequenced (Indexed or Queue) Files Key-sequenced files contain records that are stored in independent positions on the disk, but accessed in ascending sequence ordered by the unique value of a field within each record. Enscribe calls this field the prime record key; HP COBOL calls it the prime record key. You can read any record by specifying its key value. A key-sequenced file can be incomplete; Enscribe does not require that there be a record for each possible key value. If HP COBOL run-time routines ask Enscribe for the record associated with a certain key value, and there is no such record in the file, Enscribe reports that no such record exists and the HP COBOL run-time routine raises the invalid-key condition (and, if you defined a file status code data item, stores an appropriate value in it). HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -13 Disk Input and Output Creating and Using HP COBOL Sequential Files You can also read the file in key-value order. In this case, Enscribe does not report absent records—it returns the records that exist. Because the key is part of the record, you have access to the key value when you have read the record. Enscribe allocates only as much space on disk as necessary for each key-sequenced file record. Each record can vary in length from empty to the maximum record length defined for the file. In HP COBOL terms, you can write fixed-length or variable-length records (whichever the file was declared to have) of any length up to the limit. If HP COBOL creates the file for you, that limit is the larger of: • • The length of the longest record description entry for the file The length declared in the RECORD CONTAINS clause You can write records anywhere in the file, introducing new records or replacing existing records. You can replace an existing record with a record of a different length. You can delete a record. A deleted record is not the same as a record of length zero. In HP COBOL, the DEPENDING phrase of the RECORD CONTAINS clause enables you to designate a data item to receive the record length upon the successful completion of a READ statement and to control the record length for a WRITE statement. A read operation with an invalid key leaves the contents of the record area undefined (that is, unpredictable). Creating and Using HP COBOL Sequential Files In a sequential file—a file with sequential organization—records are arranged in a fixed predecessor-successor relationship that is established as the records are entered in the file. HP COBOL sequential files fall into these categories: • • • Entry-Sequenced Files Unstructured Files Unstructured EDIT Files HP COBOL programs can create, read, write, and purge all of the preceding forms of sequential file. To create an entry-sequenced file that has alternate keys, however, the COBOL program must use the FILE_CREATE_ procedure (see Unstructured Files). Entry-Sequenced Files An HP COBOL program can create and write an entry-sequenced file that any other HP product can later read. An HP COBOL program can read an entry-sequenced file created by any HP product. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -14 Disk Input and Output Unstructured Files An HP COBOL program can use the FILE_CREATE_ procedure to create an entrysequenced file that has alternate keys. An HP COBOL program cannot create an entry-sequenced file that has alternate keys directly, because the operating environment maintains the alternate keys in one or more separate files, whose names are recorded with the operating environment information about the entry-sequenced file (see Alternate Record Keys). Outside an HP COBOL program, you can use the TACL command FUP CREATE to create an entry-sequenced file that has alternate keys. Unstructured Files An HP COBOL program cannot create an unstructured file directly because the HP COBOL language cannot describe a file as unstructured. To create an unstructured file indirectly, an HP COBOL program calls the FILE_CREATE_ procedure. An easier way to create an unstructured disk file is to use FUP outside of any HP COBOL program. You can use the routine COBOL_ASSIGN_ to set file-code to 101 (for an EDIT file) or to set file-type to 0 (for a non-EDIT file). Suppose that your HP COBOL program needs an unstructured disk file named MYTEMP on volume $MYVOL that accommodates 5K eighty-byte records in one extent. Suppose that your HP COBOL program includes this data description: 01 WS-TEMP-NAME. 03 WS-VOL-NAME PIC X(8). 03 WS-SUBVOL-NAME PIC X(8). 03 WS-FILE-NAME PIC X(8). This HP COBOL code creates MYTEMP: ENTER "COBOL_ASSIGN_" USING MYTEMP, OMITTED, 0 The value zero in the third parameter causes the file to be unstructured. The omitted parameter is for the file code (which defaults to zero). The FUP command that is equivalent to the preceding HP COBOL code that created MYTEMP is: FUP CREATE $MYVOL.MYTEMP, TYPE U Additional FUP parameters enable you to specify these attributes: • • • • • File code Primary extent size Secondary extent size Whether the file is audited by TMF Whether the file’s label is to be copied to the disk every time the file’s EOF value changes For more information about FUP, see the Guardian Programmer’s Guide. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -15 Disk Input and Output EDIT Files EDIT Files An EDIT file is a special form of unstructured file whose file code is 101. HP COBOL programs can read, write, and create EDIT files. The file code 101 must be assigned to the file in one of these ways before the HP COBOL program opens the file: • • • • Create the file outside the program (with an HP editor or FUP). Have the HP COBOL program create the file by calling the FILE_CREATE_ procedure. Before executing the HP COBOL program, use the TACL command ASSIGN to associate the file’s name with the file code 101. If the program runs in the CRE, have the program call the routine COBOL_ASSIGN_ to associate the file’s name with the file code 101. Creating and Using HP COBOL Relative Files In a relative file—a file with relative organization—records are accessed by their record numbers. A record number is the position, relative to the beginning of the file, at which the record is stored. It is not related to the order in which the records were entered in the file. Record numbers need not be consecutive; for example, you can create a relative file with only three records whose numbers are 12, 19435, and 237. An HP COBOL program can create and write a relative file that any other HP product can later read. An HP COBOL program can read a relative file created by any HP product. An HP COBOL program can create, read, write, and purge relative files. An HP COBOL program must use the FILE_CREATE_ procedure to create a relative file that has alternate keys. An HP COBOL program cannot create a relative file that has alternate keys directly, because the operating environment maintains the alternate keys in one or more separate files whose names are recorded with the operating environment information about the relative file (see Alternate Record Keys). An HP COBOL program can create a relative file that does not have alternate keys simply by describing the file as having relative organization (but without alternate keys) and opening the file for OUTPUT, EXTEND, or I-O. The HP COBOL run-time routines create the relative file. There is one important difference between the way HP COBOL uses relative files and the way many other HP utilities use them: HP COBOL calls the first record in a relative file record 1, and the operating environment and most other HP software call the first record in a relative file record 0. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -16 Disk Input and Output Creating and Using HP COBOL Indexed Files The HP COBOL run-time routines that manipulate relative files convert HP COBOL record numbers to Enscribe record numbers by subtracting 1 from the value of each HP COBOL record number (except in the case of the two special record numbers -1 and -2 explained in Types of HP Disk Files). If your HP COBOL program calls a TAL routine and passes a relative key to it or receives a relative key from it, you must convert the record number appropriately. Similarly, if a file contains numeric values that are to be used as record numbers, all programs that use the file must use the same record numbering scheme. Example 28-7. Relative File Without Alternate Keys ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT RELFILE ASSIGN TO "$FIDDL.DEE.D" ORGANIZATION IS RELATIVE ACCESS MODE IS RANDOM RELATIVE KEY IS FIDLKEY. ... DATA DIVISION. FILE SECTION. FD RELFILE RECORD CONTAINS 5 TO 200 CHARACTERS LABEL RECORDS ARE OMITTED. 01 REL-RECORD. ... WORKING-STORAGE SECTION. ... 01 KEYS-GROUP. 03 FIDLKEY PIC 9(8) COMPUTATIONAL. These FUP commands declare the same relative file as the HP COBOL code in Example 28-7: SET TYPE R SET EXT (1000 RECS, 2000 RECS) SET REC 200 SET BLOCK 2048 CREATE $FIDDL.DEE.D Creating and Using HP COBOL Indexed Files In an indexed file—a file with indexed organization—records are accessed by the values of a key field within each record. An HP COBOL program can create and write an indexed file that any other HP product capable of handling indexed files can later read. An HP COBOL program can read an indexed file created by any HP product. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -17 Disk Input and Output Creating and Using HP COBOL Indexed Files An HP COBOL program can create, read, write, and purge indexed files. An HP COBOL program must use the FILE_CREATE_ procedure to create an indexed file that has alternate keys. An HP COBOL program cannot directly create an indexed file that has alternate keys, because the operating environment maintains the alternate keys in one or more separate files, whose names are recorded with the operating environment information about the indexed file (see Alternate Record Keys). An HP COBOL program can create an indexed file that does not have alternate keys simply by describing the file as having indexed organization (but without alternate keys) and opening the file for OUTPUT, EXTEND, or I-O. The HP COBOL run-time routines create the indexed file. Example 28-8. Indexed File Without Alternate Keys ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT INDFILE ASSIGN TO "$COBOL.PROGS.JAKE" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS JAKE-KEY. ... DATA DIVISION. FILE SECTION. FD INDFILE RECORD CONTAINS 5 TO 200 CHARACTERS LABEL RECORDS ARE OMITTED. 01 IND-RECORD. ... WORKING-STORAGE SECTION. ... 01 KEYS-GROUP. 03 JAKE-KEY PIC X(18). These FUP commands declare the same indexed file as the preceding HP COBOL code: SET TYPE K SET EXT (1000 RECS, 2000 RECS) SET REC 200 SET BLOCK 2048 CREATE $COBOL.PROGS.JAKE HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -18 Disk Input and Output Creating and Using Queue Files Creating and Using Queue Files A queue file is an indexed file (and therefore, a key-sequenced file) that can function as a queue. Processes can queue and dequeue records in a queue file. Queue files contain variable-length records that are accessed by values in designated key fields. Unlike other key-sequenced files, queue files have prime keys but cannot have alternate keys. The prime key for a queue file includes an 8-byte timestamp; you can add a user key if desired. The disk process inserts the timestamp when each record is inserted into the file, and maintains the timestamp during subsequent file operations. Topics: • • • • Creating a Queue File Opening a Queue File Reading a Queue File Writing to a Queue File For more information about queue files, see the Enscribe Programmer’s Guide. Creating a Queue File Before you can use a queue file, you must create it (with the FUP CREATE command, for example). Its prime key must have at least 8 bytes (for the timestamp). If you want to add a user key, describe it before describing the timestamp, as in Example 28-9. Example 28-9. Creating a Queue File With a Timestamp and a User Key SELECT queue-file ASSIGN to queuef ORGANIZATION IS INDEXED ACCESS MODE IS SEQUENTIAL RECORD KEY IS queue-key FD queue-file RECORD IS VARYING FROM 10 TO 100 CHARACTERS DEPENDING ON rec-len. 01 queue-rec. 02 queue-key. 03 user-key PIC XX. 03 timestamp PIC X(8). 02 the-rest PIC X(90). Opening a Queue File Open a queue file for shared access and SYNCDEPTH 0; for example: OPEN queue-file INPUT SHARED SYNCDEPTH 0 HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -19 Disk Input and Output Reading a Queue File Reading a Queue File When you read a record of a queue file, you have a choice of: • • Removing the Record From the Queue Leaving the Record in the Queue Removing the Record From the Queue To read a record and remove it from the queue, use the READ ... NEXT WITH LOCK statement. The compiler translates the READ ... NEXT WITH LOCK statement to a call to the Guardian routine READUPDATELOCK[X]. Leaving the Record in the Queue To read a record but leave it in the queue, use the READ ... NEXT statement (without LOCK). The compiler translates the READ ... NEXT statement to a call to the Guardian routine READ[X]. Writing to a Queue File To write to a queue file, be sure that it exists and then open it for input and output; for example: OPEN queue-file I-O SHARED SYNCDEPTH 0 In the file-control entry, specify ACCESS MODE IS RANDOM. After the file is open, use any form of the WRITE statement to write to it. The value that you write to the timestamp field does not matter, because the system replaces that value with its own timestamp. Establishing Starting Points in Files When you read a file using a key, you sometimes want to start at the record associated with a given key value and continue to read successive records according to the value of that key until you reach the record associated with a certain other value of that key. The key can be the prime key of a file of relative or indexed organization or an alternate key of any structured file. Such a key is termed the key of reference. The mechanisms in HP COBOL that implement this form of reading are the DYNAMIC access mode, the START statement, and the sequential form of the READ statement (a READ statement with a NEXT phrase). HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -20 Disk Input and Output Key of Reference Topics: • • • • Key of Reference Alternate Record Keys Positioning Repositioning to New Record With Same Alternate Key Key of Reference COBOL defines the “key of reference” as “the prime or alternate key currently being used to access records within an indexed file.” HP COBOL extends that definition to “the prime or alternate key currently being used to access records within an indexed or relative file, or the alternate key currently being used to access records in an entrysequenced file.” Enscribe uses the term “access path” for the sequence of records accessed by the key of reference. You establish the key of reference by executing a START statement or a READ statement containing a KEY phrase. In a START statement, the key can specify the identifier of an entire key field or the identifier of a leftmost subordinate of the key field. For example, in the record in Example 28-10, if LAST-NAME, DEPARTMENTNUMBER, and JOB-TITLE are alternate keys, you can use LN5, LN10, LN15, DN3, and J-T-PORTION as keys. Example 28-10. Key of Reference 01 PERSONNEL-REC. 03 NAME-FIELDS. 05 LAST-NAME. 07 LN1ST. PIC X. 07 LN2ND. PIC X. ... 07 LN25TH. PIC X. 05 FIRST-NAME PIC X(25). 05 M-I-NAME PIC X. 03 DEPARTMENT-NUMBER PIC 9999. 03 DN REDEFINES DEPARTMENT-NUMBER. 05 DN3 PIC 999. 05 FILLER PIC X. 03 JOB-TITLE. 05 J-T-PORTION. 07 J-T PIC X OCCURS 1 TO 25 TIMES DEPENDING ON J-T-LENGTH. 66 LN5 RENAMES LN1ST THRU LN5TH. 66 LN10 RENAMES LN1ST THRU LN10TH. 66 LN15 RENAMES LN1ST THRU LN15TH. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -21 Disk Input and Output Alternate Record Keys After you have established the key of reference, you can execute sequential READ statements (READ NEXT statements) to read successive records according to that key: records in a relative file in ascending record-number order, records in an indexed file in ascending prime-key order, or records in any structured (sequential) file in ascending alternate-key order. You can also execute sequential READ REVERSED statements to read records in reverse order. The key-of-reference concept enables you to select one of several possible keys and then use a single sequential READ statement to read a subset of records in a file. Suppose that you have the personnel record in Example 28-10, and that the employee number (which is not even part of the record) is the record number and therefore the prime key. By selecting an alternate key as the key of reference, you can start reading at the first “Adams” in the file, the first member of department 3141, or the first person having the job “Clerk.” Then you can use a single READ statement to read successive records for employees named “Adams,” successive records for employees whose names follow “Adams” alphabetically, records of employees in the department number 3141 or higher, or records of employees whose job title is “Clerk” or follows “Clerk” in collating sequence order. Uppercase and lowercase letters are not equivalent in keys. When a data item with a mixed-case value is to serve as a key, you have these choices: • • • Leave the value alone, and accommodate any case differences. Shift the value into uppercase in the existing data item. Create an uppercase copy of the value in another data item in the record and use the uppercase copy for key operations. Alternate Record Keys An alternate record key (or alternate key) is a data item, other than the prime record key, whose value identifies a record in a structured file. COBOL restricts alternate keys to indexed files. HP COBOL also allows alternate keys in entry-sequenced (sequential) and relative files. In HP COBOL, an alternate key can occur anywhere in a record. The DUPLICATES phrase of the ALTERNATE RECORD KEY clause of the file-control entry determines whether alternate key values must be unique. If unique, an alternate key can have up to 253 characters; otherwise, it can have up to 253 characters minus the length of the prime key. Alternate keys can overlap both each other and the prime key, but no two alternate keys can start at the same character position (offset) in the record. Enscribe implements alternate keys using one or more alternate-key files. For each file with one or more alternate keys (primary file), Enscribe maintains at least one alternate-key file. For each unique alternate key with a different key length, Enscribe maintains a separate alternate-key file. You can refer to multiple unique alternate keys of the same key length through a single alternate-key file. The directory entry for the primary file with alternate keys includes the names and other attributes of the associated alternate-key files. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -22 Disk Input and Output Positioning Each record of an alternate-key file has three fields: the alternate key specifier, the value of the alternate key, and the value of the prime key. An alternate key specifier is a two-character code that identifies an alternate key defined for a primary file. An alternate-key file is a key-sequenced file. For every record in the primary file, there are at most as many records in the alternate-key file as there are alternate keys declared for that alternate-key file. Using FUP CREATE, you can specify a null-value character for each alternate key. Any record with an alternate-key field composed entirely of the null-value character is not represented in the alternate-key file. This strategy saves space when you have alternate keys for which many records have the same value, such as zeros or spaces, and you are not interested in locating these records by their alternate key. If you have a structured file without alternate keys and you want it to have alternate keys, you can use FUP to create the alternate-key file and to load the alternate-key file. If you describe your database with DDL, the DDL compiler can produce the necessary FUP commands to create prime-key and alternate-key files. For more information about alternate keys, see the Guardian Programmer’s Guide. Caution. Because updating the alternate-key file can require multiple write operations, certain types of failures can cause the operating environment to fail to record alternate keys. The record and some of its alternate keys might be updated while other alternate keys might not be updated. To prevent this, use TMF to verify that an update to a file with alternate keys is either completed or aborted. For information about TMF, see Section 32, Fault-Tolerant Processes. Positioning Enscribe provides three positioning modes: approximate, exact, and generic. Only approximate positioning is available in COBOL; both approximate and generic positioning are available in HP COBOL. Neither COBOL nor HP COBOL supports exact positioning; it involves a variablelength key. In using Enscribe directly, you specify a maximum key length for a keysequenced file’s prime key or for any alternate key. When you call the KEYPOSITION routine (analogous to HP COBOL’s START statement), you can specify a length and a value: a compare length that is shorter than or equal to the maximum key length, and a value of that length for the key. Exact positioning means that the only records delivered are those whose key is the same length as the compare length and whose value is the same as the key value. If the key is unique, at most one such record exists in the file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -23 Disk Input and Output Positioning Table 28-5. Enscribe File Positioning Modes Positioning Mode Starting Position Defined by End of File Is Signaled Available in HP COBOL? Exact Positioning Whole key value When key no longer identical to start key No Approximate Positioning Whole or partial key value At physical end of file Yes Generic Positioning Whole or partial key value When key or partial key no longer identical to start key Yes Approximate Positioning With approximate positioning, you execute the START statement with a starting key, and the next READ statement retrieves the next record in the access path that contains a value in the corresponding data item that bears the stated relationship (equal to, greater than, or not less than) to the starting key. Subsequent READ statements receive the records that follow in the access path. An EOF condition arises when the actual end of the file is reached. Approximate positioning is the default, but you can include an APPROXIMATE phrase in the START statement for documentation purposes if necessary. Generic Positioning Generic positioning is like approximate positioning except that you specify a starting key that (usually) has a shorter length than the key data item in the record. Also, the only relation permitted with the key is the equal relation. Subsequent READ statements retrieve the records in the access path whose key values match the starting key for as many characters as the start key has. Suppose you want to read only the Adamses in the personnel file described in Key of Reference. With the GENERIC phrase of the START statement (an HP extension to COBOL), you specify that when a READ NEXT statement obtains a record with a LAST-NAME value that does not begin with the five characters “Adams,” the statement must raise the EOF condition and not deliver that record to the program. You usually use generic positioning with partial keys. Using key values that include trailing spaces, you can achieve an effect similar (but not identical) to exact positioning. Consider the case of “Adams.” If you want to find only the Adamses (but not any Adamsons), you can use a complete key of “Adams” plus enough spaces to fill out the key. Suppose that an HP COBOL program includes the code in Example 28-11. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -24 Disk Input and Output Positioning Example 28-11. Generic Positioning INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT NAME-FILE ASSIGN TO "$JUICE.APPLE.NAME" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS KEY-NUMBER ALTERNATE RECORD KEY IS KEY-NAME WITH DUPLICATES ... DATA DIVISION. FILE SECTION. FD NAME-FILE RECORD CONTAINS 5 TO 100 CHARACTERS LABEL RECORDS ARE OMITTED. 01 NAME-FILE-REC. 02 KEY-NUMBER PIC X(5). 03 FILLER PIC X(3). 02 KEY-NAME PIC X(35). 02 REDEF-KEY REDEFINES KEY-NAME. 04 FIRST-5 PIC X(5). 04 FILLER PIC X(30). ... PROCEDURE DIVISION. THE-TOP. OPEN I-O NAME-FILE. PERFORM SHOW-NAMES. STOP RUN. SHOW-NAMES. DISPLAY "SHALL I START THE FILE GENERIC?". ACCEPT WHAT-FILE. IF WHAT-FILE = "Y" DISPLAY "WHAT FIRST 5 LETTERS SHALL I USE?" ACCEPT FIRST-5 START NAME-FILE KEY = FIRST-5 GENERIC ELSE DISPLAY "WHAT APPROXIMATE NAME SHALL I START AT?" ACCEPT KEY-NAME START NAME-FILE KEY = KEY-NAME APPROXIMATE. PERFORM GET-AND-DISPLAY UNTIL NOT NAME-FILE-OK. GET-AND-DISPLAY. READ NAME-FILE NEXT; AT END MOVE "99999-----EOF" TO NAME-FILE-REC. DISPLAY KEY-NUMBER, "---", KEY-NAME. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -25 Disk Input and Output Repositioning to New Record With Same Alternate Key Suppose that NAME-FILE contains these records: 00005 00010 00121 01010 12532 43132 52353 54116 54396 ADAMS ADAMSKI JOHNSON ADAMS REITWIESNER SMITH ROTH ADAMS-JONES ADAMSSOHN Without the GENERIC phrase, if the first key is “ADAMS” followed by 30 spaces, the program displays: 00005---ADAMS 01010---ADAMS 54116---ADAMS-JONES 00010---ADAMSKI 54396---ADAMSSOHN 00121---JOHNSON 12532---REITWIESNER 52353---ROTH 43132---SMITH 99999-----EOF With the GENERIC phrase, if the first key specifies that its first five characters must be “ADAMS,” the program displays: 00005---ADAMS 01010---ADAMS 54116---ADAMS-JONES 00010---ADAMSKI 54396---ADAMSSOHN 99999-----EOF Repositioning to New Record With Same Alternate Key COBOL provides no mechanism for repositioning to one of several records having the same alternate key. HP COBOL provides a mechanism: the POSITION phrase of the START statement. The POSITION phrase enables you to write context-free servers that must return large sets of records to their requesters. Suppose you want your server to return one record for each product that includes part number 1345-55433. To keep message length and buffer space to a reasonable size, the server can return only 10 records. A server should not retain a context from a requester. Each server should be able to serve any requester. The POSITION phrase can specify the prime key, a leftmost subordinate of the prime key, an alternate key, or a leftmost subordinate of an alternate key in the KEY phrase. The prime-key value is in a separate data item; it need not be inserted in the record area of the file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -26 Disk Input and Output Repositioning to New Record With Same Alternate Key The POSITION phrase enables a server to pass the value of the prime key of the most recently processed record back to a requester. The requester can then send the primekey value to a server with its next request, and the server can use that value in a POSITION phrase of the START statement (and also as the alternate key in the KEY phrase) to uniquely specify a record at which to resume processing. The POSITION phrase includes the optional keyword, AFTER. Without AFTER, the START statement establishes the current file position at the same record specified by the prime-key value. With AFTER, the START statement establishes the current file position at the next record (if any) after the record specified by the prime-key value in the POSITION phrase. The role of the POSITION phrase is to reestablish the environment after the last read using a partial key. The execution of a START statement with a POSITION phrase does not report an invalid-key condition—the next READ statement executed could report an EOF condition. To resume processing a file after an interruption, take the same START statement that you used to initiate processing and add a POSITION phrase, specifying the key relation EQUAL. It might be possible to collapse the initial START statement and the repositioning START statement into a single statement when it is not important for the initial positioning operation to detect an invalid-key condition if no record matches the key relation in a normal initial start operation. If this is acceptable, write the program for just the continuation repositioning case and use LOW-VALUES for the prime record key (or 1 for the relative key) in the initial case. This strategy is especially useful for servers. The server need only be implemented with a continuation request and can depend on the requester to supply LOW-VALUES (or 1) for the prime key in the initial request. Example 28-12 is a skeleton program for a server. It accepts several types of request, one of which calls for a list of part records (beginning at a specified part name) to be returned to the requester. If more than 10 such records must be returned, the requester must accept 10 at a time and request the next portion by passing back the last part number it received and the part name. This program is incomplete and is provided only to illustrate the POSITION phrase of the START statement. Example 28-12. Use of START With the POSITION Phrase (page 1 of 4) IDENTIFICATION DIVISION. PROGRAM-ID. PART-LIST-SERVER. AUTHOR. KELLY COBOL. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. TXP. OBJECT-COMPUTER. TXP. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -27 Disk Input and Output Repositioning to New Record With Same Alternate Key Example 28-12. Use of START With the POSITION Phrase (page 2 of 4) INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT MESSAGE-IN ASSIGN TO "$RECEIVE" FILE STATUS IS RECEIVE-FILE-STATUS. SELECT MESSAGE-OUT ASSIGN TO "$RECEIVE" FILE STATUS IS RECEIVE-FILE-STATUS. SELECT PART-FILE ASSIGN TO "PART" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS PART-NO OF PART-DATA-RECORD ALTERNATE RECORD KEY IS PART-NAME OF PART-DATA-RECORD WITH DUPLICATES FILE STATUS IS FILE-STAT. RECEIVE-CONTROL. TABLE OCCURS 5 TIMES SYNCDEPTH LIMIT IS 1 REPLY CONTAINS 1100 CHARACTERS. DATA DIVISION. FILE SECTION. FD MESSAGE-IN LABEL RECORDS ARE OMITTED RECORD CONTAINS 1 TO 200 CHARACTERS. 01 PART-DEL-GET-LIST-MSG. 02 PRT-HEADER. 03 REPLY-CODE 03 APPLICATION-CODE 03 FUNCTION-CODE 03 TRANS-CODE 03 TERM-NO 03 LOG-REQUEST 02 PART-NO 02 PART-NAME PIC PIC PIC PIC PIC PIC PIC PIC S9(4) X(2). X(02). 9(2). X(15). X(01). X(10). X(50). COMP. FD MESSAGE-OUT LABEL RECORDS ARE OMITTED RECORD CONTAINS 1 TO 1100 CHARACTERS. 01 SERVER-REPLY. 02 PRT-HEADER. 03 REPLY-CODE PIC S9(4) COMP. ... {same as PRT-HEADER of PART-DEL-GET-LIST-MSG } 02 ERROR-CODE PIC S9(4) COMP. 02 GUARDIAN-ERR PIC S9(4) COMP. 02 ERROR-MESSAGE. 03 ERROR-FILE-NO PIC X(05). 03 ERROR-TEXT PIC X(65). 01 PART-GET-REPLY. 02 PRT-HEADER. 03 REPLY-CODE PIC S9(4) COMP. ... {same as PRT-HEADER of PART-DEL-GET-LIST-MSG } 02 PART-DATA. 03 PART. 04 PART-NO PIC X(10). 04 PART-NAME PIC X(50). ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -28 Disk Input and Output Repositioning to New Record With Same Alternate Key Example 28-12. Use of START With the POSITION Phrase (page 3 of 4) 01 PART-LIST-REPLY. 02 PRT-HEADER. 03 REPLY-CODE PIC S9(4) COMP. ... {same as PRT-HEADER of PART-DEL-GET-LIST-MSG } 02 LINE-COUNT PIC 9(04). 02 ALL-PART-LINES. 03 PART-LINE OCCURS 10 TIMES. 04 PART-NO PIC X(10). 04 PART-NAME PIC X(50). 04 CUST-NUM PIC 9(06). ... FD PART-FILE LABEL RECORDS ARE OMITTED. 01 PART-DATA-RECORD. 02 PART. 03 PART-NO 03 PART-NAME ... WORKING-STORAGE SECTION. ... PIC X(10). PIC X(50). PROCEDURE DIVISION. MAIN SECTION. BEGIN-COBOL-SERVER. PERFORM A-INIT. PERFORM B-TRANS UNTIL CLOSE-FROM-REQUESTER. PERFORM C-EOJ. STOP RUN. A-INIT. OPEN INPUT MESSAGE-IN OUTPUT MESSAGE-OUT INPUT PART-FILE SHARED. SYNCDEPTH 1 C-EOJ. CLOSE MESSAGE-IN MESSAGE-OUT PART-FILE. B-TRANS. MOVE SPACES TO PART-DEL-GET-LIST-MSG. PERFORM 920-GET-SERVER-MSG. IF NOT CLOSE-FROM-REQUESTER PERFORM B-TRANS-CASE. B-TRANS-CASE. IF TRANS-CODE OF PART-DEL-GET-LIST-MSG = LIST-BY-NO-TRANS OR LIST-BY-NAME-TRANS PERFORM 200-GET-PART-LIST-RCD ELSE PERFORM 960-INVALID-T-CODE . 100-GET-PART-RCD. PERFORM 110-INIT-REPLY. PERFORM 120-READ-PART-INFO. 110-INIT-REPLY. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -29 Disk Input and Output Repositioning to New Record With Same Alternate Key Example 28-12. Use of START With the POSITION Phrase (page 4 of 4) 120-READ-PART-INFO. MOVE PART-NO OF PART-DEL-GET-LIST-MSG TO PART-NO OF PART-DATA-RECORD. PERFORM 945-READ-PART-KEY. IF NO-ERROR PERFORM 914-GET-REPLY ELSE PERFORM 990-BUILD-ERROR-REPLY PERFORM 910-SERVER-REPLY. 200-GET-PART-LIST-RCD. PERFORM 210-INIT-REPLY. PERFORM 220-BUILD-REPLY. 210-INIT-REPLY. MOVE SPACES TO SERVER-REPLY. MOVE PRT-HEADER OF PART-DEL-GET-LIST-MSG TO PRT-HEADER OF SERVER-REPLY. MOVE ZERO TO REPLY-CODE OF PART-LIST-REPLY LINE-COUNT OF PART-LIST-REPLY MOVE SPACES TO ALL-PART-LINES OF PART-LIST-REPLY. 220-BUILD-REPLY. MOVE PART-NO OF PART-DEL-GET-LIST-MSG TO PART-NO OF PART-DATA-RECORD. MOVE PART-NAME OF PART-DEL-GET-LIST-MSG TO PART-NAME OF PART-DATA-RECORD. PERFORM 935-START-PART-REPOSITIONED. IF NO-ERROR PERFORM 230-GET-PART VARYING I FROM 1 BY 1 UNTIL I > MAXLIST OR FILE-ERROR IF NO-ERROR OR END-OF-FILE PERFORM 916-LIST-REPLY ELSE PERFORM 990-BUILD-ERROR-REPLY PERFORM 910-SERVER-REPLY ELSE PERFORM 990-BUILD-ERROR-REPLY PERFORM 910-SERVER-REPLY. 230-GET-PART. MOVE I TO LINE-COUNT OF PART-LIST-REPLY. PERFORM 940-READ-PART-NEXT. IF NO-ERROR MOVE PART-NO OF PART-DATA-RECORD TO PART-NO OF PART-LIST-REPLY (I) MOVE PART-NAME OF PART-DATA-RECORD TO PART-NAME OF PART-LIST-REPLY (I) ... ELSE IF END-OF-FILE MOVE PART-FILE-EOF TO REPLY-CODE OF PART-LIST-REPLY SUBTRACT 1 FROM LINE-COUNT OF PART-LIST-REPLY. 910-SERVER-REPLY. WRITE SERVER-REPLY. 914-GET-REPLY. WRITE PART-GET-REPLY. 916-LIST-REPLY. WRITE PART-LIST-REPLY. 935-START-PART-REPOSITIONED. START PART-FILE KEY IS = PART-NAME OF PART-DATA-RECORD POSITION PART-NO OF PART-DATA-RECORD APPROXIMATE. 960-INVALID-T-CODE. MOVE INVALID-TRANSACTION TO REPLY-CODE OF SERVER-REPLY. PERFORM 910-SERVER-REPLY. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -30 Disk Input and Output Optimizing Disk File Processing Optimizing Disk File Processing The features of Enscribe that protect the database from corruption also slow down the Enscribe input and output routines. If you can afford less protection, you can improve the performance of the HP COBOL disk input and output routines. You can afford less protection when a process has exclusive access to a file, or when it is acceptable that other processes that read the file might not receive the most recent copy of a changing record. These topics explain how to use these types of files to optimize disk file processing: • • • • Unstructured Files Structured Files Files With Alternate Keys Partitioned Files Unstructured Files A process can read and write unstructured files faster than it can read structured files, whether the logical records of the unstructured file are blocked or not. A process can read and write blocked unstructured files considerably faster than it can read and write unblocked unstructured files. HP COBOL performs record blocking (for write operations) and deblocking (for read operations) of unstructured files when all of these conditions are met: • • • • The program describes the file’s organization as sequential. The program does not describe the file as being composed of variable-length records (except in the case of EDIT files, which can be described as having variable-length records). The program includes a BLOCK CONTAINS clause that specifies an even multiple of the established record size. The program does not describe the file with a LINAGE clause or an ALTERNATE RECORD KEY clause. Structured Files For structured files, the file system provides two independent record blocking performance enhancements—cache buffering and sequential block buffering. In addition, HP COBOL has Fast I-O, a faster enhancement built on top of sequential block buffering. The type of record blocking used for a file is determined by number in the RESERVE clause of the file-control entry. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -31 Disk Input and Output Structured Files In the non-CRE environment, the value of number must be in the range 1 through 8 and is interpreted: Value of number Effect on Record Blocking 1 No buffering or HP COBOL Fast I-O 2 or greater HP COBOL Fast I-O if the assigned file qualifies; if not, sequential block buffering for input and buffered cache for output if the assigned file qualifies; otherwise, normal I-O. number is the number of blocks to buffer In the CRE, the value of number must be in the range 1 through 32 and is interpreted: Value of number Effect on Record Blocking 1 No buffering or HP COBOL Fast I-O 2 Sequential block buffering on input and buffered cache on output if the assigned file qualifies 3 or greater HP COBOL Fast I-O if the assigned file qualifies; if not, sequential block buffering for input and buffered cache for output if the assigned file qualifies; otherwise, normal I-O number is the number of blocks to buffer The BLOCK CONTAINS clause has no effect when a RESERVE clause is present— the block size of the existing file is used. Topics: • • • Cache Buffering Sequential Block Buffering HP COBOL Fast I-O Cache Buffering Cache buffering is a disk-process feature that speeds up the writing of structured disk files. A cache, or buffer pool, is an area of system memory reserved for buffering blocks of data for transfer to or from a disk. If cache buffering is not used, each logical write operation causes the cache block containing the record to be written immediately to the disk. This is called write-through cache. If cache buffering is used, the records are held in the cache (in system memory) and not immediately written through to the disk. The blocks are written to disk only when certain situations require it. This is called buffered cache. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -32 Disk Input and Output Structured Files By default, files that are audited by TMF use cache buffering, and files that are not audited do not. Caution. Do not use cache buffering with a program that requires that each record actually be written on the disk before the next statement in the program is executed. If your program is writing to a file that is opened with the exclusion mode SHARED or PROTECTED, give careful consideration to the use of cache buffering, because other processes can read the file and could read a record that your writing process has updated but which the file system has not yet delivered to the disk. When a file is opened, the call to the FILE_OPEN_ procedure includes a parameter that determines whether or not cache buffering is used—that is, whether the file has the attribute BUFFERED. You can give a file the BUFFERED attribute by using FUP routines or the corresponding Enscribe routines through environment procedure calls; then all output to the file is done with cache buffering. Each disk has its own cache. Each cache is configured to have space for a certain quantity of disk data. Each disk device has an associated disk process that performs the physical operations of reading data from the disk into cache memory and writing data from cache memory to the disk. When a process requests a record from a given disk, the Enscribe record manager checks that particular cache for the block that contains the record. If that block is not present in the cache, Enscribe must perform a physical read from the disk and then return the record to the application process. If the block is present, Enscribe does not need to do the read operation; it can simply return the record to the application process. Sequential Block Buffering Sequential block buffering (SBB) is an Enscribe feature that speeds the sequential reading of a structured file by reading a block of records together into a memory buffer. Enscribe allocates the buffer in the process file segment outside the data space of your process. Note. With the advent of the DP2 disk processing system, “normal” I/O could be faster than sequential block buffering, depending on the number of records per block. For example, a file containing eight 4K blocks and 1600 records requires one physical I/O operation and 1600 interprocess messages in normal mode, but eight physical I/O operations and only eight interprocess messages in SBB mode; on the other hand, a file with eight 4K blocks and only eight records requires one physical I/O and eight interprocess messages in normal mode, but eight physical I/O operations and eight interprocess messages in SBB mode If the file has no alternate keys, the size of the buffer is the block size of the file. If the file has alternate keys, the alternate-key file (not the primary file) is buffered, because the alternate-key file is being read sequentially, while the primary file is probably being read randomly. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -33 Disk Input and Output Structured Files Without sequential block buffering, every time an application program performs a read operation, the HP COBOL run-time routines must call the READ routine, which causes the file system to send a message to the disk process and causes the disk process to return a message containing the record. With sequential block buffering, only entire blocks are sent, and any records in the block after the first one are delivered from the process file segment without any message traffic. HP COBOL provides sequential block buffering for a file when all of these conditions are met: • • • The file is structured. The file’s open mode is INPUT or I-O. The program declares the file to have sequential access mode (although organization can be sequential, relative, or indexed). Caution. Do not use sequential block buffering for a file opened for shared access. If you do, a process could read data that is not up to date while another process alters the file. HP COBOL Fast I-O Fast I-O is an HP COBOL enhancement in input-output performance beyond that of sequential block buffering or buffered cache. With HP COBOL Fast I-O, the HP COBOL run-time routines use an auxiliary block buffer and perform the blocking and deblocking in local storage. This process operates 2 or 3 times faster than when the operating environment performs the blocking and deblocking operations. HP COBOL Fast I-O is available if the HP COBOL program and the structured file upon which it is to operate meet these criteria: • • • • • Either the program runs in the non-CRE environment and the file is organized sequentially, or the program runs in the CRE (in which case the file can have any organization). The file description includes a RESERVE clause with a number specifying the number of blocks to buffer. In the non-CRE environment, the number must be greater than 1; in the CRE, it must be greater than 2. The file description does not include a LINAGE clause or a CODE-SET clause. The file was not opened with time limits (as with the TIME LIMITS phrase in the OPEN statement). The program is not compiled with the NONSTOP directive. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -34 Disk Input and Output • Files With Alternate Keys The specifications in the OPEN statement, or the attributes derived during the open operation by some other means (such as from a TACL ASSIGN command), conform to: ° ° The open mode is INPUT or OUTPUT. ° If the open mode is OUTPUT, the exclusion mode is EXCLUSIVE. If the open mode is INPUT, the exclusion mode is PROTECTED or EXCLUSIVE. Note. HP COBOL Fast I-O is not recommended for an indexed file that has had many records inserted or deleted since it was created. If you want to use HP COBOL Fast I-O on such a file, first use FUP RELOAD to reorganize it. If all of the preceding qualifications are satisfied at run time, HP COBOL Fast I-O is used only if memory resources are available. For a file opened for output, the loader creates the file. The loader is also used by FUP, SQL/MP, and other products. The loader manages its own extended data segment to write the file. The loader requires local storage, which is allocated by the run-time system. The amount of local storage is approximately 800 bytes (the exact amount depends on the type of the file and other factors). If the necessary storage is not available, the OPEN statement returns file status “07” and buffered cache is used to write the file. For a file opened for input, HP COBOL Fast I-O allocates space for double buffering from a buffer pool that is in its own extended data segment and is of a fixed size. Buffer size is determined by multiplying the number in the RESERVE clause by the data block size of the file (to see this size, use the command FUP INFO file-name, DETAIL). Then, based on various factors such as the maximum transfer allowed, a read buffer size that is not larger than 30,720 bytes is selected. The total space allocated from the buffer pool is twice the read buffer size. If there is not enough space (as when several files are opened for input using HP COBOL Fast I-O at the same time), the OPEN statement returns file status “07” and sequential block buffering is used for the file. The buffer pool space returns to the pool when the file is closed. The SAME AREA clause has no effect on allocation or deallocation from this buffer pool. If the file is being created and the maximum file size is exceeded, the corrupt bit is set in the file header and the program terminates abnormally. Attempting to open the file causes a file system error. If the file is sequential, you can use FUP to clear the corrupt bit and read what was written to the file (all of the records you released with WRITE will probably not be there). If the file is relative or indexed, the file is unusable. Files With Alternate Keys You can improve the performance of alternate-key file access by: • • • Declaring Null Values for Alternate Keys Making the Main File Entry-Sequenced or Relative Not Updating the Alternate-Key File Automatically HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -35 Disk Input and Output Files With Alternate Keys Declaring Null Values for Alternate Keys When you create an alternate-key file with FUP CREATE, you can declare a null value for any alternate key. When you insert a record, if each byte in the alternate-key field contains that null value, the alternate-key reference is not added to the alternate-key file. This reduces both the size of the alternate-key file and the access time for the records of a file being accessed according to that alternate key. It also makes the records that have null values invisible when you read the file by an alternate key for which a null value has been defined. If you update a record in the file in such a way that the alternate-key field receives a null value, the alternate-key reference for that record is deleted from the alternate-key file. If you read a file according to an alternate key for which a null value has been defined, records containing the null value of the alternate key are not read. The most common null values are the ASCII space and the binary zero. Making the Main File Entry-Sequenced or Relative If your main file has several keys defined but no one key is used substantially more than any other keys, consider making that main file a relative or entry-sequenced file rather than a key-sequenced file. Every time you read a key-sequenced file by prime key, you cause two possible physical read operations: one for the key and one for the record. Every time you read a key-sequenced file by alternate key, you cause four possible physical read operations: one for the alternate key, one for the alternate-key record, one for the prime key, and one for the record. If the main file has two keys and the probability of reading the file by any given key is about even, then half the time you could cause two physical read operations and half the time you could cause four. For each logical read operation, you average three physical read operations. If the main file has two keys and the probability of reading the file by any given key is about even, you also average three physical read operations for each logical read operation if you choose entry-sequenced or relative organization for the main file; however, if the main file has more than two keys, the average number of physical read operations per logical read operation improves. The average number of physical read operations per logical read operation improves even further when several records in the alternate-key file or main file are in the same physical block and no physical read is required, such as when you are reading sequentially on an alternate key. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -36 Disk Input and Output Partitioned Files Not Updating the Alternate-Key File Automatically Another way to improve the performance of alternate-key file access is to specify that the alternate-key file not be automatically updated by the operating environment when the value of an alternate-key field changes (use the FUP parameter NOUPDATE). This is appropriate when your only means of updating the file is a batch update program that runs when no interactive processes are reading the file; you can run the batch update, then re-create the alternate-key file and reload it. Do not use the NOUPDATE parameter if the file is updated interactively, because the changed records do not cause any changes in the alternate-key file until the next batch update. Partitioned Files Partitioned files can be accessed faster because separate read heads are used for each partition. Loss of access to one disk need not mean loss of access to the entire file. You can divide an indexed file according to the value of the prime key and have, for example, A through C on the first disk volume and U through Z on the last disk volume. If one of the disks is taken offline for maintenance, or if one system of the network is inaccessible due to communication problems, the remainder of the partitioned file is still accessible. To open a partitioned file when some partitions cannot be accessed, an HP COBOL program must use the routine COBOL85^SPECIAL^OPEN (in the non-CRE environment) or COBOL_SPECIAL_OPEN_ (in the CRE). If all partitions can be accessed, an HP COBOL program can open a partitioned file with the OPEN statement. For more information about partitioned files, see Partitioned Files. Optimizing Disk File Storage You can specify at file creation time that an indexed or data file is to be compressed for more space-efficient storage at a slight expense of speed. Enscribe compresses records by eliminating duplicate leading characters from one record to the next and replacing them with a one-byte count of the duplicate characters. If a file has a significant amount of duplicated data, the storage saving can be substantial. The prime key of a compressed file must be at the beginning of the record. Compression is recommended for an indexed file in which the first records of successive blocks have similar prime-key values. Compression is recommended for an alternate-key file in which several alternate keys have the same value. For more information about compressing indexed and data files, see the Guardian Programmer’s Guide. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -37 Disk Input and Output Avoiding Deadlock Avoiding Deadlock Deadlock is a situation in which two processes are in contention for a single-user resource. If both processes require exclusive use of both resources, they are deadlocked. Neither can proceed until the other surrenders control of the resource it has under its control. If two servers get into a deadlock, their respective requesters are also deadlocked because neither requester receives a reply from its server. One example of deadlock is when one process has opened a file (call it ABLE) and needs to open another file (call it BAKER), while another process has opened BAKER and now needs to open ABLE. Another example of deadlock is when one process has locked a record in a file (call it record n ) and wants to read another record in the file (call it record m ), while some other process has locked record m and wants to read record n. The ways to avoid deadlock are: • • Locking and Unlocking Files and Records Setting Time Limits on Input-Output Operations Locking and Unlocking Files and Records The most complete way for a process to lock a file is to open the file for exclusive access (open it with the exclusion mode EXCLUSIVE). This strategy prevents all other processes from reading or writing the file. If it is not feasible for one process to have exclusive control of a file for when it has the file open, there are alternatives. One alternative is protected access. When a process opens a file for protected access (opens it with the exclusion mode PROTECTED), other processes can read and write the file while the opening process has it open, but cannot write the file until the opening process closes the file. Another alternative is shared access. When a process opens a file for shared access (opens it with the exclusion mode SHARED), other processes can read and write the file while the opening process has it open. When a file is open for shared access and one process needs exclusive access to the file temporarily, that process can lock the file with a LOCKFILE statement, operate on it, and then unlock it with an UNLOCKFILE statement. If a process only needs temporary exclusive access to a record of the file, the process can temporarily lock the record with a READ statement with a LOCK phrase and then unlock it with an UNLOCKRECORD statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -38 Disk Input and Output Setting Time Limits on Input-Output Operations To avoid deadlock when processes share and lock files, have each process lock and unlock records and files in the same sequence. Note. If a process is protected by TMF, all locks are retained (despite unlocking statements) until the current transaction is completed or backed out. Setting Time Limits on Input-Output Operations Even when each program that shares files carefully arranges to lock files and records in the same order, a newly introduced program or a change to an existing program can fail to conform and cause deadlock. In HP COBOL, you can prevent this deadlock by using the TIME LIMITS phrase with the statements OPEN, START, READ, and LOCKFILE. Without the TIME LIMITS phrase, if your process attempts to open a file, establish a starting position in a file, read a file, or lock a file and that file or the necessary record in that file is already locked, the process suspends activity until the lock is removed. With the TIME LIMITS phrase, you can specify a time limit on the suspension. If the time expires before the inhibiting lock is removed, the file operation terminates with file status code “30” and GUARDIAN-ERR special register value 40. The program can diagnose the failure of the file operation and either retry the operation or abandon the current group of operations to allow another process to complete its operations. Suppose you have a file declared by these entries: SELECT OAK-FILE ASSIGN TO "$OAK.ACORN.TREE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL FILE STATUS IS OAK-STATUS. FD 01 OAK-FILE LABEL RECORDS ARE OMITTED. OAK-RECORD. 02 ... Suppose that you open the file with this statement: OPEN INPUT OAK-FILE WITH TIME LIMITS SHARED. Suppose that your program includes a declaratives section such as: DECLARATIVES. OAK-FILE-USE-SECTION. USE AFTER STANDARD ERROR PROCEDURE ON OAK-FILE. OAK-DECL. IF OAK-STATUS = "30" AND GUARDIAN-ERR = 40 MOVE "Operation timed out on OAK file" TO REPORT MOVE TIME-OUT-CODE TO OAK-ERROR DISPLAY REPORT END-IF. END DECLARATIVES. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -39 Disk Input and Output Using Enscribe and Operating System Routines Suppose that you attempt to read the file OAK with a statement such as: READ OAK-FILE RECORD TIME LIMIT 5 AT END PERFORM END-OAK. IF OAK-ERROR = TIME-OUT-CODE ... When the read operation cannot be completed within 5 seconds, control passes to the USE procedure for the OAK file, which can adjust the program’s behavior appropriately. The USE procedure displays a diagnostic to the OUT file. The program could retry a certain number of times, or (if it is a server) report back to its requester that the read operation could not be completed, which is another way to handle a file that might be locked at the file or record level. Using Enscribe and Operating System Routines Enscribe routines are a subset of operating system routines that function collectively as the operating environment’s database record manager. All processes use Enscribe routines to interact with records in disk files in the database. HP COBOL run-time routines that perform input-output operations do so by calling Enscribe routines, but they also handle HP COBOL-related processing that Enscribe does not, such as declaratives and file status code data items. An HP COBOL program can call an Enscribe or other operating system routine with the ENTER statement. Some Enscribe and operating system routines are not safe to use from an HP COBOL program; others are. Caution. Generally, it is not safe to mix HP COBOL input-output operations and direct calls to Enscribe input-output routines for the same open file. Although you can use HP COBOL statements to open, close, and checkpoint a file and also call Enscribe routines to perform operations that HP COBOL does not provide, calling Enscribe routines disables useful HP COBOL tools such as declaratives and file-status data items, causing corruption or loss of data, abnormal termination, and other failures. Although such calls might work in one RVU of the software, they are not guaranteed to work in subsequent RVUs. Topics: • • • • • • • Physical File Names Obtaining File Numbers and Other File Attributes Determining Whether Two COBOL File Names Specify the Same Physical File Purging a File From an HP COBOL Program Purging the Contents of a File From an HP COBOL Program Renaming a File From an HP COBOL Program Creating a File Having Alternate Keys From an HP COBOL Program HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -40 Disk Input and Output Physical File Names Physical File Names A physical file name is the file name by which the Enscribe disk file handling routines recognize a file (as opposed to the COBOL file name, which is also called the internal file name). In the non-CRE environment, Enscribe disk file handling routines demand file names in one of two rigid formats—one for local files and one for files on other nodes of the Expand network. They correspond to these HP COBOL declarations: 01 Enscribe-LOCAL-FILE-NAME. 03 VOLUME-SPECIFIER. 05 FILLER 05 VOLUME-NAME 03 SUBVOLUME-NAME 03 FILE-NAME 01 Enscribe-NETWORK-FILE-NAME. 03 SYSTEM-SPECIFIER. 05 FILLER 05 ONE-BYTE-SYSTEM-NUMBER 03 VOLUME-SPECIFIER. 05 VOLUME-NAME 03 SUBVOLUME-NAME 03 FILE-NAME PICTURE PICTURE PICTURE PICTURE X VALUE IS "$". X(7). X(8). X(8). PICTURE X VALUE IS "\". PICTURE X. PICTURE X(6). PICTURE X(8). PICTURE X(8). The data item ONE-BYTE-SYSTEM-NUMBER is a 1-byte integer whose value is in the range 0 through 254. Each node in an Expand network has a unique system name and a unique system number. The number and name of a node are established during system generation. Obtaining File Numbers and Other File Attributes When a process opens a file, Enscribe assigns the file a number that is unique within that process. File number zero is always set aside for $RECEIVE, regardless of whether a process opens it or not. The first other file that a process opens is assigned file number one. Enscribe always assigns the lowest available file number. After a process closes a file, the associated file number becomes available. Many Enscribe routines require file numbers instead of file names. Each of these routines returns a file number: • • HP COBOL routine COBOLFILEINFO or COBOL_FILE_INFO_ Enscribe routine FILE_GETINFO_ Each of the preceding routines can return other file attributes in addition to the file number; use the routine best suited to your needs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -41 Disk Input and Output Determining Whether Two COBOL File Names Specify the Same Physical File The HP COBOL routine COBOLFILEINFO or COBOL_FILE_INFO_ accepts a COBOL file name and returns: • • • The file number of the file The internal form of the file name associated with the file description The file-system error code of the last input-output operation attempted for that file For more information about the COBOLFILEINFO routine, see COBOLFILEINFO. For more information about the COBOL_FILE_INFO_ routine, see COBOL_FILE_INFO_. The FILE_GETINFO_ procedure can return more attributes than the HP COBOL routine COBOLFILEINFO can. For details, see the Guardian Procedure Calls Reference Manual. Determining Whether Two COBOL File Names Specify the Same Physical File Through programmer error or a TACL ASSIGN command, two COBOL file names in the same run unit can refer to the same physical file. This situation is not forbidden; in fact, it can be useful: you can develop a server by having the input come from a disk file and the output go to a printer, and then putting the server into production with both the input file and the output file assigned to $RECEIVE. Having two COBOL file names refer to the same physical file can also cause problems. If, for example, a program has two output files that are intended as two separate reports, and both are assigned to the same printer (not a spooler collector but the same mechanical device), then the program terminates abnormally. If both files have the exclusion mode SHARED, the lines of the two reports are interspersed on the paper. To enable your HP COBOL program to detect that two of its HP COBOL file names refer to the same external file, call operating system routine FILENAME_COMPARE_. FILENAME_COMPARE_ accepts two file names in internal form and returns a numeric value: Value Returned Meaning -1 The two internal file names do not refer to the same physical file. 0 The two internal file names refer to the same physical file. 1 The two internal file names refer to the same volume name, device name, or process name, but the remainder of the two file names do not match (such as two instances of the same spooler collector that specify different locations). A negative value other than -1 represents a file-system error number having the corresponding positive value; for example, if at least one of the parameters specifies an illegal file name, the value returned is -13. For more information about the FILENAME_COMPARE_ routine, see the Guardian Procedure Calls Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -42 Disk Input and Output Purging a File From an HP COBOL Program Purging a File From an HP COBOL Program The HP COBOL language provides no mechanism for deleting a file from the system directory; an HP COBOL program can purge a file only through an explicit call to the FILE_PURGE_ procedure. The file being purged must be closed. The FILE_PURGE_ procedure accepts the internal form of a file name as a parameter. To determine whether the purge operation was successful, call the HP COBOL routine COBOLFILEINFO with the file name as its parameter. COBOLFILEINFO returns an error value. If the purge operation was successful, the error value is zero. One common reason for a purge operation to fail is that the process’s accessor ID was not authorized to purge the file according to the security attributes of the file. Example 28-13. Purging a File From an HP COBOL Program WORKING-STORAGE SECTION. 01 FS-ERROR NATIVE-2 01 EXTERNAL-NAME PIC X(30). 01 INTERNAL-NAME. 03 VOL-NAME PIC X(8). 03 SUBVOL-NAME PIC X(8). 03 FILE-NAME PIC X(8). 01 PURGE-RESULT PIC S9(4) COMP. 88 PURGED-OK VALUE ZERO. ... PROCEDURE DIVISION. ... MOVE "$FIFTY.NIFTY.SHIFTY" TO EXTERNAL-NAME. MOVE "$FIFTY" TO VOL-NAME. MOVE "NIFTY" TO SUBVOL-NAME. MOVE "SHIFTY" TO FILE-NAME. ENTER "FILE_PURGE_" USING EXTERNAL-NAME (1:19) GIVING FS-ERROR. ENTER TAL "COBOLFILEINFO" USING INTERNAL-NAME PURGE-RESULT IF PURGED-OK ... If the reason you want to purge a file is that you want to have a temporary file for the duration of a single process and the name of the file is not of any real interest, use the special name #TEMP in the ASSIGN clause of the file-control entry at compilation time (or in a TACL ASSIGN command at execution time). When you specify #TEMP, the run-time routines create a temporary file on the process’s default volume. You can also create a temporary file on a specific volume by just assigning the HP COBOL file to the volume name, specifying spaces. It is often useful to locate a temporary file on a different volume to improve performance. The TACL ASSIGN command enables you to allocate specific primary and secondary extents for temporary and permanent disk files that a process is to create. If you do not specify extents, the run-time routines use a primary extent size of 4 disk pages (each page holds 2048 bytes) and a secondary extent size of 20 disk pages. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -43 Disk Input and Output Purging the Contents of a File From an HP COBOL Program Unless the CLEARONPURGE flag is set for a file, purging the file does not obliterate the data on the disk. If security is a major consideration, use one of these to set the CLEARONPURGE flag: • • The FUP SECURE command with the CLEARONPURGE option The SETMODE routine For more information about the FILE_PURGE_ and SETMODE routines, see the Guardian Procedure Calls Reference Manual. Purging the Contents of a File From an HP COBOL Program It is sometimes convenient to purge the contents of a file but keep the file in the directory for later use. The HP COBOL run-time routines do this when you open a file for output (if you have read access to the file). You might choose (for security) to purge the contents of a temporary work file when you have finished working with it, because merely purging the file does not erase the data from the disk. The HP COBOL library routine COBOL_CONTROL_ is a multipurpose routine that calls the operating system routine CONTROL, and whose function is determined by an operation code. The operation code 20 enables a process to purge only the contents of a file if the process has write access to the file. The process can even purge the data from a temporary file whose name was assigned by Enscribe because you specified only a volume name or assigned it to #TEMP. The COBOL_CONTROL_ routine call for purging data requires two parameters. The first parameter is the file-name described in the SELECT clause of the file-control entry for the file; the second is the number 20 (which causes the file system to purge the data in the file). Example: ENTER "COBOL_CONTROL_" USING MYFILE 20 For more information about the CONTROL routine, see the Guardian Procedure Calls Reference Manual. Renaming a File From an HP COBOL Program The FILE_RENAME_ procedure enables a process to rename a closed disk file, provided the process has purge access to the file. If the file is a temporary file, the process can call FILE_RENAME_ to make the file a permanent file. For more information about the RENAME or FILE_RENAME_ routine, see the Guardian Procedure Calls Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -44 Disk Input and Output Creating a File Having Alternate Keys From an HP COBOL Program Creating a File Having Alternate Keys From an HP COBOL Program At times, it is necessary within an HP COBOL process to create and operate on a file that has alternate keys. Suppose the file must be named and built during execution. The only way to do this is through a series of steps involving a few Enscribe routines: 1. Declare the records of the file in a file description entry. 2. Use the FILE_CREATELIST_ procedure to create the primary file in conformance with the specification in the file-control entry and the file description. 3. Use the FILE_CREATELIST_ procedure to create the alternate-key file in conformance with the specification of the keys in the file-control entry and the record description for the file. 4. Open the loadfile and use it. Suppose you have a server process that must create a private, indexed file having one alternate key. Note. This explanation does not elaborate all the data definitions and all the code necessary to manage the creation of an indexed file with an alternate key. Only the significant declarations and code are shown. In some cases, the code mentions data items that are presumed to have been defined and given values by statements not shown. The file-control entry and file description entry are: SELECT T-file-1 ASSIGN TO "ISFILE" ORGANIZATION IS INDEXED RECORD KEY IS K1 ALTERNATE RECORD KEY IS AK1 ACCESS MODE IS DYNAMIC FILE STATUS IS Fs ... FD T-file-1 LABEL RECORDS OMITTED. 01 T-rec-1. 02 K1. 03 K1-fp PIC XX. 03 FILLER PIC X. 02 Ak1. 03 Fp PIC X(5). 03 Lp PIC X(5). 02 FILLER PIC X(20). 02 rw-flag PIC X(4). 02 T-rec-no PIC 999. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -45 Disk Input and Output Creating a File Having Alternate Keys From an HP COBOL Program Declare parameters to pass to the FILE_CREATELIST_ procedure to create the indexed file (see the Guardian Procedure Calls Reference Manual for details on these parameters): • • • The file type (key-sequenced) The record length The prime record key parameters (key length = 16, key offset = 0, and index block length = default): 01 01 01 01 01 01 Create-error Error-item File-name File-name-len Fs Fp-chg NATIVE-2. NATIVE-2. PIC X(128) VALUE "ISFILE". PIC 999 COMP VALUE 6. PIC XX. PIC S9 COMP VALUE -1. 01 Item-list. 02 File-type 02 Lrl 02 Key-offset 02 Key-length 02 Number-keys 02 Key-descriptor 02 Num-ak-files 02 Ak-file-name-len 02 Ak-file-name 01 Number-of-items 01 01 01 01 Values-array. 02 File-type-v 02 Lrl-v 02 Key-offset-v 02 Key-length-v 02 Number-keys-v 02 Key-descriptor-v. 03 A-key-spec 03 A-key-len 03 A-key-off 03 A-key-filenum 03 A-null-value 03 A-attributes 02 Num-ak-files-v 02 Ak-file-name-len-v 02 Ak-file-name-v Values-length Akf-rec-len Akf-key-len 01 01 01 01 01 01 Create-error Error-item File-name File-name-len Fs Fp-chg NATIVE-2 NATIVE-2 NATIVE-2 NATIVE-2 NATIVE-2 NATIVE-2 NATIVE-2 NATIVE-2 NATIVE-2 VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE 41. 43. 45. 46. 100. 101. 102. 103. 104. NATIVE-2 VALUE 9. NATIVE-2 VALUE 3. NATIVE-2. NATIVE-2 VALUE 0. NATIVE-2. NATIVE-2 VALUE 1. PIC XX VALUE "AA". NATIVE-2. NATIVE-2. NATIVE-2 VALUE 0. NATIVE-2 VALUE 0. NATIVE-2 VALUE H"4000". NATIVE-2 VALUE 1. NATIVE-2 VALUE 7. PIC X(8) VALUE "ISFILEA ". NATIVE-2. NATIVE-2. NATIVE-2. NATIVE-2. NATIVE-2. PIC X(128) VALUE "ISFILE". PIC 999 COMP VALUE 6. PIC XX. PIC S9 COMP VALUE -1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -46 Disk Input and Output Creating a File Having Alternate Keys From an HP COBOL Program Example 28-14. Dynamic File Assignment ... MOVE MOVE MOVE MOVE FUNCTION FUNCTION FUNCTION FUNCTION LENGTH LENGTH LENGTH LENGTH (T-rec-1) TO Lrl-v (K1) TO Key-length-v, A-key-off (AK1) TO A-key-len (Values-array) TO Values-length * Create the primary file ENTER "FILE_CREATELIST_" USING File-name, File-name-len, Item-list, Number-of-items, Values-array, Values-length, Error-item GIVING Create-error IF Create-error NOT = 0 DISPLAY "Creation failed with error ", Create-error, " in parameter " Error-item STOP RUN END-IF * Create the alternate key file * The key length has to be 2 greater than the real one COMPUTE Akf-key-len = 2 + A-Key-len * The record length has to be 5 greater than the real key length COMPUTE Akf-rec-len = 5 + A-Key-len ENTER "FILE_CREATE_" USING Ak-file-name-v, Ak-file-name-len-v, OMITTED, OMITTED, OMITTED, OMITTED, 3, OMITTED, Akf-rec-len, OMITTED, Akf-key-len, 0 GIVING Create-error IF Create-error NOT = 0 DISPLAY "AK creation failed with error ", Create-error, " in parameter " Error-item STOP RUN END-IF HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -47 Disk Input and Output Creating a File Having Alternate Keys From an HP COBOL Program HP COBOL Manual for TNS and TNS/R Programs —522555-006 28 -48 29 Terminal Input and Output Most interaction between users and an HP system is conducted through video display terminals. The HP COBOL language has no mechanisms for full-screen block inputoutput. On an HP system, a typical application uses Pathway/TS to write requester programs in SCREEN COBOL to handle terminal input and output and uses HP COBOL or TAL server programs to handle database input and output. Occasionally, an HP COBOL process must communicate with a terminal directly. For very small amounts of data transfer and for free-format collection and reporting of numeric values, such processes can use the ACCEPT and DISPLAY statements. Each ACCEPT or DISPLAY statement either specifies a mnemonic name of a device or defaults to the process’s IN or OUT file, respectively (only if the IN and OUT files are suitable for ACCEPT and DISPLAY statement use). If a process needs uninterrupted access to a terminal or wants to determine at run time which of several terminals to communicate with, the process must declare the terminal process as a sequential file and operate on it with the usual OPEN, READ, WRITE, and CLOSE statements. The system generation process includes operations to define each terminal attached to an HP system. Each terminal has a device name and a logical device number. The file system supports transfers from terminals in both page mode and conversational mode. Conversational mode is easy to use from an HP COBOL process, but page mode is awkward. The normal way to use page-mode input and output in conjunction with an HP COBOL process is to write a SCREEN COBOL requester program and have it communicate with an HP COBOL server process. Topics: • • • • • • • • Using ACCEPT and DISPLAY With a Terminal Using a Terminal as a File Prompting the Terminal Operator for Input Sharing a Terminal Getting Break Ownership Transferring Break Ownership Communicating With an Operator or Process Logging Program Activity Information to a Terminal HP COBOL Manual for TNS and TNS/R Programs —522555-006 29- 1 Terminal Input and Output Using ACCEPT and DISPLAY With a Terminal Using ACCEPT and DISPLAY With a Terminal ACCEPT and DISPLAY statements transfer small amounts of data between a device and a process. The device is not a file; it is neither mentioned in the HP COBOL program’s FILE-CONTROL paragraph nor described in the program’s File Section. Whenever a process executes an ACCEPT or DISPLAY statement, the HP COBOL run-time routines automatically open the device, perform the operation, and close the device. Any ACCEPT and DISPLAY statements that do not include a mnemonic name to specify a device interact with the standard input and output devices of their process, respectively. Topics: • • Guardian Environment OSS Environment Guardian Environment In the Guardian environment, each process has an IN file, an OUT file, and a home terminal file. You can specify these files in the RUN command, using the IN, OUT, and TERM run options or with the PARAM EXECUTION-LOG command (see Section 25, Executing and Debugging HP COBOL Programs). If you do not specify one or all of the files in the RUN command, the process inherits the corresponding file of the command interpreter that accepted the RUN command. If you want a process’s ACCEPT and DISPLAY statements to interact with a terminal other than that on which you issued the RUN command to start the process, you have two alternatives: • • Use the SPECIAL-NAMES paragraph to associate a mnemonic name with the other terminal and qualify the ACCEPT and DISPLAY statements with that name. Mention the other terminal in the RUN command IN and OUT options when you initiate the process. If a process needs to choose among several terminals for input or output, the use of the mnemonic name requires that all device assignments be established at compile time; therefore, several ACCEPT or DISPLAY statements, each associated with a fixed device, must be present in the program, and the process must choose the ACCEPT or DISPLAY to use. Example 29-1 shows the use of ACCEPT and DISPLAY statements with the IN file and the OUT file and with a terminal that is known to the file system as $TRM053. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29- 2 Terminal Input and Output Guardian Environment Example 29-1. ACCEPT and DISPLAY Statements With a Terminal IDENTIFICATION DIVISION. PROGRAM-ID. TERMINAL-ACCEPT-DISPLAY. AUTHOR. MO COBOL. DATE-WRITTEN. 29 FEBRUARY 1984. DATE-COMPILED. ****************************************************** * This program illustrates ACCEPT and DISPLAY with * * and without mnemonic names. * ****************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. SPECIAL-NAMES. FILE "$TRM053" IS OUT-THERE. DATA DIVISION. WORKING-STORAGE SECTION. 01 A-TEXT-LINE PICTURE X(30). PROCEDURE DIVISION. A. * Deliver a value to the default terminal (the OUT file) DISPLAY "Who's there?". * Get a line from the default terminal (the IN file) ACCEPT A-TEXT-LINE. * * Deliver the entered-line from the default terminal to OUT-THERE DISPLAY A-TEXT-LINE " is at the default terminal." UPON OUT-THERE. * Deliver a value to a specific terminal DISPLAY "Who's there?" UPON OUT-THERE. * Get a line from a specific terminal ACCEPT A-TEXT-LINE FROM OUT-THERE. * Deliver the entered-line from OUT-THERE DISPLAY A-TEXT-LINE " is at terminal $TRM053". STOP RUN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29- 3 Terminal Input and Output OSS Environment OSS Environment These are true in the OSS environment but not in the Guardian environment: • • • No prompt is given for an ACCEPT statement. If a DISPLAY statement includes mnemonic-name, it must be either the OSS pathname of a Guardian file or the name of an OSS text file. If an ACCEPT statement includes mnemonic-name, it must be the OSS pathname of a Guardian process or terminal. If mnemonic-name is an OSS device, a diagnostic is issued and the default input device (#IN) is used instead. Using a Terminal as a File All files that an HP COBOL process uses must be specified in the FILE-CONTROL paragraph and described in the File Section of the Data Division of the source program. As with any other file, the process must explicitly open the terminal file, perform its read and write operations, and close the file. It is always advisable to declare a terminal file to have variable-length records by including a RECORD CONTAINS or RECORD IS VARYING clause in the file description of the file. If the file is not declared to have variable-length records, the HP COBOL run-time routines expect each READ statement to receive a record of exactly the length declared (explicitly or implicitly) in the file description, and they raise a run-time error if too short a record is typed at the terminal. If a record of more than the declared number of characters is typed at the terminal, the run-time routine does not deliver the excess characters to the process. When an HP COBOL process opens a file assigned to a terminal, it establishes communication with that terminal. The default exclusion mode for terminals is SHARED. If a process is to have private use of a terminal, with no command interpreter assigned to the terminal, the OPEN statement should specify the exclusion mode EXCLUSIVE. Use the ASSIGN clause of the file-control entry for a given file to associate a COBOL file name with a device name or logical device number of a terminal. You can override this assignment at the start of a process’s execution by using the TACL command ASSIGN. Establish the assignment dynamically during process execution by specifying #DYNAMIC in the ASSIGN clause of the file-control entry and calling the COBOLASSIGN routine (in the non-CRE environment) or the COBOL_ASSIGN_ routines (in the CRE) to associate the terminal device name or logical device number with a COBOL file name. Example 29-2 shows the use of terminal $TRM053 as a file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29- 4 Terminal Input and Output Using a Terminal as a File Example 29-2. Using a Terminal as a File IDENTIFICATION DIVISION. PROGRAM-ID. TERMINAL-READ-WRITE. AUTHOR. BO COBOL. DATE-WRITTEN. 29 FEBRUARY 1984. DATE-COMPILED. ************************************************************* * This program illustrates the use of a terminal as a * * file * ************************************************************* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT A-TERM ASSIGN TO "$TRM053" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. DATA DIVISION. FILE SECTION. FD A-TERM RECORD CONTAINS 1 TO 79 CHARACTERS LABEL RECORDS ARE OMITTED. * Using 80 characters causes a blank line after * the WRITE 01 A-TEXT-RECORD PICTURE X(79). PROCEDURE DIVISION. A. * Open the terminal as a file, excluding other users. OPEN I-O A-TERM EXCLUSIVE. B. * * Read one 79-character record. If a CTRL/Y was entered, quit. READ A-TERM AT END GO TO HIT-EOF. * Insert response. MOVE "So what?" TO A-TEXT-RECORD. * Deliver response. WRITE A-TEXT-RECORD. * Loop. GO TO B. HIT-EOF. STOP RUN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29- 5 Terminal Input and Output Prompting the Terminal Operator for Input Prompting the Terminal Operator for Input This topic assumes that you are using the terminal as a file (see Using a Terminal as a File). HP COBOL has a useful extension that can be used with terminal input and output. The HP COBOL READ statement is extended to include a PROMPT phrase. If you want to enter a dialogue with a user at a terminal, just using alternate WRITE statements for prompts and READ statements to collect the reply causes the prompt to appear on one line of the screen and the reply to be collected from the next line. You can achieve a more natural effect of having the prompt and its reply appear on the same line by using the PROMPT phrase. When an HP COBOL process executes a READ statement that includes a PROMPT phrase, the HP COBOL run-time routine that performs terminal input and output first delivers the characters in the data item whose name appears in the PROMPT phrase to the terminal, leaving the terminal cursor at the next available character position. Next, the routine clears the file’s record area to spaces. When the terminal operator enters a sequence of zero or more characters, terminated by pressing Return, the routine delivers the sequence of characters into the record area and returns control to the process. Example 29-3. READ Statement With PROMPT Phrase (page 1 of 2) IDENTIFICATION DIVISION. PROGRAM-ID. TERMINAL-READ-WRITE. AUTHOR. FLO COBOL. DATE-WRITTEN. 29 FEBRUARY 1984. DATE-COMPILED. ************************************************************* * This program illustrates the use of READ PROMPT * * for a terminal file * ************************************************************* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT A-TERM ASSIGN TO "$TRM053" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29- 6 Terminal Input and Output Sharing a Terminal Example 29-3. READ Statement With PROMPT Phrase (page 2 of 2) DATA DIVISION. FILE SECTION. FD A-TERM RECORD CONTAINS 1 TO 79 CHARACTERS LABEL RECORDS ARE OMITTED. * Using 80 characters causes a blank line after the * WRITE. 01 A-TEXT-RECORD PICTURE X(79). WORKING-STORAGE SECTION. 01 TAUNT PIC X(17) VALUE "What do you want?". PROCEDURE DIVISION. A. * Open the terminal as a file, excluding other users. OPEN I-O A-TERM EXCLUSIVE. B. * Read one 79-character record. If a CTRL/Y was entered, * quit. READ A-TERM WITH PROMPT TAUNT AT END GO TO HIT-EOF. * Insert response. MOVE "So what?" TO A-TEXT-RECORD. * Deliver response. WRITE A-TEXT-RECORD. * Loop. GO TO B. HIT-EOF. STOP RUN. Sharing a Terminal For development, you normally use a terminal that is associated during system generation with a command interpreter (such as TACL). That command interpreter uses your terminal as its IN file, its OUT file, and its home terminal. Most terminals on a production system do not have command interpreters associated with them. Each production terminal is directly associated with a production process, either as a terminal running under the control of a Pathway/TS terminal control process (TCP) or as a terminal that can be accessed by a process. Topics: • • • Terminal Associated With a Command Interpreter Terminal Not Associated With a Command Interpreter Non-COBOL Modules HP COBOL Manual for TNS and TNS/R Programs —522555-006 29- 7 Terminal Input and Output Terminal Associated With a Command Interpreter Terminal Associated With a Command Interpreter When a command interpreter has a terminal open for its IN and OUT file, an HP COBOL process can open that terminal as a file only if it opens it for shared access (the default). It cannot open such a terminal for exclusive access, even if the command interpreter does not accept messages from or send messages to that terminal for the duration of the HP COBOL process’s execution. If you want an HP COBOL process to have exclusive use of a terminal, no command interpreter can have the terminal open. To free a terminal that is running TACL for use as a file by an HP COBOL program, enter the TACL command PAUSE. Terminal Not Associated With a Command Interpreter When a terminal is not connected to a command interpreter, an HP COBOL process can open it, read from it, write to it, or close it like any other file. See Using a Terminal as a File. Non-COBOL Modules If your program consists of modules written in different languages, the modules can share the standard files—the predefined files called “standard input,” “standard output,” and “standard log” (except that FORTRAN modules cannot share “standard log” because FORTRAN does not support it). The standard input, output, and log file can be a terminal. If you want to do mixed-language programming, compiling your program to run in the CRE is highly recommended. Although mixed-language programming is possible in the non-CRE environment, it is very limited because of incompatibilities between different languages’ run-time libraries. The CRE supports the languages HP C, HP COBOL, FORTRAN, Pascal, and TAL. For more information about the CRE in general and on mixed-language programs sharing standard files in particular, see the CRE Programmer’s Guide. Getting Break Ownership When you press Break on a terminal, the process that owns Break receives a system message on $RECEIVE. A process discovers that Break has been pressed by reading $RECEIVE. An HP COBOL process, lacking the ability to perform NOWAIT input and output directly, must open $RECEIVE with an OPEN statement with a TIME LIMITS phrase and then try to read $RECEIVE from time to time. If a READ statement fails because it timed out, Break was not pressed. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29- 8 Terminal Input and Output Transferring Break Ownership When a command interpreter starts a process, whether or not the process uses the command interpreter’s terminal for any input or output, the command interpreter retains ownership of Break unless another process explicitly obtains ownership of Break from the operating environment. All a process needs to do to obtain that ownership is: • • Open the terminal for I-O (to get a stable file number, because DISPLAY and ACCEPT open and close the terminal each time they are executed) Call the COBOL_SETMODE_ routine with: ° ° ° The file-name ° Zero as the second parameter The function code 11 The CPU, PIN (processor number, process number) of the process to receive ownership as the first parameter If you start a process from the command interpreter, and that process takes ownership of Break but does not return ownership before terminating, the command interpreter does not regain title to Break. You might have to get a system operator to stop and restart your command interpreter in order for it to regain Break ownership. Transferring Break Ownership For one process to pass ownership of Break to another process, the first process must determine the CPU and PIN of the second process. Then the first process can transfer Break ownership to the other process by calling the operating system routine SETMODE with the appropriate values for parameters 1 and 2 (see Getting Break Ownership). The most common reason to transfer Break ownership to another process is to return it to its previous owner after you have accessed it. If the process will return Break ownership to its previous owner after a time, another parameter must be included in the call to receive the 4-byte value of the restoration parameters. This enables the process to call SETMODE with the 4 bytes as parameters 1 and 2 when it surrenders the ownership of the Break, as Example 29-4 shows. Because the message that Break has been pressed is a system message, a nonprivileged process cannot directly transfer the message to another process. Some other protocol must be established between the two processes. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29- 9 Terminal Input and Output Communicating With an Operator or Process Example 29-4. Transferring Break Ownership WORKING-STORAGE SECTION. 01 FILE-NUMBER PIC S9(4). 01 PROCESS-HANDLE PIC X(20). 01 ERROR-NUMBER PIC S9(5) COMP. 01 PREV-BREAK-OWNER. 03 PREV-OWNER NATIVE-2. 03 PREV-ACCESS-MODE NATIVE-2. ... PROCEDURE DIVISION. ... OPEN I-O A-TERM. ENTER TAL "COBOLFILEINFO" USING A-TERM OMITTED OMITTED FILE-NUMBER. * Get ownership of Break, saving previous info. ENTER TAL "SETMODE" USING FILE-NUMBER, 11, 1, 1, PREV-BREAK-OWNER. ... ... { HP COBOL program now owns Break } ... * Restore Break ownership according to saved info. ENTER "COBOL_SETMODE_ " USING FILE-NUMBER, 11, PREV-OWNER, PREV-ACCESS-MODE. Communicating With an Operator or Process A running HP COBOL program can use the DISPLAY statement to write to the operator console (a write-only device). Likewise, a running HP COBOL program can use the DISPLAY statement to write characters to any terminal or printer and can use the ACCEPT statement to read characters from any terminal or process. When a process includes code from an HP COBOL program and that HP COBOL code reports a run-time error, it reports the error to the process’ home terminal. The home terminal for a process must be chosen with care. Run-time diagnostic messages can easily get lost if an unattended terminal is used for them. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29 -10 Terminal Input and Output Writing to a Console Topics: • • • • Writing to a Console Writing to a Terminal or Printer Reading From a Terminal or Process Reading and Writing Numeric Data Writing to a Console The system operator console terminal device on any HP system is named $0 (“dollar zero”). It can be a hard-copy device or the Operations and Service Processor (OSP). In either case, the system operator (any super group member) can redirect the messages to another device or disable the delivery of messages entirely. Minimize messages to the operator in both development programs and production programs. If your HP COBOL application needs to announce something to the system operator, it must either associate a mnemonic name with $0 and use DISPLAY statements to communicate with the operator (as Example 29-5 does) or assign a file to $0 in the Environment Division and use WRITE statements. Example 29-5. Using DISPLAY Statements to Write to a Console IDENTIFICATION DIVISION. PROGRAM-ID. TELL-THE-LOG. AUTHOR. KILROY COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1984. DATE-COMPILED. ********************************************************* * This program delivers a line to the system console. * ********************************************************* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. SPECIAL-NAMES. FILE "$0" IS RECORD-FOR-POSTERITY. DATA DIVISION. WORKING-STORAGE SECTION. 01 ANNOUNCEMENT PICTURE X(16) VALUE "Kilroy was here". PROCEDURE DIVISION. A. DISPLAY "Program TELL-THE-LOG: " ANNOUNCEMENT UPON RECORD-FOR-POSTERITY. STOP RUN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29 -11 Terminal Input and Output Writing to a Terminal or Printer Each console terminal device on your node has a unique name. The names of consoles other than the system operator console are determined by the system generation. A program can contain any number of mnemonic names, each associated with a terminal device. The syntax of the DISPLAY statement limits the name in the UPON phrase to be a mnemonic name. The mnemonic name cannot be a data item; therefore, if you have a message that must be displayed on several devices, you need one DISPLAY statement for each device. Writing to a Terminal or Printer When a process includes code from an HP COBOL program having a DISPLAY statement without a mnemonic name attached, the process delivers characters to its OUT file. If no OUT file was specified in the initiation of the process, the process inherits the OUT file of its parent (the command interpreter, if the process was initiated with a RUN command). If the name of the specified OUT file is all spaces, the characters are discarded. To display characters to device $DDD or printer $PPP that is not the OUT file of the process, use the qualified form of the DISPLAY statement; for example: DISPLAY "Hello" UPON MY-NAME-FOR-DOLLAR-DDD. The compiler accepts this form of the DISPLAY statement only if it has already encountered an entry in the SPECIAL-NAMES paragraph associating MY-NAME-FORDOLLAR-DDD with the device $DDD; for example: SPECIAL-NAMES. FILE "$DDD" IS MY-NAME-FOR-DOLLAR-DDD. Each time a DISPLAY statement in a process executes, the process opens the terminal or printer, transmits the characters, and closes the terminal or printer. Some other process could open the terminal or printer for exclusive use and hold it open, causing the next DISPLAY or ACCEPT statement that tries to reach it to get a “device in use” error. Reading From a Terminal or Process When a process includes code from an HP COBOL program having an ACCEPT statement without a mnemonic name attached, the process reads characters from its IN file; if no IN file was specified, the process reads characters from its home terminal. To read characters from terminal $TTT or process $QQQ that is not the IN file of the process, use the qualified form of the ACCEPT statement; for example: ACCEPT ADVICE FROM MY-NAME-FOR-DOLLAR-QQQ. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29 -12 Terminal Input and Output Reading and Writing Numeric Data The compiler accepts this form of the ACCEPT statement only if it has already encountered an entry in the SPECIAL-NAMES paragraph associating MY-NAME-FORDOLLAR-QQQ with some device or process; for example: SPECIAL-NAMES. FILE "$QQQ" IS MY-NAME-FOR-DOLLAR-QQQ. Each time an ACCEPT statement in a process executes, the process opens the terminal or process, collects the characters, and closes the terminal or process. Some other process could open the terminal or process for exclusive use and hold it open, causing the next ACCEPT or DISPLAY statement that tries to reach it to get a “device in use” error. Reading and Writing Numeric Data The ANSI standard is not very specific on the details of the behavior of ACCEPT. The ACCEPT statement, as implemented in HP COBOL, allows you some flexibility in entering numeric data that some other implementations do not. HP COBOL allows you to enter a sequence of characters that correspond to a numeric literal, such as would be legal in an HP COBOL source program. The ACCEPT runtime routine converts this numeric representation into an appropriate form for storage in the designated data item, only as if you had a MOVE statement that specified the numeric literal as its source and the data item as its destination. The DISPLAY statement is equally versatile, converting a stored data value to a convenient external format. In Example 29-6, both ACCEPT and DISPLAY handle signed and unsigned numeric, numeric edited, and computational items. Example 29-6. Reading and Writing Numeric Data (page 1 of 2) IDENTIFICATION DIVISION. PROGRAM-ID. FRIENDLY-ACCEPT. AUTHOR. KIT COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1984. DATE-COMPILED. ****************************************************** * This program shows the flexibility of the ACCEPT * * statement. * ****************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. SPECIAL-NAMES. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29 -13 Terminal Input and Output Logging Program Activity Information to a Terminal Example 29-6. Reading and Writing Numeric Data (page 2 of 2) DATA DIVISION. WORKING-STORAGE SECTION. 01 A PICTURE 99999. 01 B PICTURE 999V999. 01 C PICTURE S999V999. 01 D PICTURE 999.999. 01 E PICTURE 9999V9999 USAGE IS COMPUTATIONAL. 01 F PICTURE USAGE IS COMPUTATIONAL. PROCEDURE DIVISION. Z. ACCEPT A. DISPLAY ACCEPT B. DISPLAY ACCEPT C. DISPLAY ACCEPT D. DISPLAY ACCEPT E. DISPLAY ACCEPT F. DISPLAY STOP RUN. A. B. C. D. E. F. A record of the output of one execution of the program in Example 29-6 follows. Each ACCEPT statement interprets the characters entered at each prompt (?) the same way as it would interpret those characters as a numeric literal in a source program. Each DISPLAY statement converts the value of a data item to a character-string that represents a numeric value for display. ?-1234.5678 01234 ?-1234.5678 234.567 ?-1234.5678 -234.567 ?-1234.5678 234.567 ?-1234.5678 1234.5678 ?-1234.5678 -0001234.5678000 Logging Program Activity Information to a Terminal Whenever a process sends a message to the system operator console terminal device ($0), the operating environment can automatically duplicate the message to the standard log file, which can be a terminal. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29 -14 Terminal Input and Output Logging Program Activity Information to a Terminal If you use the DISPLAY statement to send messages to the console, and therefore to the standard log file terminal, you must associate a mnemonic name with $0 in the SPECIAL-NAMES paragraph. This association is established at compilation time. Each DISPLAY statement transmits characters to a single terminal or device. If you use the WRITE statement to send messages to the console, and therefore to the standard log file terminal, you can determine the assignment between the file and the device in any one of these ways: • • • During program compilation, through the SELECT clause of the FILE-CONTROL paragraph Before program execution, through the ASSIGN or ADD DEFINE command During program execution, with the COBOLASSIGN routine (in the non-CRE environment) or the COBOL_ASSIGN_ routine (in the CRE). If your program consists of modules written in different languages, the modules can share the standard log file terminal (except FORTRAN modules, because FORTRAN does not support a standard log file). If you want to do mixed-language programming, compiling your program to run in the CRE is highly recommended. Although mixed-language programming is possible in the non-CRE environment, it is very limited because of incompatibilities between different languages’ run-time libraries. The CRE supports the languages HP C, HP COBOL, FORTRAN, Pascal, and TAL. For more information about the CRE in general and on mixed-language programs sharing standard files in particular, see the CRE Programmer’s Guide. HP COBOL Manual for TNS and TNS/R Programs —522555-006 29 -15 Terminal Input and Output Logging Program Activity Information to a Terminal HP COBOL Manual for TNS and TNS/R Programs —522555-006 29 -16 30 Printer and Spooler Output There are two ways that a process can write a report to paper: it can write directly to a printer or it can write to a spooler collector. When a process writes directly to a printer, it has exclusive use of the printer from the time it opens the file until the time it closes the file. When a process writes to a spooler collector, the spooler collector accumulates the lines of the report on a disk and does not engage a printer until the process closes the file. Some installations insist that processes write only to a spooler, because this can even out the printer usage or speed up jobs that would be output bound if they had to wait for a slow printer. An installation can configure its spooler locations such that a printer is either accessible only to the spooler and never by other processes or accessible to other processes whenever the spooler is not using it. HP has no file structure that is strictly for printer files. To establish a COBOL file for use with a printer, declare it to have sequential organization and to be accessed sequentially. Topics: • • • • • • Using a Printer Directly Understanding Spoolers Using a Spooler Controlling Vertical Spacing in a Printed Report Formatting Pages of a Printed Report Logging Program Activity Information to a Printer Using a Printer Directly Each installation chooses names for its printers. To write to a printer, an HP COBOL program declares a file with sequential organization and sequential access and associates that file with the printer device name. The HP COBOL process tries to open the printer file with the open mode OUTPUT or EXTEND. If the printer is not available, the OPEN statement fails with file status code “30” and a run-time error. The HP COBOL run-time routines deliver a diagnostic message to the process’ home terminal. If no declarative procedure is available for the printer file, the process terminates. If a declarative procedure is available for the printer file, the declarative procedure can examine the special register, GUARDIAN-ERR, and take appropriate action. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30- 1 Printer and Spooler Output Understanding Spoolers GUARDIAN-ERR contains the file-system error number that specifies the reason the printer was not available. Typical values for GUARDIAN-ERR are 14 (device does not exist) and 12 (file in use). If the file is in use, the process can call the operating system routine DELAY to let some time pass and then try the open operation again. If the printer is available, the open operation succeeds, and the process can go ahead and write to the printer. By default, an HP COBOL program opens a printer file with exclusion mode EXCLUSIVE. All other processes that attempt to write to the printer are excluded until the process that has the printer open closes it. Understanding Spoolers The HP spooler is a set of processes that acts as an interface between the print devices of a system and the users and their application programs. A spooler receives output from a process and stores it on disk, queued for delivery to a print process. This unit of storage is called a job. Topics: • • Spooler Components Jobs For more information on spoolers, see the Spooler Programmer’s Guide. Spooler Components The spooler has these components: • • • • • Supervisor Process Collector Process Print Process SPOOLCOM PERUSE The two spooler components that you are most likely to use are SPOOLCOM and PERUSE. Unlike the supervisor, collectors, and print processes that run continuously and are named processes, SPOOLCOM and PERUSE are processes you start when you need one and they usually are not named. Both interact with the supervisor. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30- 2 Printer and Spooler Output Spooler Components Supervisor Process The supervisor process communicates with and monitors the other processes and decides when and where to print output. The supervisor is an HP product and is started and managed by the system manager. A system can have more than one spooler supervisor; this can be useful for systems with vast numbers of print jobs or systems with special reporting needs. If a system has only one supervisor, its name is usually $SPLS. Collector Process The collector process receives the output. Your spooler system has one or more collectors. Each installation chooses its own names, but typical process names for spooler collectors are $S and $C. Print Process Each print device accessible to a spooler has an associated print process that executes in coordination with the spooler supervisor. The print process provided by HP reads the records stored on disk and delivers them to its associated print device. An installation can provide its own print processes that read the stored records and perform other operations on them, such as performing a statistical analysis of data in the records or formatting the data for a special-purpose output device. SPOOLCOM SPOOLCOM is an HP product. It is a loadfile that can be started by an interactive user or a system operator. System operators, who are members of the super group, can do more with SPOOLCOM than application programmers can. As an application programmer running SPOOLCOM interactively, you can examine the job queue and the status of print devices and change attributes of jobs you own. A system operator running SPOOLCOM can examine the queue and the status of devices but can also create and initialize the other components of the spooler system and make changes to the attributes of any job in the spooler. For more information about SPOOLCOM, see the Spooler Programmer’s Guide. PERUSE HP provides a perusal program named PERUSE, with which you can control and monitor your jobs in the spooler. PERUSE is oriented more to the interactive user than to the system operator. When a member of the super group calls PERUSE, that user must handle individual jobs rather than groups of jobs, and PERUSE does not give that user the control over devices that SPOOLCOM does. Your installation can write its own perusal processes. For more information about PERUSE, see the Spooler Programmer’s Guide. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30- 3 Printer and Spooler Output Jobs Jobs A job is analogous to a file. When you write to the spooler, you are creating a job. The spooler assigns each job a number. It starts at 1 and advances by 1 up to a maximum (specified when the spooler was started), not to exceed 4095. When the spooler reaches the maximum job number, it starts over with 1. If the job number the spooler tries to use is currently being used, the spooler advances until it finds a job number that is not being used. Each job has an owner. When an application program opens the spooler collector for output, the created job is marked as owned by the user number of the application program. Unlike a file, a spooler job does not have four-fold security; only the individual owner (or a system operator in the super-group) can print, delete, or otherwise manipulate a job. Using SPOOLCOM, you can transfer ownership of a job to another user. If one spooler reroutes a job to another spooler on the same system or on a different system in an Expand network, the owner of the job on the second spooler is the same as the owner was on the first spooler (typically, the system operator; therefore, if your spooler reroutes your job to another spooler, you are no longer the owner of the job. Jobs have six primary attributes: • • • • • • Location State Number of Copies Priority Report Name Form Name Location A job’s location is the job’s logical destination. Its physical destination is governed by a print process. A job’s location name consists of a group name and a destination name. The format of a location name is: ns $ ns S . ns # ns group-name ns . ns location-name VST618.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 30- 4 Printer and Spooler Output Jobs Suppose your installation has 12 printers, of which 4 are stocked with narrow paper. Three of them are at the other end of the building (in room 145), and one is near your work place (in room 301). Suppose your spooler designates this group of printers as NARROW, and within that group designates the printers as RM145A, RM145B, RM145C, and RM301. If you do not care which narrow-paper printer your report is printed on, you can assign the output file to $S.#NARROW. The spooler directs the job to whichever of the four printers could finish it first. If you want the job printed on the nearby printer, assign the output file to $S.#NARROW.RM301. There are two ways that your system manager can configure the spooler to print jobs that have only a group name but no destination name specified: • • On the printer that can finish the job first On all printers in the group The latter configuration is called broadcast mode. If you specify a location that is unknown to the spooler, your job sits in the spooler until such a location is made known to the spooler or you or a system operator changes the job’s location with PERUSE or SPOOLCOM. You can send the job to a fictitious location and use PERUSE to examine the contents of a report before it is printed. If there is any problem with the report, you can delete it from the spooler, fix the program that produced the report, and re-create the report. If you do not specify a location, the spooler uses the location #DEFAULT. Each installation determines for itself the identity of the device or devices that compose the default group. State A job is always in one of four states: State Meaning OPEN A process is writing to the collector. READY The originating process has closed its file and the job is ready to be printed, but the device on which it is to print is not currently available or its location is not associated with a device. PRINT The job is being printed on the device associated with the job’s location. HOLD The job is awaiting disposition. If the job is in PRINT state, the spooler stops printing the job as soon as you request that the job be put into the HOLD state. You can put a job into the HOLD state with PERUSE or SPOOLCOM. PERUSE has a HOLD command; SPOOLCOM has a JOB command with a HOLD subcommand. By default, the spooler deletes a job as soon as it has printed it. If you want the spooler to put the job into the HOLD state after printing it instead, use the PERUSE command HOLDAFTER or the SPOOLCOM command JOB with the subcommand HOLDAFTER. You can issue the HOLDAFTER command for a job in any state. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30- 5 Printer and Spooler Output Jobs A job in the HOLD state remains in the spooler until you or a system operator changes the job’s state or deletes the job. Remember that the number of jobs the spooler can hold is limited, as is the amount of disk space available for the text of those jobs. Number of Copies The default number of copies is 1. If you want several copies of your report, specify a number of copies (a number in the range from 1 through 32,767). When the spooler finds an available device for the job, it prints that many copies before freeing the device for another job. Your installation might have rules limiting how many copies you may run or how many pages you may print with a single job; check with your operations staff. Priority A job’s priority determines when the job is printed in relation to other jobs queued for the same device. The default priority is 4. The system operator can configure each device known to the spooler to print jobs of the same priority in a first-come, firstserved order or in shorter-jobs-before-longer-jobs order. Report Name The spooler passes the report name to the print process. If your installation uses the print process supplied by HP, the system operator can configure it to either leave a blank page between jobs or print a header page. The header page displays the report name in banner-head letters on the first page of the job, along with the location name. In ordinary type at the bottom of the first page, the print process reports the date and time, the job number, and the form name of the job. A report name can have up to 16 characters. No character can be a hyphen. The default report name is your group name and user name. You can use PERUSE or SPOOLCOM to change the report name. If you are using a different print process, that print process can do anything with the report name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30- 6 Printer and Spooler Output Using a Spooler Form Name If a job must be printed on a specific form, give the job a form name. Each device known to the spooler can have a form name. If your installation prints invoices, you might specify INVOICE as the form name for a report. When the time comes to print the invoices, the operator loads the proper paper forms on the chosen device and sets the device’s form name to INVOICE. When both the location and form name of a spooler job match the location and form name of the device, the spooler prints the job. You probably cannot expect the operator to notice that a job is waiting for a form name to be associated with a device. Your facility might have a forms schedule for regularly scheduled jobs, but you would have to alert the operator for other spooler jobs that need special forms. A form name can have up to 16 characters. A form name must not: • • Start with a number or a space character Contain any special characters or embedded blanks The default form name is blank (that is, no form name). When a device has a nonblank form name associated with it, the spooler routes only jobs with the same form name to that device. When a device has no form name associated with it, the spooler can route any job with no form name to it. Using a Spooler There are two contexts in which you, as an HP COBOL application programmer, use a spooler: compilation and execution. When you compile an HP COBOL program and produce a listing, it can go to the spooler. When you execute an HP COBOL program, it can send output to the spooler. There are three levels of spooling. You interact with the spooler through the PERUSE and SPOOLCOM processes. Topics: • • • • Spooling Compiler Listings Spooling Program Output Using PERUSE Using SPOOLCOM HP COBOL Manual for TNS and TNS/R Programs —522555-006 30- 7 Printer and Spooler Output Spooling Compiler Listings Spooling Compiler Listings To send your compiler listing to a spooler, specify a spooler collector and location for your OUT file when you compile your HP COBOL program; for example: COBOL85 /IN WHIZBANG, OUT $S.#WIZZ/;SYNTAX The compiler uses level 3 spooling when the OUT file is a spooler collector (device subtype 31). Spooling Program Output For its output, an HP COBOL program can use any of: • • • Level-1 Spooling Level-2 Spooling Level-3 Spooling Level-1 Spooling Level-1 spooling uses the spooler collector as a simple output file: you assign the COBOL file name of the output file to a system name that is a spooler collector (with or without a location name) and operate on the file with the HP COBOL statements OPEN, WRITE, REWRITE, and CLOSE. The LINAGE clause and the ADVANCING phrase of the WRITE statement work as expected. All attributes of the spooler job except the location name assume their default values: single copy, priority 4, report name set to group name followed by user name, and no form name. Example 30-1. Level-1 Spooling SELECT SPOOLER-FILE ASSIGN TO "$S.#MYSTUF" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. ... FD SPOOLER-FILE RECORD CONTAINS 80 TO 132 CHARACTERS LABEL RECORDS ARE OMITTED. 01 SPOOLER-SHORT-LINE PIC X(80). 01 SPOOLER-LONG-LINE PIC X(132). ... PROCEDURE DIVISION. ... OPEN OUTPUT SPOOLER-FILE ... WRITE SPOOLER-SHORT-LINE ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 30- 8 Printer and Spooler Output Spooling Program Output Level-2 Spooling You use level-2 spooling the way you use level-1 spooling, except that instead of opening the output file with the OPEN statement, you open it with the routine COBOL85^SPECIAL^OPEN (in the non-CRE environment) or COBOL_SPECIAL_OPEN_ (in the CRE), giving the first parameter, open-type, the value 1, and either omitting the parameter level-3 or giving it the value 0. The other parameters of the COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ routine enable you can specify: • • • • • • • • • • • • • • • Exclusion mode Sync depth Whether a page-eject precedes the first page printed Location name Form name Report name Number of copies Page size Flags that set the job priority and the attributes HOLD and HOLDAFTER Owner Maximum number of lines Maximum number of pages Whether to create a regular or code-129 spooler file Whether a form feed is to be used to position the file at the top of a new page rather than using spacing when LINAGE is specified for the file An error return code For details, see COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_. The preferred way to apply a declarative to a file that is used for level-2 spooling is to explicitly name the file in a USE AFTER EXCEPTION statement. All ordinary HP COBOL file-manipulating statements then transfer control to the declarative if an exception arises. The statement ENTER “COBOL85^SPECIAL^OPEN” (in the nonCRE environment) or ENTER COBOL_SPECIAL_OPEN_ (in the CRE) does not transfer control if it encounters an exception, so include a GIVING phrase in the ENTER statement and then test the file status code data item after the ENTER statement executes. Example 30-2 uses level-2 spooling in the non-CRE environment. In the CRE, use COBOL_SPECIAL_OPEN_ instead of COBOL85^SPECIAL^OPEN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30- 9 Printer and Spooler Output Spooling Program Output Example 30-2. Level-2 Spooling SELECT SPOOLER-FILE ASSIGN TO "$S" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL FILE STATUS IS SPOOLER-FILE-STAT. ... FD SPOOLER-FILE RECORD IS VARYING FROM 80 TO 132 CHARACTERS. 01 SPOOLER-SHORT-LINE PIC X(80). 01 SPOOLER-LONG-LINE PIC X(132). WORKING-STORAGE SECTION. 01 SPOOLER-FILE-STAT PIC XX. 01 LOCATION-NAME PIC X(16) VALUE 01 REPORT-NAME PIC X(16) VALUE * Flag for HOLDAFTER (32), PRIORITY 2 01 FLAGS PIC S9(4) VALUE 01 ERROR-CODE PIC S9(4). ... PROCEDURE DIVISION. ... ENTER TAL "COBOL85^SPECIAL^OPEN" USING SPOOLER-FILE 1 OMITTED OMITTED OMITTED 0 LOCATION-NAME OMITTED REPORT-NAME OMITTED OMITTED FLAGS GIVING ERROR-CODE ... WRITE SPOOLER-SHORT-LINE ... "#MYSTUF". "PRIVATE PROPERTY". (+2 = 34) 34. Level-3 Spooling Level-3 spooling causes the compiler to block output and minimizes the number of interactions with the spooler. There are two ways to get level-3 spooling: • • The same way you get level-2 spooling, except that when you open the output file with the COBOL85^SPECIAL^OPEN or COBOL_SPECIAL_OPEN_ routine, you give the parameter level-3 a nonzero value. Instead of using HP COBOL output statements on the file, use ENTER statements to call the Guardian environment routines listed in Table 30-1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -10 Printer and Spooler Output Using PERUSE Table 30-1. Guardian Environment Routines for Level 3 Spooling Routine Action CLOSE Closes the spooler collector OPEN Opens the spooler collector SPOOLCONTROL Handles VFU channel skipping SPOOLCONTROLBUF Handles the loading of programmable VFU for the model 5220 printer SPOOLEND Signals the end of a spooler job and can change attributes before a new spooler job starts without closing and reopening the spooler collector SPOOLSETMODE Sets automatic perforation skipping, system spacing control, baud rate, form length, vertical tabs, automatic-answer or control-answer mode, horizontal pitch, prespacing or postspacing, get device status, or reset to configured values SPOOLSTART Establishes the level-3 buffer, location name, form name, report name, number of copies, page size, and attributes such as HOLD and PRIORITY SPOOLWRITE Writes text to the spooler For information about these routines, see the Spooler Programmer’s Guide. Using PERUSE If you direct a process’s output to a spooler location that is known to the spooler, the job prints as soon as the device associated with that location becomes available. If the location you chose is unknown to the spooler, the job sits in READY state until one of these occurs: • • • An operator (using SPOOLCOM) defines that location to the spooler. You or the operator changes the location attribute of the job to a known location. You or the operator deletes the job from the spooler. The HP perusal process PERUSE enables you to examine the contents of the job, change its attributes, or delete it from the spooler. To call PERUSE, run it like any other process: 103> PERUSE PERUSE introduces itself with a header. If any jobs in the spooler belong to you, PERUSE lists them. In Example 30-3, job 1171 is ready to be printed. It consists of three pages, one copy is to be printed, its priority is 4, its HOLDAFTER attribute is not set, its location is #EXCEP R01, and it belongs to DEVELOP.JAN. Job 2423 does have its HOLDAFTER attribute set. The underscore (_) is the PERUSE prompt. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -11 Printer and Spooler Output Using PERUSE Example 30-3. PERUSE Output PERUSE - T9101D20 - (8JUN92) JOB 1171 2423 STATE READY READY PAGES 3 4 COPIES 1 1 SYSTEM PRI 4 4 HOLD A \LEO LOCATION #EXCEP R01 #MURPHY REPORT DEVELOP JAN DEVELOP JAN _ Topics: • • • Current Job Current Position Common PERUSE Operations For more information about PERUSE, see the Spooler Programmer’s Guide. Current Job The current job is the job to which the spooler is currently devoting its attention. Almost all commands that you give to PERUSE apply only to the current job. You cannot tell the spooler to list job number 2423; you must establish job 2423 as the current job and then tell the spooler to list the current job. The current job is undefined when you first start the spooler and after a DELETE command executes. To define the current job, use the JOB command. Example Effect JOB 1171 Establishes job 1171 as the current job JOB * Establishes the job most recently added to the spooler (and owned by the current user) as the current job JOB #MURPHY Establishes the job most recently sent to location #MURPHY (and owned by the current user) as the current job If the first command you give to PERUSE is not a JOB command, any command except DELETE establishes the job most recently added to the spooler (and owned by the current user) as the current job. Current Position At any given time during your PERUSE session, the spooler has a current position within its current job, just as a file in an HP COBOL program has a current record position. If you press Return at the PERUSE prompt, PERUSE lists the next line of the job and advances its current position. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -12 Printer and Spooler Output Using PERUSE Common PERUSE Operations After you have established a current job, you can perform the operations such as those listed in Table 30-2 (all operations apply to the current job unless otherwise specified). Table 30-2 is not a complete list of PERUSE commands; for more information, see the Guardian User’s Guide. Table 30-2. PERUSE Operations and Commands (Partial List) Operation Command Set number of copies COPIES Set form name FORM Set location LOC Set report name REPORT Set priority PRI Put the job into the HOLD state HOLD or HOLD ON Remove the job from HOLD state HOLD OFF Set the HOLDAFTER attribute HOLDAFTER or HOLDAFTER ON Clear the HOLDAFTER attribute HOLDAFTER OFF List some or all of the current job at your screen or on a device or to another job LIST List last page of the job (this is often a summary, showing any errors) LIST L Set the current position as the first line of a chosen page in the job PAGE Display the page number and line number of the current position PAGE Find the next instance of a certain character-string in the job FIND Delete the job DELETE Give the job to a new owner OWNER Get information about PERUSE commands HELP Here are some examples of spooler commands that involve the current job and the current position. Suppose you have just started the spooler. The spooler always begins by listing all jobs in its queues that belong to you. Suppose that the list is: PERUSE - T9101D20 - (8JUN92) JOB 1171 2423 STATE READY READY PAGES 3 4 COPIES 1 1 SYSTEM PRI 4 4 HOLD A \LEO LOCATION #EXCEP R01 #MURPHY REPORT DEVELOP JAN DEVELOP JAN _ To establish job 1171 as the current job, you enter: _JOB 1171 HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -13 Printer and Spooler Output Using PERUSE Suppose that the last page of the listing contains a summary, and you want to check that first. You enter: _LIST L The last page of the listing appears on your terminal screen. If it looks acceptable, you can relocate the listing to a defined device by entering a command such as: _LOC #LP5 If the printer associated with #LP5 is not busy, your job starts printing there. As soon as the job is printed, the spooler deletes the job unless its HOLDAFTER attribute is set. If you want to browse through your job, use the function keys to list groups of lines. Function key n lists the next 2n lines, starting at the current position; for example, function key 1 lists the next 2 lines, function key 2 lists the next 4 lines, function key 3 lists the next 8 lines, and function key 6 lists the next 64 lines (approximately a page in a typical report). To find certain texts in your job, use the FIND command. Suppose you compile an HP COBOL program, sending its listing to a spooler location that is not associated with a device. The job remains in the spooler in a READY state. If you list the last page of the job (using the LIST L command), you can view the summary and see whether the compiler found any errors. If it did find errors, you can use the FIND command to track them down easily. If you have a job in the PRINT state and you suddenly remember that you wanted to make additional copies, you can issue a HOLDAFTER command to keep the spooler from automatically deleting the job at the end of the printing operation. If the spooler collects your HOLDAFTER command before it finishes listing the job, then after the job finishes printing, it goes into the HOLD state. You can then request that three more copies be sent to the same location: _COPIES 3 _HOLD OFF If you want a different banner on the additional copies, you can change the job’s report name before setting the HOLD state to OFF. If you want to list the three extras copies at a different location, you can use the LOC command to change the location before setting the HOLD state to OFF. If your current job is 300 pages, and you want to print 5 copies of pages 150 through 159 at the printer associated with location #LP2.A, you can issue the commands: _LIST /OUT $S.#ABBREV/ 150/159 C _JOB #ABBREV _COPIES 5 _LOC #LP2.A This creates a new spooler job with the location ABBREV, containing only the chosen pages. The letter C in the LIST command transmits all CONTROL and SETMODE commands embedded in the job to the new job. Without C, the pagination of the new job does not match that of the old. The JOB command makes the job most recently sent to #ABBREV the current job. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -14 Printer and Spooler Output Using SPOOLCOM If you have a job in the HOLD or READY state, you can delete it by making it the current job and issuing the DELETE command. Using SPOOLCOM Although most of your interaction with the spooler is likely to be through PERUSE or another perusal process, there are a few things you might want to do for which SPOOLCOM can be more helpful than PERUSE. The main value of SPOOLCOM is that it shows you the date each job was created, and it also enables you to perform operations on groups of jobs. SPOOLCOM is intended primarily for system operators (members of the super group). These users have privileged access to the system. If you do not have privileged access, SPOOLCOM restricts the variety and complexity of operations available to you. SPOOLCOM does have the ability to accept commands on the (implicit) RUN command line and to accept commands from an IN file specified as a RUN option, but the way you are most likely to use SPOOLCOM is run it like any other process: 104> SPOOLCOM SPOOLCOM introduces itself with this header: SPOOLCOM - T9101C00 - (15JUL87) ) SYSTEM \LEO The right parenthesis is the SPOOLCOM prompt. Table 30-3 lists some of the commands available to you, but it is not a complete list of SPOOLCOM commands. For more information, see the Guardian User’s Guide. Table 30-3. SPOOLCOM Operations and Commands (Partial List) (page 1 of 2) Operation Command Report the status of a particular collector or all collectors COLLECT Report the state of a device in the spooler system DEV Skip pages on a report that a particular device is printing DEV Restart a device that has been stopped by a device error DEV Escape from SPOOLCOM EXIT or Control-Y Show proper syntax of all SPOOLCOM commands HELP Operate on one or more of your jobs in the spooler, such as reporting their status, changing their attributes or ownership, deleting them, starting them (shifting them from HOLD state to READY state), and so on JOB Report the status of one or more locations (including their destinations) LOC Report a cross-reference list of locations, devices, and print processes LOC HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -15 Printer and Spooler Output Using SPOOLCOM Table 30-3. SPOOLCOM Operations and Commands (Partial List) (page 2 of 2) Operation Command Specify a spooler supervisor with which SPOOLCOM is to communicate OPEN Report the status of the spooler’s print processes PRINT Report the status of the spooler SPOOLER The subcommands most useful to the application programmer are: • • JOB DEV JOB The SPOOLCOM command JOB is very powerful and flexible. Suppose that you are user 5,40, and you give the command: ) JOB (OWNER 5,40) You get a report like this: JOB 1203 1595 1671 1672 1737 1739 1779 2423 STATE HOLD READY HOLD PRINT READY HOLD HOLD READY FLAGS 4 A 4 A 4 A 4 A 4 4 4 4 A OWNER 5,40 5,40 5,40 5,40 5,40 5,40 5,40 5,40 TIME 01/28 01/20 12/15 12/15 01/28 01/11 01/28 01/20 COPY 1 1 1 1 1 1 1 1 PAGE 4 59 1 1 8 1 1 4 REPORT DEVELOP DEVELOP DEVELOP DEVELOP DEVELOP DEVELOP DEVELOP DEVELOP QUINN QUINN QUINN QUINN QUINN QUINN QUINN QUINN LOCATION #ANON #ANON #LP3 #LP3 #ANON #HT #HT #MURPHY This is much like the report that PERUSE gives you at the beginning of its execution, except that you have to ask for jobs belonging to user 5,40, or SPOOLCOM lists all its jobs, not only yours. Suppose that you want to delete the two jobs belonging to you that have been around since December 15 (jobs 1671 and 1672). In PERUSE, you must establish 1671 as the current job, delete it, establish 1672 as the current job, and delete it. With SPOOLCOM you can give the command: JOB (OWNER 5,40, DATE FROM DEC 15 1988 THRU DEC 15 1996) SPOOLCOM reports only your jobs created on that date. When you are certain that the jobs of 12/15 are the right ones, you can delete the chosen jobs with the command: JOB (OWNER, DATE FROM DEC 15 1988 THRU DEC 15 1996), DELETE! If you do not use the exclamation mark (!) SPOOLCOM asks you about each job. If you use OWNER without a user ID, SPOOLCOM uses the creator accessor ID (your user ID). HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -16 Printer and Spooler Output Using SPOOLCOM For two jobs, SPOOLCOM requires more keystrokes than PERUSE, but suppose you wanted to delete all your jobs created on or before January 11. The SPOOLCOM command for that is: JOB (OWNER, DATE THRU JAN 11 1997), DELETE! Similarly, you can delete all jobs whose current location is #ANON by using the command: JOB (OWNER, LOC #ANON), DELETE! You can delete all jobs whose current state is HOLD by using the command: JOB (OWNER, STATE HOLD), DELETE! If you want the spooler to print one copy each job in a certain set but direct them to another user at another spooler location, and delete those jobs after they are printed, you can give the command: JOB (OWNER, LOC #ANON), HOLD, REPORT DEVELOP LEE, HOLDAFTER OFF, LOC #PRT.A, START DEV The SPOOLCOM command DEV is useful for discovering what devices are configured for your spooler, and for skipping pages on a spooler job. If you give SPOOLCOM a simple DEV command with no parameters, you get a report like this: DEVICE $LP1 $LP2 $SPECL.#TYPE1 $SPECL.#TYPE2 \ARIES.$S \VIRGO.$S STATE JOB 159 WAITING WAITING WAITING WAITING WAITING FLAGS H ET H !T H ! H H PROC $SPLP $SPLP $SPLP $SPLP $SPLX $SPLX FORM RED This report shows: • • • • Two print devices, $LP1 (which is printing job 159) and $LP2 (which is free, but has a form name established, so the spooler routes only jobs with the form name RED to $LP2) Two print processes, $SPLP and $SPLX A device named $SPECL that apparently performs at least two distinct services (selected by the specification #TYPE1 or #TYPE2, which the $SPECL process obtains from its open message), which is free The spooler is configured to enable you to send jobs to spooler collectors on two other systems—\ARIES and \VIRGO, which are free. Suppose you have a 100-page report in the spooler and you want to print its last 3 pages on $LP1. First, use either PERUSE or the SPOOLCOM JOB command to get the job printing on $LP1. Then use this form of the DEV command: DEV $LP1, SKIPTO 98 HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -17 Printer and Spooler Output Controlling Vertical Spacing in a Printed Report This command tells the spooler to skip forward to page 98 of the job. The skipping capability is related to the device, not to the job. Skipping capability is useful is when the printer has jammed or the ribbon failed and ruined part of your listing. If the spooler delivered 56 pages of the job, but the pages from 50 onward are not usable, the job’s owner (or the system operator) can take the printer offline, fix the mechanical problem, put the printer back online, and issue the SPOOLCOM command: DEV $LP1, SKIPTO 49 For the full syntax of the JOB and DEV commands, see the Guardian User’s Guide. You can often get the information you need from SPOOLCOM command HELP; for example, this command gives the syntax and capabilities of the JOB command: HELP JOB Controlling Vertical Spacing in a Printed Report When you write to a printer or to a spooler, you can transmit not only data but also control information. Control information skips numbers of lines or skips to VFU channels. Some printers supplied by HP use a punched paper tape to control vertical formatting; others use an electronic device to perform that function. The control information is not embedded in each print line but is transmitted separately from your program to the device or to the spooler collector. The spooler stores the information in a manner that enables it to generate the same image on paper as would have been generated if your program had been writing directly to a printer. You control vertical spacing in a report with the ADVANCING clause of the sequential form of the WRITE statement. Topics: • • • • Skipping Lines Overprinting Lines Skipping to a Printer Control Tape Channel Punch Skipping to a New Page If you do not use an ADVANCING clause, the WRITE statement behaves as if it contained the clause AFTER ADVANCING 1 LINE; that is, the printer prints the record in the WRITE statement after advancing one record. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -18 Printer and Spooler Output Skipping Lines Skipping Lines To leave a blank line in your report before printing the record DETAIL-X, use this form of the WRITE statement: WRITE DETAIL-X AFTER ADVANCING 2 LINES To print the record DETAIL-Y and then leave a blank line, use this form of the WRITE statement: WRITE DETAIL-Y BEFORE ADVANCING 1 LINE Do not follow the preceding statement with another WRITE AFTER statement, or you will not get a blank line. Overprinting Lines To overprint the record named HEADER-X for emphasis, print it three times on the same line: WRITE HEADER-X WRITE HEADER-X AFTER ADVANCING 0 LINES WRITE HEADER-X AFTER ADVANCING 0 LINES This sequence also causes overprinting: WRITE HEADER-X AFTER ADVANCING 0 LINES WRITE HEADER-X BEFORE ADVANCING 0 LINES To underline a line, print a string of underscore characters over it. Skipping to a Printer Control Tape Channel Punch If you are writing to a printer that has a VFU control feature, handled either by punched paper tape or an electronic equivalent, you can specify that the printer is to advance to a certain vertical position before (or after) the record delivered by the WRITE statement is written on the paper. To do this, you must: • • • Know what channels are defined for the printer Use the SPECIAL-NAMES paragraph of the Environment Division to associate your own mnemonic name with the channel you plan to use Use a BEFORE or AFTER ADVANCING phrase having that mnemonic name So, if you have a printer on which a skip to channel 6 puts you at line 50 of a page, your program must specify something like: SPECIAL-NAMES. CHANNEL-6 IS CH-6. Then the WRITE statement to print the contents of record SUBTOTAL-Z on line 50 of the current page is: WRITE SUBTOTAL-Z AFTER ADVANCING CH-6 HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -19 Printer and Spooler Output Skipping to a New Page Skipping to a New Page To have your program deliver a print line to the top of a new page, include an AFTER ADVANCING PAGE phrase in the WRITE statement. If you want the program to deliver a print line, then skip to the top of a page, include a BEFORE ADVANCING PAGE phrase in the WRITE statement. Formatting Pages of a Printed Report By using the LINAGE clause in the file description of a report file and by including the AT END-OF-PAGE phrase in each WRITE statement that adds lines to the report, you can produce attractive reports with little effort. This technique requires you to use a bit of structured programming. The idea behind the LINAGE clause is that each page of the report has a top-margin area and a bottom-margin area, where the program writes no characters, and a body area, where the program does write characters. The body area ends with a footing area, made up of zero or more lines, where the program can write when it detects that the remainder of the body area is full. A typical use of this is for subtotals and totals for columns of data in the remainder of the body. Figure 30-1. LINAGE Clause Layout Top Margin Top Body (Includes Footing) Body Footing Bottom Bottom Margin VST708.vsd A standard 11-inch page printed at 6 lines per inch can accommodate 66 lines. You could establish 3 blank lines at the top, 3 blank lines at the bottom, and 60 lines of body between them. If you establish a footing line at 55, then the end-of-page condition arises after line 54 is written. If you want a one-line footing, use: FOOTING AT 66 HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -20 Printer and Spooler Output Formatting Pages of a Printed Report This file description illustrates the LINAGE clause for this type of page: FD SHOW-LINAGE LABEL RECORDS ARE OMITTED LINAGE IS 60 LINES WITH FOOTING AT 55 LINES AT TOP 3 LINES AT BOTTOM 3. One tenet of structured programming is that there be one WRITE procedure for each output file; the program builds the line for delivery and then performs the write procedure. This situation is a perfect basis for using the LINAGE clause. If your code writes each text line before advancing one line, you can use AT END-OFPAGE phrase to detect that the program has already written the last line in the body of the report page. If the page needs subtotals or column footings, you can specify a number of footing lines in the LINAGE clause. This action causes the end-of-page condition to arise when the process attempts to write into the footing area. You can then use an AT END-OF-PAGE phrase in the main WRITE statement and specify that when the end-of-page condition arises, a footing-area procedure is to be performed. Example 30-4 illustrates this technique. Example 30-4. END-OF-PAGE Phrase WRITE-PROCEDURE SECTION. ... WRITE SHOW-LINAGE-REC BEFORE ADVANCING 1 AT END-OF-PAGE PERFORM DO-FOOTING. ... DO-FOOTING. MOVE SUMMATION-LINES TO SHOW-LINAGE-REC. WRITE SHOW-LINAGE-REC BEFORE ADVANCING 2. PERFORM COLLECT-SUBTOTALS-TO-PRINT. WRITE SHOW-LINAGE-REC BEFORE ADVANCING PAGE. If you have trouble tracing the interactions of BEFORE phrases, AFTER phrases, numbers of lines to advance, page advances, and channel skips, you can always discover exactly what printer control commands are being used by following this procedure: 1. Direct your output to a spooler collector with a fictitious location. 2. Use the PERUSE command LIST to specify that the lines for at least two pages be listed to a printer or to the spooler collector in octal, showing all control codes: LIST /OUT $S.#LPF/ 1/2 O C This step lists each print line, each SETMODE operation, and each CONTROL operation. 3. See the Spooler Programmer’s Guide to identify the codes in the SETMODE and CONTROL operations. HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -21 Printer and Spooler Output Logging Program Activity Information to a Printer Logging Program Activity Information to a Printer To record a log of program activity to a printer, you can use either of these statements: • • DISPLAY WRITE (usually preferable) DISPLAY If you use the DISPLAY statement to send messages to a printer for shared access, you must associate a mnemonic name with the printer device name (such as $LP) in the SPECIAL-NAMES paragraph. This association is established at compilation time. Each DISPLAY statement transmits characters to a single device—there is no mechanism for changing the destination of a DISPLAY statement. Every time your process executes a DISPLAY statement, it must open the printer, write one line of characters, and close the printer. The printer is then available to other processes until the next time your process executes a DISPLAY statement. You cannot use the DISPLAY statement to deliver characters to a spooler. In the OSS environment, if a DISPLAY statement includes mnemonic-name, it must be either the OSS pathname of a Guardian file or the name of an OSS text file. WRITE If you use the WRITE statement to send messages to a printer, you can determine the assignment between the file and the device: • • • At compilation through the SELECT clause of the FILE-CONTROL paragraph At the beginning of execution with the TACL command ASSIGN or ADD DEFINE (in the Guardian environment only) During execution through the invocation of the routine COBOLASSIGN (in the nonCRE environment) or the routine COBOL_ASSIGN_ (in the CRE) The WRITE statement has these advantages over the DISPLAY statement: • • • • If there are several printers and the one you expected to use is busy, you can redirect the file to another printer. You can open the file for exclusive access (the default exclusion mode for printers) and be certain that no other process can send characters to the device while you are using it. You can recover from input-output errors by using declaratives. You can use the PARAM PRINTER-CONTROL command to handle the condition of the printer’s being out of paper (in the Guardian environment only). HP COBOL Manual for TNS and TNS/R Programs —522555-006 30 -22 31 Process Initiation, Communication, and Management On a NonStop system, a process is a running program. More specifically, it is the unique executing entity created when someone runs object code from a loadfile in one of these ways: • • • By entering an explicit RUN command (for example, RUN COBOL85) By entering an implicit RUN command (for example, COBOL85) By calling the PROCESS_CREATE_ procedure from another process If a user runs two separate programs, the operating environment creates two processes. The operating environment also creates two processes if the user runs two instances of the same program concurrently, or if two users run the same program concurrently. Physically, each process consists of at least: • • • A shareable, unmodifiable code area containing instructions and constants An exclusive, modifiable data area called a stack An exclusive entry in the process control block (PCB), a system table that uniquely defines the process within the system This arrangement permits two users of the same loadfile to use only one code area. Although two processes can share a code area, each process has its own data area and PCB. Although several processes in a particular processor module can share resources and attempt to run, only one process actually executes in a given processor module at a given instant. Actual process execution requires the use of the processor’s hardware registers, which are allocated to the running process by the operating environment. Before the running process yields the processor module to another process or to an interrupt handler, the operating environment saves information about the current executing environment in the process’s PCB entry. This strategy permits the operating environment to restore that environment when the process resumes execution. A process comes into being when the operating environment takes the code and data produced by compilation and either binding or linking and combines them with the memory and other resources of the computer system. The process exists until it requests termination (or is terminated) and surrenders its resources. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31- 1 Process Initiation, Communication, and Management Memory and Virtual Memory Figure 31-1. Process Creation, Execution, and Termination Program File Creation Execution Termination Process Process Process CPU Memory Tables Allocation Deallocation Resources PCB Table Entry Resident Memory Virtual Disk Space VST709.vsd Topics: • • • • Memory and Virtual Memory Initiating a Process From an HP COBOL Program Communicating With a Process Managing a Process Memory and Virtual Memory Memory is one resource consumed by a process. Each processor in an HP system has its own physical memory. Each processor in a system can have one to four increments of memory, and different processors in the same system can have different amounts of memory. The size of the increments depends on the type of processor—see the system description manual for your processor. The operating environment allows several processes to occupy different areas of physical memory concurrently. It manages these processes with a virtual memory mechanism. The active portions of a process reside in physical memory. The inactive portions remain in physical memory only as long as the number of active processes remains small. As the number of active processes grows, the inactive portions of processes tend to remain on disk in virtual memory. The unit of memory allocation is the page, whose size depends on the processor. See the system description manual for your processor. The virtual memory for process code consists of the loadfile. The virtual memory for process data consists of temporary disk storage, allocated at the time the process is created. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31- 2 Process Initiation, Communication, and Management Initiating a Process From an HP COBOL Program A process can modify its data but not its code; therefore, the operating environment can fetch code pages needed from disk but does not need to restore them to disk; the operating environment must rewrite data pages to disk when their physical memory is surrendered. The transfer of code and data pages between virtual memory on disk and physical memory is directed by the memory manager process of the operating environment with the help of the disk process. The performance of any process is affected by the amount of time that is spent managing memory instead of executing process instructions. For more information about memory and its management, see the system description manual for your processor. Initiating a Process From an HP COBOL Program Suppose you want to make your running HP COBOL program start a new process. This is different from having your HP COBOL program call another program with a CALL or ENTER statement—you want to cause an entirely independent process to execute asynchronously, perhaps on a different processor of the system or on a different HP system. If your program is a TNS program, use either the CREATEPROCESS routine (to start a low-PIN process) or the CLU_PROCESS_CREATE_ routine (to start a high-PIN process), If your program is a native program, use the CLU_PROCESS_CREATE_ routine. For information on the CLU_PROCESS_CREATE_ routine, see the CRE Programmer’s Guide. You can use the CREATEPROCESS routine in various ways: • • • To start several other processes To initiate a precompiled Enform query that returns records to your process from a database To activate the File Utility Program (FUP) and cause it to create a disk file and load data into it You call CREATEPROCESS with the ENTER verb and pass these items to it: • • • • • The name of the loadfile to be executed The name to be given to the process being created (optional) A code that specifies the process creation messages that are to be passed to the new process (optional) The priority at which the new process is to execute (optional) The processor on which the new process is to execute (optional) HP COBOL Manual for TNS and TNS/R Programs —522555-006 31- 3 Process Initiation, Communication, and Management • • Initiating a Process From an HP COBOL Program The number of memory pages the new process is to be allocated (optional) A numeric data item in which the operating environment is to return the process ID (name, processor number, and number of process within that processor) after the process is created (optional and of little use to the HP COBOL programmer) Note. If the process is running at a high PIN, the process ID that the operating environment returns is synthetic. For information about synthetic IDs of high-PIN processes, see the Guardian Application Conversion Guide. • A numeric data item in which the operating environment is to return a diagnostic code indicating the success of the process creation (optional, but recommended) For a syntax diagram of the CREATEPROCESS routine and complete descriptions of its parameters, see CREATEPROCESS. In Example 31-1, CREATEPROCESS initiates two independent processes. Note the mechanism used to decompose the 2-byte computational GIVING item into its two single-byte portions. Example 31-1. CREATEPROCESS Routine (page 1 of 3) ?SEARCH $SYSTEM.SYSTEM.COBOLLIB IDENTIFICATION DIVISION. PROGRAM-ID. LAUNCHER. AUTHOR. DANA COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1988. DATE-COMPILED. *********************************************************************** * This program initiates two other processes and then it terminates * *********************************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. DATA DIVISION. WORKING-STORAGE SECTION. 01 FAMILY. 05 P 05 COB-PROC-1 05 COB-PROC-2 05 PROC-NAME 05 SEND-STD-STARTUP-MSG 05 SU-ERROR 05 NEWPROCESS-ERR-LEFT 05 NEWPROCESS-ERR-RIGHT 05 PROC-FAILED 05 PROC-ID PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC X(21). X(21) VALUE "$WONDER.TWEEDLE.DUM". X(21) VALUE "$WONDER.TWEEDLE.DEE". X(6). S9(4) COMP VALUE 2. S9(4). 9(4). 9(4). X(16) VALUE "Failed to start ". S9(18) COMP. PROCEDURE DIVISION. AA-1. * Start $QUEEN process MOVE "$QUEEN" TO PROC-NAME. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31- 4 Process Initiation, Communication, and Management Initiating a Process From an HP COBOL Program Example 31-1. CREATEPROCESS Routine (page 2 of 3) * * * * * ENTER "CREATEPROCESS" USING COB-PROC-2 PROC-NAME Copy my IN, OUT, & default VOL/SUBVOL SEND-STD-STARTUP-MSG Default--same priority as me OMITTED Default--same processor as me OMITTED Default--use regular memory allocation OMITTED Report process ID of $QUEEN PROC-ID GIVING SU-ERROR. * Report any startup problem. IF SU-ERROR NOT = 0 MOVE COB-PROC-2 TO P PERFORM DISPLAY-STARTUP-FAILURE. DISPLAY "$QUEEN'S PROC ID IS " PROC-ID. * Start $ALICE process MOVE "$ALICE" TO PROC-NAME. * * * * * ENTER "CREATEPROCESS" USING COB-PROC-1 PROC-NAME Default--send all creation messages OMITTED Set explicit priority 43 Default--use same processor as me OMITTED Default--use regular memory allocation OMITTED Don't report process ID of $ALICE OMITTED GIVING SU-ERROR. * Report any startup problem. IF SU-ERROR NOT = 0 MOVE COB-PROC-1 TO P PERFORM DISPLAY-STARTUP-FAILURE. STOP RUN. DISPLAY-STARTUP-FAILURE. IF SU-ERROR = 1 DISPLAY PROC-FAILED " -- REQUIRED PARAMETER MISSING OR ILLEGAL" ELSE IF SU-ERROR = 2 DISPLAY PROC-FAILED " -- ILLEGAL loadfile NAME (" P ")" ELSE IF SU-ERROR = 3 DISPLAY PROC-FAILED " -- INFILE, OUTFILE, OR DEFAULT VOLUME" DISPLAY " NAME CANNOT BE CONVERTED TO NETWORK FORM" ELSE IF SU-ERROR < 256 DISPLAY PROC-FAILED " -- File management error #" SU-ERROR HP COBOL Manual for TNS and TNS/R Programs —522555-006 31- 5 Process Initiation, Communication, and Management Communicating With a Process Example 31-1. CREATEPROCESS Routine (page 3 of 3) ELSE * * -- Received raw error from NEWPROCESS system procedure. -- Decompose it into left byte and right byte values. DIVIDE SU-ERROR BY 256 GIVING NEWPROCESS-ERR-LEFT REMAINDER NEWPROCESS-ERR-RIGHT. DISPLAY PROC-FAILED " -- NEWPROCESS error # = (" NEWPROCESS-ERR-LEFT "," NEWPROCESS-ERR-RIGHT ")" ... Communicating With a Process On an HP system, all processes communicate directly with one another through the message system. The basic mechanism for access to the message system is $RECEIVE. Topics: • • • • • • • $RECEIVE Process Names Example of Simple Interprocess Communication RECEIVE-CONTROL Paragraph At-End Condition Summary of $RECEIVE Rules Simple Server Example $RECEIVE $RECEIVE is like one end of a communications conduit. It is similar to a courier who brings you a message and can be dismissed or sent back with a reply. From the perspective of a process, $RECEIVE appears to be a sequential file. The syntax for communicating with $RECEIVE in an HP COBOL program is, therefore, based on the syntax for communicating with an ordinary HP COBOL sequential file. To receive a message from another process (including the operating environment), a process must read $RECEIVE. To reply to a message, a process must write to $RECEIVE. The operating environment delivers the reply to the originator of the message. The process does not need to determine where the message came from to reply to it. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31- 6 Process Initiation, Communication, and Management $RECEIVE As with any other read operation, a process waiting to receive a message on $RECEIVE waits until a message is delivered, the process is stopped, or a timeout occurs on the read operation. Before a process can receive a message, some process must have sent a message to it. To send a message, a process must have the name of the process that is to receive the message (see Process Names). The sending process opens a file having the same name as the receiving process (using an OPEN statement). Then the sending process can write to its file and cause the operating environment to deliver the message to the receiving process. The receiving process then can read the message on its $RECEIVE. If a process tries to open a nonexistent process, both the operating environment and the HP COBOL run-time routines issue error messages. If no declarative intercepts the error, the process terminates. The sender of a message specifies whether a reply is expected or not. An HP COBOL process uses a WRITE statement to send a message to which no reply is expected and a READ WITH PROMPT statement to send a message that requests a reply. The READ WITH PROMPT statement reads the reply to the message that is transmitted as the prompt. The READ WITH PROMPT statement lets you write a requester in HP COBOL, because it enables you to send a request to a server and await a reply from that server. For more information on READ WITH PROMPT, see PROMPT phrase. Topics: • • $RECEIVE as Separate Input and Output Files $RECEIVE as Input-Output File $RECEIVE as Separate Input and Output Files The most common way to use $RECEIVE is to open it in INPUT mode for one file, and in OUTPUT or EXTEND mode for one or more other files. Figure 31-2. $RECEIVE as Separate Input and Output Files Task Message through TASKS-IN Requester Server Reply Message through RESPONSE-OUT Reply Message through ERROR-MSG VST710.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 31- 7 Process Initiation, Communication, and Management $RECEIVE All files are assigned to $RECEIVE; however, when testing your system, you can assign all files to disk files and then reassign them to $RECEIVE when testing is completed. Example 31-2. Requester Code ... SELECT TRANSACTIONS ASSIGN TO "$BAL" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. ... FD * 01 01 TRANSACTIONS LABEL RECORDS ARE OMITTED Variable-length records RECORD CONTAINS 1 TO 8 CHARACTERS. BALANCE PICTURE 9(8). ERROR-ON-TASK. 05 ERROR-CODE PICTURE 9. 05 ERR-MSG PICTURE X(7). WORKING-STORAGE SECTION. 01 TRAN-REQUEST. 05 TRAN-CODE PICTURE 9. 05 TRAN-ACCOUNT-NUMBER PICTURE 9(6). ... PROCEDURE DIVISION. ... OPEN I-O TRANSACTIONS SYNCDEPTH 2. ... MOVE TASK-CODE TO TRAN-CODE. MOVE ACCOUNT-IN TO TRAN-ACCOUNT-NUMBER. READ TRANSACTIONS RECORD WITH PROMPT TRAN-REQUEST ... Example 31-3. Server Code (page 1 of 2) ... SELECT TASKS-IN ASSIGN TO "$RECEIVE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. SELECT RESPONSE-OUT ASSIGN TO "$RECEIVE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31- 8 Process Initiation, Communication, and Management $RECEIVE Example 31-3. Server Code (page 2 of 2) SELECT ERROR-MSG ASSIGN TO "$RECEIVE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. RECEIVE-CONTROL. TABLE OCCURS 20 TIMES SYNCDEPTH LIMIT IS 2 REPLY CONTAINS 8 CHARACTERS. ... DATA DIVISION. FILE SECTION. FD TASKS-IN LABEL RECORDS ARE RECORD CONTAINS 7 01 TASK. 05 TCODE 05 ACCOUNT FD RESPONSE-OUT LABEL RECORDS ARE RECORD CONTAINS 8 01 BALANCE FD ERROR-MSG LABEL RECORDS ARE RECORD CONTAINS 8 01 ERROR-ON-TASK. 05 ERROR-CODE 05 ERR-MSG OMITTED CHARACTERS. PICTURE 9. PICTURE 9(6). OMITTED CHARACTERS. PICTURE 9(8). OMITTED CHARACTERS. PICTURE 9. PICTURE X(7). PROCEDURE DIVISION. ... OPEN INPUT TASKS-IN. OPEN OUTPUT RESPONSE-OUT ERROR-MSG. ... READ-A-TASK. READ TASKS-IN AT END CLOSE TASKS-IN OPEN INPUT TASKS-IN GO TO READ-A-TASK. IF TCODE = 1 PERFORM ... IF WS-BALANCE > 0 MOVE WS-BALANCE TO BALANCE WRITE BALANCE ELSE MOVE WS-ERR-CODE TO ERROR-CODE MOVE MESSAGE(WS-ERR-CODE) TO ERR-MSG WRITE ERROR-ON-TASK. ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 31- 9 Process Initiation, Communication, and Management $RECEIVE $RECEIVE as Input-Output File In this case, $RECEIVE is opened in I-O mode to receive requests and reply to them through the same file. Each request is acted upon and paired with a reply message sent back in response to the task. Figure 31-3. $RECEIVE as Input/Output File Task Message Requester Server Reply Message VST711.vsd The requesting process follows the outline in Example 31-4. Example 31-4. Requester Code (page 1 of 2) ... SELECT TRANSACTIONS ASSIGN TO "$BAL" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. ... FD TRANSACTIONS LABEL RECORDS ARE OMITTED RECORD CONTAINS 1 TO 8 CHARACTERS. 01 TRAN-RESPONSE. 05 RESULT-CODE PICTURE 9. 88 RESULT-OK VALUE IS 1. 88 RESULT-ERROR VALUE IS 2. ... 05 NEW-BALANCE PICTURE 9(7). ... WORKING-STORAGE SECTION. ... 01 TRAN-REQUEST. 05 TRAN-CODE PICTURE 9. 88 TRAN-PMT VALUE IS 1. ... 05 ACCOUNT-NUMBER PICTURE 9(6). ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -10 Process Initiation, Communication, and Management $RECEIVE Example 31-4. Requester Code (page 2 of 2) PROCEDURE DIVISION. ... OPEN I-O TRANSACTIONS SYNCDEPTH 1. ... MOVE TCODE TO TRAN-CODE. MOVE ACCOUNT-IN TO ACCOUNT-NUMBER. READ TRANSACTIONS WITH PROMPT TRAN-REQUEST. ... The server process receives the account number and transaction code from $RECEIVE and sends a response back to the requester, as Example 31-5 shows. Example 31-5. Server Code (page 1 of 2) INPUT-OUTPUT SECTION. FILE-CONTROL. ... SELECT TASKS-IN ASSIGN TO "$RECEIVE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. ... RECEIVE-CONTROL. TABLE OCCURS 20 TIMES SYNCDEPTH LIMIT IS 1 REPLY CONTAINS 8 CHARACTERS. ... DATA DIVISION. ... FD TASKS-IN LABEL RECORDS ARE OMITTED RECORD CONTAINS 1 TO 8 CHARACTERS. 01 TRAN-REQUEST. 05 TRAN-CODE PICTURE 9. 88 TRAN-PMT VALUE IS 1. ... 05 ACCOUNT-NUMBER PICTURE 9(6). ... 01 TRAN-RESPONSE. 05 RESULT-CODE PICTURE 9. 88 RESULT-OK VALUE IS 1. 88 RESULT-ERROR VALUE IS 2. ... 05 NEW-BALANCE PICTURE 9(7). ... HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -11 Process Initiation, Communication, and Management Process Names Example 31-5. Server Code (page 2 of 2) PROCEDURE DIVISION. ... OPEN I-O TASKS-IN. ... READ TASKS-IN. IF TRAN-PMT PERFORM ... IF SOME-ERROR MOVE 2 TO RESULT-CODE ELSE MOVE 1 TO RESULT-CODE MOVE WS-NEW-BALANCE TO NEW-BALANCE WRITE TRAN-RESPONSE ELSE ... Process Names A process that expects to receive messages must have a name by which the sending process can designate it. All processes running on an HP system, named and unnamed, have process file names. If a process is not named explicitly—with the RUNNAMED directive,the NAME option of the RUN command, or the name :length parameter of the PROCESS_CREATE_ procedure—the operating environment issues it with a process file name to an unnamed process. A file name for an unnamed process consists of an optional node name, a dollar sign ($), a processor and PIN, and a process sequence number. A file name for a named process consists of an optional node name, a process name (whose first character is a dollar sign ($)), an optional sequence number, and optional qualifiers. To find the names of processes currently active, use the TACL command PPD. NonStop systems maintain the list of process names in a destination control table (DCT). The systems recognize the PPD command as a request for a tabulation of information about named processes, not unnamed processes. Example 31-6. Report Produced by PPD Command NAME PID1 PID2 $Z000 $CRT2 $NULL $CMON $IMON $DM00 $DM01 ... 00,022 00,021 07,004 07,005 00,031 00,032 01,024 01,021 01,022 00,024 00,026 01,025 ANCESTOR 00,021 $Z000 00,025 00,025 06,010 $IMON $IMON HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -12 Process Initiation, Communication, and Management Example of Simple Interprocess Communication The report in Example 31-6 shows that the process-pair named $Z000 consists of a primary process running in processor module 00 with the process identification number (PIN) 022 and a backup process running in processor 01 with the PIN 021. The processor and PIN of the process that started $Z000 (its ancestor) is 00,021. Notice that not all processes are executing as process pairs—$DM00 and $DM01 (parts of the Inspect symbolic debugger) are running as single processes. Every disk volume name, device name, spooler collector name, and so on, begins with a dollar sign. Each time you read from or write to one of them, you are reading from or writing to the process controlling that entity. Example of Simple Interprocess Communication This example illustrates the principles of interprocess communication using named processes and $RECEIVE (see Figure 31-4). The program PITCHER accepts a line of text from its home terminal and transmits it to the process $CATCH (the program named CATCHER). When it receives a line beginning with the value “END,” PITCHER terminates after transmitting the line. CATCHER displays each line on its home terminal. When the process that opened CATCHER terminates, an HP COBOL run-time routine translates the closure as an end of file (EOF) on $RECEIVE. The AT END phrase of the READ statement passes control around the DISPLAY statement, the PERFORM terminates because its UNTIL phrase is satisfied, and CATCHER terminates. (Use of an empty declarative would eliminate the need for the END-TRANS paragraph and the AT END GO TO construct.) Figure 31-4. $RECEIVE From PITCHER to CATCHER text line "PITCHER" $CATCH VST712.vsd The bold text in Example 31-7 is significant. Note that, in PITCHER, the file for CATCHER is opened for I-O even though it is being used only for output. If you open a process with the OUTPUT or EXTEND attribute, HP COBOL handles the process as a printer device and tries to advance it to the next page—an operation that is meaningless (and fatal) to CATCHER. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -13 Process Initiation, Communication, and Management Example of Simple Interprocess Communication Example 31-7. PITCHER Code IDENTIFICATION DIVISION. PROGRAM-ID. PITCHER. AUTHOR. JO COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1988. DATE-COMPILED. ************************************************************* * This program illustrates the transmission of messages to * * another COBOL program, CATCHER, whose process name is * * $CATCH. * * * * Records entered at this process's home terminal are sent * * $CATCH. * ************************************************************* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REPORT-OUT ASSIGN TO "$CATCH" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL. DATA DIVISION. FILE SECTION. FD REPORT-OUT LABEL RECORDS ARE OMITTED. 01 REPORT-LINE. 05 REPORT-END PICTURE X(3). 88 LAST-LINE-ARRIVED VALUE "END". 05 REPORT-REST PICTURE X(77). PROCEDURE DIVISION. A. OPEN I-O REPORT-OUT. PERFORM TRANSPUT UNTIL LAST-LINE-ARRIVED. STOP RUN. TRANSPUT. ACCEPT REPORT-LINE. WRITE REPORT-LINE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -14 Process Initiation, Communication, and Management Example of Simple Interprocess Communication Example 31-8. CATCHER Code IDENTIFICATION DIVISION. PROGRAM-ID. CATCHER. AUTHOR. SANDY COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1988. DATE-COMPILED. ********************************************************* * This program illustrates the receipt of messages from * * another COBOL program, PITCHER. * * * * This program must be run as a process named $CATCH. * * * * Records received are displayed on this program's home * * terminal. * ********************************************************* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT PRINT-LINES-IN ASSIGN TO "$RECEIVE" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL FILE STATUS IS PRINT-STATUS. DATA DIVISION. FILE SECTION. FD PRINT-LINES-IN LABEL RECORDS ARE OMITTED. 01 LINE-IN PICTURE X(80). WORKING-STORAGE SECTION. 01 PRINT-STATUS PICTURE X(2). 88 SENDER-DISAPPEARED VALUE "10". PROCEDURE DIVISION. A. OPEN INPUT PRINT-LINES-IN. PERFORM TRANSPUT THROUGH END-TRANS UNTIL SENDER-DISAPPEARED. STOP RUN. TRANSPUT. READ PRINT-LINES-IN AT END GO TO END-TRANS. DISPLAY LINE-IN. END-TRANS. EXIT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -15 Process Initiation, Communication, and Management RECEIVE-CONTROL Paragraph RECEIVE-CONTROL Paragraph The RECEIVE-CONTROL paragraph of the Environment Division is an HP extension to COBOL. The RECEIVE-CONTROL paragraph in process $XX serves these purposes: • • • • It defines the receive-control table for process $XX. This specifies the maximum number of other processes that can have process $XX open concurrently. When all such other processes close process $XX, an HP COBOL run-time routine reports an end of file (EOF) on $RECEIVE. It defines the reply table for process $XX. This specifies the number of replies (and the length of a reply) to be saved for each requesting process. A process with a fault-tolerant requester must allow for replies to be saved so that the fault-tolerant facility can retransmit them to restore synchronization in the case of a takeover by the requester’s backup process. (If the requester is not fault-tolerant, the reply table is useless and wastes space.) It designates a data item to contain an error code to be returned to a requesting process that is handling process $XX as a device. Every device in the system returns an error code, a condition code, and a reply-message text. It designates a data item to contain the message source descriptor. This fixedformat item is defined in RECEIVE-CONTROL Paragraph. When the HP COBOL run-time routines complete a successful READ on $RECEIVE, they update this data item to report: ° ° ° The message source (the operating environment or another user process) The entry number in the receive-control table The process ID of the requesting process (name, processor number, and number of process in that processor) Note. If the process is running at a high PIN, the process ID that the operating environment returns is synthetic. For information about synthetic IDs of high-PIN processes, see the Guardian Application Conversion Guide. • It specifies which classes of operating environment messages are to be passed to process $XX. An ordinary Pathway server uses only three entries of the RECEIVE-CONTROL paragraph: • TABLE OCCURS Specifies how many requesters can have the server open at one time. Any additional requesters attempting to open the server are refused. This value must be greater than or equal to the MAXLINKS value in the PATHCOM command file that created the PATHMON environment. A large value is recommended. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -16 Process Initiation, Communication, and Management • At-End Condition SYNCDEPTH Usually set to 1 for Pathway servers unless they are multithreaded. • REPLY CONTAINS Specifies the length of the reply that the server sends back to the requester. It specifies the name of the file containing the longest record that is used as a reply or an explicit number of characters. At-End Condition An entry is made in the receive-control table when a requester executes an OPEN for a file assigned to the server process. A requester can have more than one OPEN issued to a server process at any given time. The receive-control table has a separate entry for each of these OPENs. An entry is deleted from the receive-control table whenever the requester issues a CLOSE for the file assigned to the server process. A server continues to receive requester messages through $RECEIVE if there is an entry in the table. When the last entry is deleted, an at-end condition arises for the server’s READ statement. This at-end condition is handled as an end of file for $RECEIVE. If a file status code data item is defined, it is set to “10” (EOF). Control passes to the statement in the AT END phrase or to a USE procedure if no AT END phrase is present. If the server is a Pathway server, it must stop itself when it detects an at-end condition. An attempt to read a file when it is at end of file causes a permanent error, setting the file status code to “30.” Ordinarily, the program must close and reopen the file before any further activity is possible on that file. For $RECEIVE, however, the run-time routines simulate a close/open sequence, relieving the program of this responsibility; however, such a READ after end of file should include a TIME LIMIT phrase, or the READ could wait indefinitely. See READ for Sequential or Dynamic Access. When a server process has just begun execution and no entries are yet in its receivecontrol table, an at-end condition will never occur before the first OPEN message is received. Summary of $RECEIVE Rules These rules apply to programs that use $RECEIVE: • • Files assigned to $RECEIVE must be sequentially organized and not described with alternate keys or LINAGE clauses. A RECEIVE-CONTROL paragraph in the Input-Output Section of the Environment Division is necessary to define two internal tables essential to the function of $RECEIVE. (Although the RECEIVE-CONTROL paragraph is optional, the default tables permit only the most limited use of $RECEIVE.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -17 Process Initiation, Communication, and Management • • • • • Simple Server Example The OPEN SYNCDEPTH value in the requester process that opens the server process must not exceed the sync value in the RECEIVE-CONTROL paragraph of the server process. Only one reply WRITE to each READ on $RECEIVE is allowed. If you fail to reply to a message before you read the next one, the HP COBOL run-time routines send a default reply. In this situation, you cannot reply to that earlier message. A program can use $RECEIVE whether or not the program runs as a process pair. The contents of the record area associated with $RECEIVE are subject to modification by the HP COBOL run-time routines. Even if a process has not requested delivery of system messages in the RECEIVE-CONTROL paragraph, the run-time routines handle system messages in the $RECEIVE record area. These unrequested messages are not delivered to the process. If a process modifies the record area and then performs a read operation on $RECEIVE, the portion of the record area beyond the actual received message can include residue of such system messages. If you want to know the length of the record you read from $RECEIVE, identify them with RECORD IS VARYING... DEPENDING, which enables you to determine the length of the message that was sent to $RECEIVE by the requester. Simple Server Example The simple server in Example 31-9 looks up items in a telephone directory. Example 31-9. Simple Server (page 1 of 4) IDENTIFICATION DIVISION. PROGRAM-ID. BRIEF-EXAMPLE. AUTHOR. ZANE COBOL. DATE-WRITTEN. 29 February, 1988 DATE-COMPILED. ************************************************************************** * This simple server performs telephone-book lookups. * * Given a name, it reports the name and a number. * * Given a number, it reports the number and a name. * * It assumes that no two persons have the same number or the same name. * ************************************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP System. OBJECT-COMPUTER. HP TXP System. INPUT-OUTPUT SECTION. FILE-CONTROL. * * Declaring MESSAGE-IN and MESSAGE-OUT separately allows us to redirect either or both for debugging during development. SELECT MESSAGE-IN ASSIGN TO $RECEIVE FILE STATUS IS RECEIVE-FILE-STATUS. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -18 Process Initiation, Communication, and Management Simple Server Example Example 31-9. Simple Server (page 2 of 4) SELECT MESSAGE-OUT ASSIGN TO $RECEIVE FILE STATUS IS RECEIVE-FILE-STATUS. SELECT PHONE-BOOK ASSIGN TO "$AA.BB.PHONE" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS PH-EMPLOYEE-NUM ALTERNATE RECORD KEY IS PH-EMPLOYEE-NAME ALTERNATE RECORD KEY IS PH-EMPLOYEE-PHONE-NUM FILE STATUS IS PHONE-FILE-STATUS. RECEIVE-CONTROL. * Up to five requesters can have this server open TABLE OCCURS 5 TIMES SYNCDEPTH LIMIT IS 1 REPLY CONTAINS MESSAGE-OUT RECORD. DATA DIVISION. FILE SECTION. FD MESSAGE-IN LABEL RECORDS ARE OMITTED. 01 FD * PIC S9(4) COMP. PIC X. VALUE "N". VALUE "#". PIC X(10). PIC X(35). MESSAGE-OUT LABEL RECORDS ARE OMITTED record is variable length. RECORD CONTAINS 1 TO 200 CHARACTERS. 01 PHONE-REPLY-MSG. 05 REPLY-CODE PIC S9(4) COMP. 000 = OK, reply contains a value 900 = no match in phone book 05 LOOKUP-CODE PIC X. 88 NAME-LOOKUP VALUE "N". 88 PHONE-LOOKUP VALUE "#". 05 LOOKUP-NUM PIC X(10). 05 LOOKUP-NAME PIC X(35). 01 BAD-PHONE-REPLY-MSG. 05 BAD-REPLY-CODE PIC S9(4) COMP. 001 = bad request, no code given 002 = start of lookup failed * * * * PHONE-QUERY-MSG. 05 FILLER 05 LOOKUP-CODE 88 NAME-LOOKUP 88 PHONE-LOOKUP 05 LOOKUP-NUM 05 LOOKUP-NAME FD PHONE-BOOK LABEL RECORDS ARE OMITTED. 01 PHONE-REC. 05 PH-EMPLOYEE-NUM 05 PH-EMPLOYEE-NAME. 10 PH-EMPLOYEE-NAME-LAST 10 PH-EMPLOYEE-NAME-REST 05 PH-EMPLOYEE-PHONE-NUM PIC X(5). PIC X(15). PIC X(20). PIC X(10). HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -19 Process Initiation, Communication, and Management Simple Server Example Example 31-9. Simple Server (page 3 of 4) WORKING-STORAGE SECTION. 01 REPLY-CODE-VALUES. 05 OK-REPLY PIC 999 05 BAD-REQUEST-REPLY PIC 999 05 START-FAILED-REPLY PIC 999 05 NONE-FOUND-REPLY PIC 999 01 FILE-STATUSES. 05 RECEIVE-FILE-STATUS. 88 RECEIVE-FILE-OK 88 CLOSE-FROM-REQUESTER 10 R-STAT-1 10 R-STAT-2 05 PHONE-FILE-STATUS. 10 P-STAT-1 10 P-STAT-2 88 PHONE-FILE-OK VALUE VALUE VALUE VALUE ZERO. 1. 2. 900. VALUE IS ZEROS. VALUE IS "10". PIC X. PIC X. PIC X. PIC X. VALUE IS ZEROS. PROCEDURE DIVISION. DECLARATIVES. ***************************************************************** UA-MESSAGE-IN SECTION. USE AFTER ERROR PROCEDURE ON MESSAGE-IN. UA-MESSAGE-IN-PROC. IF R-STAT-1 > 1 DISPLAY " ERROR ON MESSAGE-IN FILE " " STAT-1 = " R-STAT-1 " STAT-2 = " R-STAT-2. ***************************************************************** UA-PHONE-BOOK SECTION. USE AFTER ERROR PROCEDURE ON PHONE-BOOK. UA-PHONE-BOOK-PROC. * Empty declarative--intercepts error conditions and allows * PHONE-FILE-STATUS to reflect the success of a START or READ ***************************************************************** UA-MESSAGE-OUT SECTION. USE AFTER ERROR PROCEDURE ON MESSAGE-OUT. UA-MESSAGE-OUT-PROC. IF R-STAT-1 > 1 DISPLAY " ERROR ON MESSAGE-OUT FILE " " STAT-1 = " R-STAT-1 " STAT-2 = " R-STAT-2. ***************************************************************** END DECLARATIVES. ***************************************************************** MAIN SECTION. ************************************ * M A I N L O G I C * ************************************ BEGIN-COBOL-SERVER. PERFORM A-INIT. PERFORM B-TRANS UNTIL CLOSE-FROM-REQUESTER. PERFORM C-EOJ. STOP RUN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -20 Process Initiation, Communication, and Management Simple Server Example Example 31-9. Simple Server (page 4 of 4) ***************************************************************** A-INIT. OPEN INPUT MESSAGE-IN SYNCDEPTH 1 OUTPUT MESSAGE-OUT INPUT PHONE-BOOK SHARED. ***************************************************************** C-EOJ. CLOSE MESSAGE-IN MESSAGE-OUT PHONE-BOOK. B-TRANS. READ MESSAGE-IN. * Declarative handles EOF IF RECEIVE-FILE-STATUS = "00" IF NAME-LOOKUP OF MESSAGE-IN PERFORM B-01-NAME-LOOKUP-PROC ELSE IF PHONE-LOOKUP OF MESSAGE-IN PERFORM B-01-PHONE-LOOKUP-PROC ELSE MOVE SPACES TO PHONE-REPLY-MSG MOVE BAD-REQUEST-REPLY TO BAD-REPLY-CODE OF MESSAGE-OUT ... IF RECEIVE-FILE-STATUS = "00" WRITE PHONE-REPLY-MSG ELSE WRITE BAD-REPLY-MSG. B-01-NAME-LOOKUP-PROC. MOVE LOOKUP-NAME OF MESSAGE-IN TO PH-EMPLOYEE-NAME START PHONE-BOOK KEY IS = PH-EMPLOYEE-NAME. IF NOT PHONE-FILE-OK MOVE START-FAILED-REPLY TO REPLY-CODE OF MESSAGE-OUT ELSE READ PHONE-BOOK IF PHONE-FILE-OK PERFORM B-02-COPY-TO-REPLY ELSE MOVE NONE-FOUND-REPLY TO REPLY-CODE OF MESSAGE-OUT ... B-01-PHONE-LOOKUP-PROC. MOVE LOOKUP-NUM OF MESSAGE-IN TO PH-EMPLOYEE-PHONE-NUM. START PHONE-BOOK KEY IS = PH-EMPLOYEE-PHONE-NUM. IF NOT PHONE-FILE-OK MOVE NONE-FOUND-REPLY TO REPLY-CODE OF MESSAGE-OUT ELSE READ PHONE-BOOK IF PHONE-FILE-OK PERFORM B-02-COPY-TO-REPLY ELSE MOVE NONE-FOUND-REPLY TO REPLY-CODE OF MESSAGE-OUT ... B-02-COPY-TO-REPLY. MOVE PH-EMPLOYEE-PHONE-NUM TO LOOKUP-NUM OF MESSAGE-OUT. MOVE PH-EMPLOYEE-NAME TO LOOKUP-NAME OF MESSAGE-OUT. MOVE OK-REPLY TO REPLY-CODE OF MESSAGE-OUT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -21 Process Initiation, Communication, and Management Managing a Process More information: Topics Sources Programming servers and Pathsend requesters in the Pathway environment TS/MP Pathsend and Server Programming Manual Programming SCREEN COBOL requesters in the Pathway environment Pathway/TS TCP and Terminal Programming Guide Configuring and managing servers in the Pathway environment TS/MP System Management Manual Managing a Process Besides creating processes and communicating with processes, a process might need to obtain information about itself or about some other process in the same system or another system on the same Expand network. Topics: • • • • • • • • Determining the Process Handle Determining the Node (System Number) Identifying the Message Source Determining the Status Identifying the Creator Monitoring Descendants’ Completion Changing the Creator ID Suspending a Process Determining the Process Handle If a process has a record of its process handle—process name, processor number, and number of the process within that processor (also called process identification number or PIN)—it can: • • • Generate more useful diagnostic messages by including the process handle information and the time and date Use its knowledge of its location (processor number) in creating other processes with which it must communicate Obtain information from the operating system routines that require the processor number and PIN as parameters HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -22 Process Initiation, Communication, and Management Determining the Node (System Number) A process can obtain its process ID by passing its process number to the PROCESSHANDLE_DECOMPOSE_ procedure, which returns the processor and PIN values as separate integer values. If you do not know the process number, you can get it by calling the PROCESSHANDLE_GETMINE_ procedure. Example 31-10. PROCESSHANDLE_GETMINE_ and PROCESSHANDLE_DECOMPOSE_ Procedures WORKING-STORAGE SECTION. 01 PROCESS-HANDLE 01 CPU-PIN. 05 CPU 05 PIN 01 ERROR-NUMBER 01 NULL-PH ... PIC X(20). PIC S9(2) COMPUTATIONAL. NATIVE-2. PIC S9(5) COMPUTATIONAL. PIC X(20) VALUE ALL HIGH-VALUES. PROCEDURE DIVISION. ... ENTER TAL "PROCESSHANDLE_GETMINE_" USING PROCESS-HANDLE GIVING ERROR-NUMBER ENTER TAL "PROCESSHANDLE_DECOMPOSE_" USING PROCESS-HANDLE CPU PIN GIVING ERROR-NUMBER Determining the Node (System Number) When NonStop systems are linked together through Expand to constitute a network, each system (or node) of the network has a system number. If copies of a process are running on different nodes, the process might need to determine the system number of the system on which it is running. The process might report diagnostic messages to a central log and include its system name, number, or both. A process can obtain the system number of the system on which it is running by calling the routines PROCESSHANDLE_GETMINE_, PROCESSHANDLE_DECOMPOSE_, and NODENUMBER_TO_NODENAME_, as Example 31-11 shows. Example 31-11. Determining a Process’s Node (System Number) (page 1 of 2) IDENTIFICATION DIVISION. PROGRAM-ID. WHERE-AM-I. AUTHOR. BECK COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1988. DATE-COMPILED. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -23 Process Initiation, Communication, and Management Identifying the Message Source Example 31-11. Determining a Process’s Node (System Number) (page 2 of 2) ************************************************************* * This program obtains and reports its own system number * * and system name. * ************************************************************* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. DATA DIVISION. WORKING-STORAGE SECTION. 01 PROCESS-HANDLE 01 CPU-PIN. 05 CPU 05 PIN 01 ERROR-NUMBER 01 SYSTEM-NAME 01 SYSTEM-NUMBER 01 SYSTEM-NAME-LENGTH PIC X(20). NATIVE-2. NATIVE-2. PIC S9(5) COMP. PIC X(8). NATIVE-2. NATIVE-2. PROCEDURE DIVISION. WHERE-AM-I. ENTER TAL "PROCESSHANDLE_GETMINE_" USING PROCESS-HANDLE GIVING ERROR-NUMBER. ENTER TAL "PROCESSHANDLE_DECOMPOSE_" USING PROCESS-HANDLE CPU PIN GIVING ERROR-NUMBER. ENTER TAL "NODENUMBER_TO_NODENAME_" USING OMITTED SYSTEM-NAME SYSTEM-NAME-LENGTH GIVING ERROR-NUMBER. DISPLAY "I'm executing on system #" SYSTEM-NUMBER ", named """ SYSTEM-NAME """". STOP RUN. Identifying the Message Source To enable your process to determine the source of any message it receives, include a MESSAGE SOURCE clause in the program’s RECEIVE-CONTROL paragraph. This causes the HP COBOL run-time routines to automatically update the data item designated in the MESSAGE SOURCE clause at every successful READ on $RECEIVE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -24 Process Initiation, Communication, and Management Identifying the Message Source The capability of identifying the source of a message allows a process to respond differently to the same request coming from different processes or even to reject certain requests from certain processes. Example 31-12 uses the MESSAGE SOURCE clause to acquire the message-source record. It reads messages on $RECEIVE and displays the processor/PIN, process name, and message code of the message, then displays the message. WHO-SENTTHAT detects whether the sender has an explicit process name. If the sender had an explicit process name, the program determines the processor number and PIN and displays them and the process name. Example 31-12. MESSAGE-SOURCE Clause (page 1 of 2) DATA DIVISION. FILE SECTION. FD MESSAGE-IN-FILE RECORD CONTAINS 1 TO 82 CHARACTERS LABEL RECORDS ARE OMITTED. 01 MESSAGE-IN. 05 SYS-MSG-CODE 05 SYS-MSG-TEXT PIC S9(4) COMP. PIC X(80). WORKING-STORAGE SECTION. 01 MESSAGE-SOURCE-REC. 05 SYSTEM-FLAG PIC S9 COMP. 05 ENTRY-NUMBER PIC 999 COMP. 05 FILLER PIC X(4). 05 PROCESS-HANDLE PIC X(20). 05 CPU-PIN. 06 CPU PIC S9(2) COMPUTATIONAL. 06 PIN NATIVE-2. 05 ERROR-NUMBER PIC S9(5) COMPUTATIONAL. 05 NULL-PH PIC X(20) VALUE ALL HIGH-VALUES. 01 FILE-DATA. 05 RECEIVE-FILE-STATUS PIC XX. 88 RECEIVE-FILE-OK VALUE "00". 88 RECEIVE-FILE-EOF VALUE "10". 01 PROCESS-NAME 01 PROCESS-NAME-LEN PIC X(8). NATIVE-2. PROCEDURE DIVISION. DECLARATIVES. * --Declaratives are a more powerful way to * --errors than a simple AT END phrase, and * --is required to be present. HANDLE-INFILE-ERRORS SECTION. USE AFTER STANDARD ERROR PROCEDURE ON INFILE-ERROR. IF NOT RECEIVE-FILE-EOF DISPLAY "RECEIVE FILE ERROR STATUS END DECLARATIVES. handle file one or the other MESSAGE-IN-FILE. = " RECEIVE-FILE-STATUS . HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -25 Process Initiation, Communication, and Management Determining the Status Example 31-12. MESSAGE-SOURCE Clause (page 2 of 2) AA SECTION. AA-1. OPEN INPUT MESSAGE-IN-FILE. MOVE ZERO TO SYS-MSG-CODE RECEIVE-FILE-STATUS. PERFORM WATCH UNTIL NOT RECEIVE-FILE-OK. STOP RUN. WATCH. READ MESSAGE-IN-FILE. * The READ causes the MESSAGE-SOURCE-REC to be set. PERFORM CHECK-STATUS. CHECK-STATUS. MOVE SPACES TO PROCESS-NAME. ENTER TAL "PROCESSHANDLE_DECOMPOSE_" USING PROCESS-HANDLE CPU PIN * No node number OMITTED * No node name OMITTED * No nodename length OMITTED PROCESS-NAME PROCESS-NAME-LEN GIVING ERROR-NUMBER. IF ERROR-NUMBER EQUAL TO 0 PERFORM DISPLAY-PROCESS-NAME ELSE DISPLAY "ERROR " ERROR-NUMBER. DISPLAY-PROCESS-NAME. DISPLAY "MESSAGE WAS FROM CPU " CPU ", PIN " PIN. IF PROCESS-NAME-LEN > 0 DISPLAY "PROCESS " PROCESS-NAME. DISPLAY "MESSAGE CODE " SYS-MSG-CODE. DISPLAY "MESSAGE CONTENTS: " SYS-MSG-TEXT. Determining the Status Using the ENTER verb, a process can call the PROCESS_GETINFO_ routine to obtain information about any process. The PROCESS_GETINFO_ routine can return any or all of: • • • • • • The process name, processor number, and number of the process within that processor The creator accessor ID (group ID, user ID) of the process The process accessor ID (group ID, user ID) of the process The execution priority at which the process is running The name of the loadfile from which the process was loaded The device name of the process’s home terminal HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -26 Process Initiation, Communication, and Management • • Determining the Status The system number (in a network of systems) on which the process is running An error value, indicating the success of (or the nature of the failure of) the request Topics: • • Accessor IDs Search Mode Accessor IDs The creator accessor ID and process accessor ID are elements of the security system of the operating environment. Every user has a unique user name and a corresponding unique user ID. A user name is of the form: groupname.username where groupname is the name of the group to which the user belongs, and username is a name identifying the individual user within the group. This is the same user name you use when you log on. A user ID is the numeric equivalent of the user name and is of the form: group-id, user-id where group-id and user-id are nonnegative integers in the range 0 through 255. These are the numeric values reported by the WHO command of the command interpreter or in the OWNER column of a FUP INFO report. Every process on an HP system has two accessor IDs: Accessor ID Description Creator accessor ID (CAID) Identifies the user who initiated the creation of the process Process accessor ID (PAID) Authority of the process to make requests to the operating environment, such as to open a file or stop another process When you log on to a NonStop system, the operating environment gives your command interpreter your user ID as its process accessor ID. Only a process having the appropriate process accessor ID can read, write, execute, or purge a given file. All processes that you start (using the explicit or implicit RUN command) ordinarily inherit your process accessor ID as their process accessor ID and as their creator accessor ID. If, however, the loadfile from which you created the process has been designated appropriately (using the PROGID option of the FUP SECURE command or using a SETMODENOWAIT or SETMODE call to set the file security), then the new process adopts as its process accessor ID the loadfile’s owner ID, not your process accessor ID. This enables you to establish a loadfile, executable by other users, that can: • • Gain access to a file to which those users themselves cannot gain access Initiate processes which those users do not own HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -27 Process Initiation, Communication, and Management Determining the Status You can therefore provide a mechanism for passing nonsensitive data from a file containing both sensitive and nonsensitive data to a class of users who should not receive the sensitive data. For more information about these security features, see the operating environment user’s guide for your system. In Example 31-13, an HP COBOL program uses the PROCESS_GETINFO_ routine to discover its environment and then reports the information to its home terminal. Example 31-13. PROCESS_GETINFO_ Routine (page 1 of 3) IDENTIFICATION DIVISION. PROGRAM-ID. PROBE. AUTHOR. TRACY COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 03 FEBRUARY 2000. DATE-COMPILED. 03 FEBRUARY 2000. ****************************************************************** * This program obtains and reports its own process information * * from PROCESSINFO. * ****************************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. DATA DIVISION. WORKING-STORAGE SECTION. 01 PROCESS-HANDLE PIC X(20). 01 CPU-PIN. 05 CPU PIC S9(2) COMPUTATIONAL. 05 PIN NATIVE-2. 05 FILLER PIC X(4). 01 BYTE-PAIR PIC S9(4) COMP. 01 CONSECUTIVE-BYTES REDEFINES BYTE-PAIR. 05 LEFT-BYTE PIC X. 05 RIGHT-BYTE PIC X. 01 BYTE-AS-NUMBER PIC S9(4) COMP. 01 BYTE-TO-NUMERIC REDEFINES BYTE-AS-NUMBER. 05 NUMERIC-LEFT-BYTE PIC X. 05 NUMERIC-RIGHT-BYTE PIC X. 01 CREATOR-ACCESSOR-ID PIC S9(4) COMP. 01 PROCESS-ACCESSOR-ID PIC S9(4) COMP. 01 CREATOR-EDITED. 05 FILLER PIC X(6) VALUE "Group ". 05 CREATOR-GROUP PIC ZZ9. 05 FILLER PIC X(9) VALUE ", Member ". 05 CREATOR-MEMBER PIC ZZ9. 01 PROCESS-EDITED. 05 FILLER PIC X(6) VALUE "Group ". 05 PROCESS-GROUP PIC ZZ9. 05 FILLER PIC X(9) VALUE ", Member ". 05 PROCESS-MEMBER PIC ZZ9. 01 PRIORITY PIC S9(3) COMP. 01 PROGRAM-FILE-NAME PIC X(36). 01 PROGRAM-FILE-NAME-LEN NATIVE-2. 01 HOME-TERMINAL PIC X(24). 01 HOME-TERMINAL-LEN NATIVE-2. 01 ERROR-RETURN PIC S9(2) VALUE ZERO. 01 PROCESS-NAME PIC X(8). 01 PROCESS-NAME-LEN NATIVE-2. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -28 Process Initiation, Communication, and Management Determining the Status Example 31-13. PROCESS_GETINFO_ Routine (page 2 of 3) PROCEDURE DIVISION. WHO. MOVE ZERO TO BYTE-AS-NUMBER. ENTER TAL "PROCESSHANDLE_GETMINE_" USING PROCESS-HANDLE GIVING ERROR-RETURN. ENTER TAL "PROCESS_GETINFO_" * processhandle USING PROCESS-HANDLE * proc-fname OMITTED * proc-fname-len OMITTED * priority PRIORITY * moms-processhandle OMITTED * hometerm HOME-TERMINAL * hometerm-len HOME-TERMINAL-LEN * process-time OMITTED * creator-access-id CREATOR-ACCESSOR-ID * process-access-id PROCESS-ACCESSOR-ID * gmoms-processhandle OMITTED * jobid OMITTED * program-file PROGRAM-FILE-NAME * program-len PROGRAM-FILE-NAME-LEN * ... rest of params not used in this example GIVING ERROR-RETURN. IF ERROR-RETURN = 0 PERFORM EXPLAIN-MYSELF ELSE DISPLAY "PROCESS_GETINFO_ returned an error code of " ERROR-RETURN . STOP RUN. EXPLAIN-MYSELF. MOVE SPACES TO PROCESS-NAME. ENTER TAL "PROCESSHANDLE_DECOMPOSE_" USING PROCESS-HANDLE CPU PIN * No node number OMITTED * No node name OMITTED * No nodename length OMITTED PROCESS-NAME PROCESS-NAME-LEN GIVING ERROR-RETURN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -29 Process Initiation, Communication, and Management Determining the Status Example 31-13. PROCESS_GETINFO_ Routine (page 3 of 3) DISPLAY "I am process (" CPU "," PIN "), named " PROCESS-NAME. PERFORM CAPTURE-ACCESSOR-IDS. DISPLAY "My creator accessor ID is " CREATOR-EDITED. DISPLAY "My process accessor ID is " PROCESS-EDITED. DISPLAY "My priority is " PRIORITY. DISPLAY "My loadfile name is " PROGRAM-FILE-NAME. DISPLAY "My home terminal is " HOME-TERMINAL. STOP RUN. CAPTURE-ACCESSOR-IDS. MOVE MOVE MOVE MOVE MOVE CREATOR-ACCESSOR-ID TO BYTE-PAIR. LEFT-BYTE OF CONSECUTIVE-BYTES TO NUMERIC-RIGHT-BYTE. BYTE-AS-NUMBER TO CREATOR-GROUP. RIGHT-BYTE OF CONSECUTIVE-BYTES TO NUMERIC-RIGHT-BYTE. BYTE-AS-NUMBER TO CREATOR-MEMBER. MOVE MOVE MOVE MOVE MOVE PROCESS-ACCESSOR-ID TO BYTE-PAIR. LEFT-BYTE OF CONSECUTIVE-BYTES TO NUMERIC-RIGHT-BYTE. BYTE-AS-NUMBER TO PROCESS-GROUP. RIGHT-BYTE OF CONSECUTIVE-BYTES TO NUMERIC-RIGHT-BYTE. BYTE-AS-NUMBER TO PROCESS-MEMBER. Search Mode The PROCESS_GETINFOLIST_ routine lets you search for a process that meets one or more of these criteria: • • • • • • Has a specified process ID Has a specified creator accessor ID Has a specified process accessor ID Has a specified home terminal Has a priority not greater than a specified priority Came from a specified loadfile name For example, you can search for a process that is running at a priority of less than 40, has $THIRTY as its home terminal, and was loaded from loadfile $MEDIUM.PEPPER.STEAK. Using search mode, you can implement processes for such tasks as determining whether a certain named process is running, identifying processes that are running at inappropriate priorities, or determining whether a process is using a certain terminal. The only required parameter is the 2-byte binary item containing a processor and PIN value. The routine uses this to determine where to start its search. The remaining parameters can be present or specified as OMITTED. The values to be matched in the search are specified by the same parameters the operating environment is to use to return the values appropriate to the process it finds. In Example 31-14, an HP COBOL program finds and reports all processes on its system that have the same process accessor ID as the program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -30 Process Initiation, Communication, and Management Determining the Status Example 31-14. Reporting Processes With Program’s Accessor ID (page 1 of 3) IDENTIFICATION DIVISION. PROGRAM-ID. WHAT-AM-I-DOING. AUTHOR. BRINDLEY COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1988. DATE-COMPILED. ***************************************************************** * This program hunts out and reports all processes owned by * * the current user. * ***************************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. DATA DIVISION. WORKING-STORAGE SECTION. 01 PROCESS-HANDLE 01 CPU-PIN. 05 CPU 05 PIN 01 ERROR-NUMBER 01 NULL-PH 01 NUMERIC-CPU 01 NUMERIC-PIN 01 BYTE-PAIR 01 CONSECUTIVE-BYTES 05 LEFT-BYTE 05 RIGHT-BYTE 01 SEPARATED-BYTES. 05 LEFT-BYTE. 10 LEFT-HIGH-BYTE 10 LEFT-LOW-BYTE 05 NUMERIC-LEFT-BYTE 05 RIGHT-BYTE. 10 RIGHT-HIGH-BYTE 10 RIGHT-LOW-BYTE 05 NUMERIC-RIGHT-BYTE 01 PROCESS-ACCESSOR-ID 01 PROCESS-EDITED. 05 PROCESS-GROUP 05 FILLER 05 PROCESS-MEMBER 01 CREATOR-ACCESSOR-ID 01 PRIORITY 01 PROGRAM-FILE-NAME 01 HOME-TERMINAL 01 ERROR-RETURN 01 MASQUE * Bits: 0010 * to request 01 CURRENT-CPU 01 BINARY-WORKTABLE 01 INTERNAL-NAME 01 EXTERNAL-NAME PIC X(20). PIC S9(2) COMPUTATIONAL. NATIVE-2. PIC S9(5) COMPUTATIONAL. PIC X(20) VALUE ALL HIGH-VALUES. PIC S9(2) COMPUTATIONAL. NATIVE-2. PIC S9(4) COMP. REDEFINES BYTE-PAIR. PIC X. PIC X. PIC X. PIC X. PIC S9(2) COMP PIC PIC PIC PIC REDEFINES LEFT-BYTE. X. X. S9(2) COMP REDEFINES RIGHT-BYTE. S9(4) COMP. PIC ZZ9. PIC X(1) VALUE ",". PIC 999. PIC S9(4) COMP. PIC S9(3) COMP. PIC X(34). PIC X(34). PIC S9(2) VALUE ZERO. PIC S9(4) COMP VALUE 8192. 0000 0000 0000 match on process accessor id. PIC S9(4) COMP VALUE 0. PIC S9(4) COMP. PIC X(24). PIC X(34). HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -31 Process Initiation, Communication, and Management Determining the Status Example 31-14. Reporting Processes With Program’s Accessor ID (page 2 of 3) PROCEDURE DIVISION. WHATS-HAPPENING. * Start with cpu-PIN of 0,0 MOVE LOW-VALUES TO CPU-PIN. * Get owner's process accessor id ENTER TAL "PROCESS_GETINFO_" USING PROCESS-HANDLE OMITTED OMITTED PRIORITY OMITTED HOME-TERMINAL OMITTED OMITTED CREATOR-ACCESSOR-ID PROCESS-ACCESSOR-ID OMITTED OMITTED PROGRAM-FILE-NAME OMITTED OMITTED GIVING ERROR-RETURN. PERFORM EDIT-ACCESSOR-ID. DISPLAY "CPU,PIN GRP,USR PRI loadfile "HOMETERM". " * Hunt through all CPUs in system PERFORM INVESTIGATE-A-CPU UNTIL CURRENT-CPU > 16. STOP RUN. INVESTIGATE-A-CPU. ENTER TAL "PROCESS_GETINFO_" USING PROCESS-HANDLE OMITTED OMITTED PRIORITY OMITTED HOME-TERMINAL OMITTED OMITTED CREATOR-ACCESSOR-ID PROCESS-ACCESSOR-ID OMITTED OMITTED PROGRAM-FILE-NAME OMITTED OMITTED GIVING ERROR-RETURN. IF ERROR-RETURN < 2 * Found a match PERFORM REPORT-A-MATCH ADD 1 TO CPU-PIN ELSE IF ERROR-RETURN = 2 * No more on current CPU PERFORM INCREMENT-CPU-OR-QUIT ELSE IF ERROR-RETURN < 99 * CPU not configured or incommunicado PERFORM INCREMENT-CPU-OR-QUIT ELSE DISPLAY "INTERNAL ERROR IN PARAMETERS" STOP RUN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -32 Process Initiation, Communication, and Management Identifying the Creator Example 31-14. Reporting Processes With Program’s Accessor ID (page 3 of 3) REPORT-A-MATCH. PERFORM EDIT-CPU-PIN. DISPLAY "(" NUMERIC-CPU "," NUMERIC-PIN ") " PROCESS-EDITED " " PRIORITY " ". DISPLAY PROGRAM-FILE-NAME " " HOME-TERMINAL " ". EDIT-CPU-PIN. MOVE CPU-PIN TO BYTE-PAIR. PERFORM SEPARATE-BYTE-PAIR. MOVE NUMERIC-LEFT-BYTE TO NUMERIC-CPU. MOVE NUMERIC-RIGHT-BYTE TO NUMERIC-PIN. EDIT-ACCESSOR-ID. MOVE PROCESS-ACCESSOR-ID TO BYTE-PAIR. PERFORM SEPARATE-BYTE-PAIR. MOVE NUMERIC-LEFT-BYTE TO PROCESS-GROUP. MOVE NUMERIC-RIGHT-BYTE TO PROCESS-MEMBER. SEPARATE-BYTE-PAIR. MOVE LOW-VALUES TO SEPARATED-BYTES. MOVE LEFT-BYTE OF CONSECUTIVE-BYTES TO LEFT-LOW-BYTE OF SEPARATEDBYTES. MOVE RIGHT-BYTE OF CONSECUTIVE-BYTES TO RIGHT-LOW-BYTE OF SEPARATEDBYTES. INCREMENT-CPU-OR-QUIT. IF CURRENT-CPU < 15 ADD 1 TO CURRENT-CPU MOVE CURRENT-CPU TO BINARY-WORKTABLE MULTIPLY 256 BY BINARY-WORKTABLE MOVE BINARY-WORKTABLE TO CPU-PIN ELSE DISPLAY "------------------------------" STOP RUN. Identifying the Creator A process can use the PROCESS_GETINFO_ routine to determine the identity of the process that created it, which enables the process to be selective. It can terminate if it was created by an inappropriate agent. It can open different files depending on the identity of its creator. It can send messages to its creator explicitly. It can even suspend or stop its creator if its process accessor ID matches its creator’s creator accessor ID. When you issue a RUN command, such as RUN X, your TACL process initiates the specified process. The process produced from loadfile X has the TACL process as its creator. In addition, suppose your process uses CREATEPROCESS or CLU_PROCESS_CREATE_ to initiate a new process. The child process can discover the identity of its parent process, if the child is not running as a process pair (in that case, the parent of the primary process is the backup process). Example 31-15 uses the PROCESS_GETINFO_ routine to report the identity of its creator to its home terminal. To handle the possibility of an unnamed process, the example uses the same mechanism to decipher its creator’s process name that is used in WHO-SENT-THAT in Identifying the Message Source. After identifying its creator process, the example determines whether it can stop its creator; if it can, it does. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -33 Process Initiation, Communication, and Management Identifying the Creator Example 31-15. Identifying a Process’s Creator (page 1 of 2) IDENTIFICATION DIVISION. PROGRAM-ID. WHOA-MOM. AUTHOR. KRIS COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1988. DATE-COMPILED. ********************************************************************* * This program obtains and reports the process ID of its creator, * * then attempts to stop its creator. * ********************************************************************* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. DATA DIVISION. WORKING-STORAGE SECTION. 01 MOMS-PROCESS-ID. 05 MOMS-PROCESS-NAME PIC X(6). 05 MOMS-CPU-PIN PIC S9(4) COMP. 05 CPU-PIN-REDEF REDEFINES MOMS-CPU-PIN. 10 CPU-PART PIC X. 10 PIN-PART PIC X. 01 PNAME. 05 PNAME-BYTES-1-2 PIC XX. 05 PNAME-FIRST-WORD-NUM REDEFINES PNAME-BYTES-1-2 PIC S9(3) COMP. 05 FILLER PIC X(4). 01 CPU-PIN-REWORK. 05 ALPHA-CPU. 10 CPU-HIGH-BYTE PIC X. 10 CPU-LOW-BYTE PIC X. 05 NUMERIC-CPU REDEFINES ALPHA-CPU PIC S9(2) COMP. 05 ALPHA-PIN. 10 PIN-HIGH-BYTE PIC X. 10 PIN-LOW-BYTE PIC X. 05 NUMERIC-PIN REDEFINES ALPHA-PIN PIC S9(3) COMP. 01 MY-CPU-PIN PIC S9(4) COMP. 01 MY-PAID PIC S9(4) COMP. 01 MOMS-CAID PIC S9(4) COMP. 01 INTERNAL-NAME PIC X(24). 01 EXTERNAL-NAME PIC X(34). 01 ERROR-RETURN PIC S9(2) VALUE ZERO. 01 DISPLAY-BUFFER PIC X(79). PROCEDURE DIVISION. WHO. * -- PROCESS_GETINFO_ delivers 4-word process-id to MOMS-PROCESS-ID ENTER TAL "PROCESS_GETINFO_" USING MOMS-PROCESS-ID. * -- Report MOM's process name to my home terminal PERFORM DISPLAY-PROCESS-NAME. * -- Take only the CPU-PIN from MOM, and ask for MOM's * -- creator accessor id. ENTER TAL "PROCESS_GETINFO_" USING MOMS-CPU-PIN OMITTED MOMS-CAID GIVING ERROR-RETURN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -34 Process Initiation, Communication, and Management Monitoring Descendants’ Completion Example 31-15. Identifying a Process’s Creator (page 2 of 2) IF ERROR-RETURN NOT = 0 DISPLAY "Call to PROCESS_GETINFO_ returned an error code of " ERROR-RETURN STOP RUN. * -- Get my process accessor id ENTER TAL "PROCESS_GETINFO_" USING PROCESS-HANDLE OMITTED OMITTED OMITTED OMITTED OMITTED OMITTED OMITTED MOMS-CAID MY-PAID OMITTED OMITTED OMITTED OMITTED OMITTED OMITTED GIVING ERROR-RETURN. IF ERROR-RETURN NOT = 0 DISPLAY "Call to PROCESS_GETINFO_ returned an error code of " ERROR-RETURN STOP RUN. * -- If my process accessor id matches MOM's creator accessor id, I can * -- stop MOM before continuing IF MY-PAID = MOMS-CAID ENTER TAL "PROCESS_STOP_" USING MOMS-PROCESS-ID. * ... STOP RUN. DISPLAY-PROCESS-NAME. MOVE MOMS-PROCESS-NAME TO PNAME. IF PNAME-FIRST-WORD-NUM < 0 MOVE MOMS-PROCESS-ID TO INTERNAL-NAME DISPLAY "My creator is (" NUMERIC-CPU "," NUMERIC-PIN ")-----" MOMS-PROCESS-NAME ... CAPTURE-CPU-PIN. MOVE CPU-PART TO CPU-LOW-BYTE. MOVE LOW-VALUES TO CPU-HIGH-BYTE. MOVE PIN-PART TO PIN-LOW-BYTE. MOVE LOW-VALUES TO PIN-HIGH-BYTE. Monitoring Descendants’ Completion The operating environment always sends messages about descendant processes to parent processes. If your process starts another process, it might need to determine whether the process ran to normal completion or terminated abnormally. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -35 Process Initiation, Communication, and Management Monitoring Descendants’ Completion The HP COBOL run-time routines report the receipt of system messages only when the RECEIVE-CONTROL paragraph specifies it. If you want a process that creates other processes to be notified about termination or failure of these descendant processes: • • Include a REPORT SYSTEM MESSAGES entry in the RECEIVE-CONTROL paragraph of the parent process. Have the parent process monitor $RECEIVE and watch for ABEND and STOP messages. A process other than the actual creator can intercept the STOP and ABEND messages by using the PROCESS_SETINFO_ routine to become the creator of record. See Changing the Creator ID. Example 31-16 creates a FUP process and then watches for its termination. Example 31-16. Monitoring Completion of Descendant Processes (page 1 of 3) ?ENV COMMON ?SAVE ALL ?SEARCH $SYSTEM.SYSTEM.COBOLLIB IDENTIFICATION DIVISION. PROGRAM-ID. FUPPERWARE. AUTHOR. TERRY COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1988. DATE-COMPILED. ************************************************************************* * This program creates a FUP process and watches for its termination. * ************************************************************************* ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. SPECIAL-NAMES. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT MESSAGE-IN-FILE ASSIGN TO "$RECEIVE" FILE STATUS IS RECEIVE-FILE-STATUS. I-O-CONTROL. RECEIVE-CONTROL. TABLE OCCURS 1 TIMES SYNCDEPTH LIMIT IS 1 MESSAGE SOURCE IS MESSAGE-SOURCE-REC REPORT SYSTEM MESSAGES. DATA DIVISION. FILE SECTION. FD MESSAGE-IN-FILE LABEL RECORDS ARE OMITTED. 01 MESSAGE-IN. 05 SYS-MSG-CODE 88 SYS-MSG-STOP 05 SYS-MSG-PROCNAME 05 FILLER 05 SYS-MSG-STOP-FLAG 05 FILLER PIC S9(4) COMP. VALUE -101. PIC X(6). PIC X(66). NATIVE-2. PIC X(948). HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -36 Process Initiation, Communication, and Management Monitoring Descendants’ Completion Example 31-16. Monitoring Completion of Descendant Processes (page 2 of 3) WORKING-STORAGE SECTION. 01 MESSAGE-SOURCE-REC. 05 SYSTEM-FLAG 05 ENTRY-NUMBER 05 FILLER 05 PROCESS-HANDLE 10 CPU-PIN. 15 CPU 15 PIN 05 FILLER 01 CPU-PIN-REDEF. 05 ALPHA-CPU. 10 CPU-HIGH-BYTE 10 CPU-LOW-BYTE 05 NUMERIC-CPU PIC S9 COMP. PIC 999 COMP. PIC X(4). PIC S9(2) COMP. NATIVE-2. PIC X(16). 05 ALPHA-PIN. 10 PIN-HIGH-BYTE 10 PIN-LOW-BYTE 05 NUMERIC-PIN PIC X. PIC X. REDEFINES ALPHA-CPU PIC S9999 COMP. PIC X. PIC X. REDEFINES ALPHA-PIN PIC S9999 COMP. 01 FILE-DATA. 05 RECEIVE-FILE-STATUS. 10 STAT-1 PIC 9. 88 CLOSE-FROM-REQUESTOR VALUE 1 THRU 3. 10 STAT-2 PIC 9. 01 SAVE-MESSAGE-STUFF. 05 FUP PIC X(21) VALUE "$SYSTEM.SYSTEM.FUP". 05 SU-ERROR PIC S9(4) VALUE ZERO COMP. 05 NEWPROCESS-ERR-LEFT PIC 9(4). 05 NEWPROCESS-ERR-RIGHT PIC 9(4). 05 FUP-FAILED PIC X(19) VALUE "Failed to start FUP". 05 STRING-PORTION PIC X(6) VALUE "STRING". 05 INFO-COMMAND PIC X(6) VALUE "INFO *". 05 STARTUP-RESULT PIC S9(4) VALUE ZERO COMP. 05 NULL-CPLIST PIC S9(9) VALUE ZERO COMP. PROCEDURE DIVISION. DECLARATIVES. HANDLE-INFILE-ERRORS SECTION. USE AFTER STANDARD ERROR PROCEDURE ON MESSAGE-IN-FILE. INFILE-ERROR. IF STAT-1 = 1 DISPLAY "EOF on $RECEIVE" ELSE DISPLAY "RECEIVE FILE ERROR STATUS = " RECEIVE-FILE-STATUS ... END DECLARATIVES. AA SECTION. AA-1. OPEN INPUT MESSAGE-IN-FILE. MOVE ZERO TO SU-ERROR SYS-MSG-CODE. * Inject INFO command into startup message to pass to FUP ENTER "PUTSTARTUPTEXT" USING STRING-PORTION, INFO-COMMAND, NULL-CPLIST GIVING STARTUP-RESULT. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -37 Process Initiation, Communication, and Management Monitoring Descendants’ Completion Example 31-16. Monitoring Completion of Descendant Processes (page 3 of 3) * Start FUP ENTER "CREATEPROCESS" USING FUP GIVING SU-ERROR. * Await termination of FUP, or report it never started IF SU-ERROR = 0 PERFORM WATCH UNTIL SYS-MSG-STOP IF FUNCTION MOD (SYS-MSG-STOP-FLAG, 2) = 0 DISPLAY "FUP terminated normally" ELSE DISPLAY "FUP aborted" END-IF ELSE PERFORM DISPLAY-STARTUP-FAILURE. STOP RUN. DISPLAY-STARTUP-FAILURE. EVALUATE SU-ERROR WHEN 1 DISPLAY FUP-FAILED " -- REQUIRED PARAMETER MISSING OR ILLEGAL" WHEN 2 DISPLAY FUP-FAILED " -- ILLEGAL loadfile NAME (" FUP ")" WHEN 3 DISPLAY FUP-FAILED " -- INFILE, OUTFILE, OR DEFAULT VOLUME" DISPLAY " NAME CANNOT BE CONVERTED TO NETWORK FORM" WHEN OTHER IF SU-ERROR < 256 DISPLAY FUP-FAILED " -- File management error #" SU-ERROR ELSE * -- Received raw error from NEWPROCESS system procedure. * -- Decompose it into left byte and right byte values. DIVIDE SU-ERROR BY 256 GIVING NEWPROCESS-ERR-LEFT REMAINDER NEWPROCESS-ERR-RIGHT. DISPLAY FUP-FAILED " -- NEWPROCESS error # = (" NEWPROCESS-ERR-LEFT "," NEWPROCESS-ERR-RIGHT ")" END-IF END-EVALUATE ... WATCH. READ MESSAGE-IN-FILE. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -38 Process Initiation, Communication, and Management Changing the Creator ID Changing the Creator ID One reason the operating environment keeps track of the creator of a process is to be able to notify a creator when a descendant process terminates. If process $PARENT starts process $CHILD, the operating environment notifies $PARENT through the $RECEIVE mechanism when $CHILD terminates. It is possible for a third process, $THIRD, to instruct the operating environment to alter the system tables to make $THIRD the recorded parent of $CHILD. $THIRD does this by calling the PROCESS_SETINFO_ procedure. This operation is legal only if $THIRD has the same process accessor ID as $CHILD; the $THIRD process has no explicit control other than that. The fault-tolerant facility uses PROCESS_SETINFO_ to enable each member of a process pair to be notified if the other terminates. After $THIRD has called PROCESS_SETINFO_, any notification of $CHILD’s termination is sent to $THIRD, rather than to $PARENT. Also, if $CHILD calls PROCESS_GETINFO_, the operating environment reports back to $CHILD that $THIRD is $CHILD’s creator. For more information about PROCESS_GETINFO_ or PROCESS_SETINFO_, see the Guardian Procedure Calls Reference Manual. Suspending a Process A process might need to automatically suspend its execution. It might be a sampling routine that wakes up, takes and records some measurements, and suspends itself for a time. It might be a monitoring routine that wakes up every 10 minutes and checks whether a specified terminal or a certain program is in use. By calling the DELAY routine, a process can suspend its execution for a number of hundredths of a second. Example 31-17 uses suspension to watch for a remote system to become available so it can send a message to a routine on the remote system. Example 31-17. Suspending a Process (page 1 of 2) IDENTIFICATION DIVISION. PROGRAM-ID. DOZER. AUTHOR. BUFFY COBOL. INSTALLATION. TRANSACTIONS ANONYMOUS. DATE-WRITTEN. 29 FEBRUARY 1988. DATE-COMPILED. ************************************************************************** * This program sends one message to $BOSS on system \HQ. If that * * process cannot be opened, the program tries again every five minutes. * ************************************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. HP TXP. OBJECT-COMPUTER. HP TXP. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -39 Process Initiation, Communication, and Management Suspending a Process Example 31-17. Suspending a Process (page 2 of 2) INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REPORT-OUT ASSIGN TO "\HQ.$BOSS" ORGANIZATION IS SEQUENTIAL ACCESS MODE IS SEQUENTIAL FILE STATUS IS REPORT-STATUS. DATA DIVISION. FILE SECTION. FD REPORT-OUT LABEL RECORDS ARE OMITTED. 01 REPORT-LINE PIC X(80). WORKING-STORAGE SECTION. 01 REPORT-STATUS PIC XX VALUE " ". 01 REPEAT-INTERVAL PIC S9(10) VALUE 30000. * = 5 min * 60 sec * 100 PROCEDURE DIVISION. DECLARATIVES. HANDLE-REPORT-ERRORS SECTION. USE AFTER STANDARD ERROR PROCEDURE ON REPORT-OUT. REPORT-ERROR. * An empty declarative can be used to intercept error conditions * and set the file status data item. * Presence of a declarative does not prevent the run-time routine * from delivering an error 019 to the home terminal of this * process. END DECLARATIVES. PULLMAN SECTION. ZZZZ. PERFORM OPEN-IT UNTIL REPORT-STATUS = "00". MOVE "Having a wonderful time! Wish you were here." TO REPORT-LINE. WRITE REPORT-LINE. CLOSE REPORT-OUT. STOP RUN. OPEN-IT. OPEN OUTPUT REPORT-OUT. IF REPORT-STATUS NOT = "00" * That is, error on file open. ENTER TAL "DELAY" USING REPEAT-INTERVAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 31 -40 32 Fault-Tolerant Processes A process is running in a fault-tolerant manner when no single point of failure can stop the process or corrupt its data or the files it is manipulating. Processes are not automatically fault tolerant—they must be designed and implemented to be fault tolerant. How might a single point of failure affect a process? Suppose a process is operating an automated teller machine (ATM) for a financial institution. If you, as a customer, come to the ATM and request $20 from your account: • • • You want the ATM to service your request, not terminate before completing the transaction. You want the ATM to record at most one debit of $20 from your account; the institution wants the ATM to record at least one debit of $20 from your account. You want the ATM to dispense at least $20 to you; the institution wants the ATM to dispense at most $20 to you. If the process is not fully fault tolerant, a number of possible failures can interfere with the preceding desires: • • • • A process might be running on a processor that fails (blows a fuse, is accidentally unplugged, is stopped by an operator, or whatever), so the transaction does not complete. A process might get part way through your withdrawal transaction, deducting the $20 from your balance but not yet reaching the point of dispensing the cash to you. If the process is automatically retried, it might deduct the $20 from your account again and dispense you the cash; but the balance in your account would then be down by $40. A process might fail during the transaction after disbursing the $20 to you, but before recording the fact, and resume at the point of asking what you want. If you again asked for $20, the process could disburse another $20 (total = $40) and record only a $20 withdrawal. A process might disburse the $20 cash to you and fail before making a permanent record of the transaction. Topics: • • • NonStop Operating System Fault-Tolerant Facility TMF HP COBOL Manual for TNS and TNS/R Programs —522555-006 32- 1 Fault-Tolerant Processes NonStop Operating System NonStop Operating System The NonStop operating system architecture is the underlying mechanism that enables you to write fault-tolerant processes. The full redundancy of processors, devices, controllers, and paths among them is the basis for the NonStop operating system’s fault tolerance. But given that base, there are still two ways a process (particularly a Pathway server process operating under TS/MP) can be designed to be fault tolerant: by using the fault-tolerant facility or by using TMF. Topics: • • • Introduction to the Fault-Tolerant Facility Introduction to TMF Choosing the Fault-Tolerant Facility or TMF When you have decided which of the two mechanisms to use, you can read more about it in Fault-Tolerant Facility or TMF. Introduction to the Fault-Tolerant Facility Note. This topic does not apply to the OSS environment. It applies to the NMCOBOL compiler only for RVU D46.00 and G06.00 or later, software product revision T8107AAT (run-time library T8108AAR). To use the fault-tolerant facility, you must include the NONSTOP compiler directive in your compilation and embed one STARTBACKUP statement and one or more CHECKPOINT statements at strategic points in your program. At the beginning of its execution, after opening its files, your process executes a STARTBACKUP statement to instruct the operating environment to produce a backup process in a different processor and to open the same files in the backup process. The backup process is loaded from the same loadfile as the original (primary) process, but the operating environment does not actually start it running. At certain points in your program, you code CHECKPOINT statements, which instruct the operating environment to copy a specific list of one or more of your data elements into the backup process’s data space. If the primary process fails, the operating environment activates the backup process. The backup process starts executing at the code location following the last CHECKPOINT statement executed. At this point, the backup process’s data space contains a copy of the part of the primary process’s data space that was checkpointed at the time of the last CHECKPOINT statement. Determining the proper sites and data-element lists for CHECKPOINT statements can be a painstaking operation. One recommendation is that you checkpoint everything involved in writing a record just before executing the WRITE statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32- 2 Fault-Tolerant Processes Introduction to TMF Introduction to TMF The HP NonStop™ Transaction Management Facility (TMF) relies on the principle of archiving and backing out transactions. Every transaction has a beginning and an end. If the entire transaction cannot be completed (due to some single point of failure), any changes made to the database must be backed out. This means that other processes must be kept from using any of the records that a transaction has modified until the transaction has been completed. If you are writing a Pathway server in HP COBOL, and the Pathway application will use TMF, your design is much simpler than it would be if you used the fault-tolerant facility. All an HP COBOL server needs to do to be fault tolerant under these conditions is to lock every record it is going to change before changing the record, and lock any record it reads that affects the course of the transaction. All other coding for fault tolerance is at the requester level—the SCREEN COBOL program includes BEGIN TRANSACTION, END TRANSACTION, and ABORT TRANSACTION statements. If you want an HP COBOL program that is not a Pathway server to run under TMF, you must include ENTER statements to call the routines BEGINTRANSACTION, ENDTRANSACTION, and so on. Choosing the Fault-Tolerant Facility or TMF If your program is updating unaudited files and you want it to be fault tolerant, you must code it to use the fault-tolerant facility; otherwise, whether to use the fault-tolerant facility or TMF is primarily a question of efficiency versus maintenance. TMF is implemented with process pairs, so when you use TMF you are using the faulttolerant facility indirectly. Using the fault-tolerant facility directly makes the program run more efficiently; however, maintenance is easier with TMF, because the programming and debugging of the process pairs has already been done for you. It is easier to configure the system for TMF and to design, implement, and maintain servers that use TMF than it is to design, implement, and maintain process pairs. The auditing operation takes processing time. The audit trails take disk space and require tape operations. But just as Pathway/TS frees the application programmers from having to produce and support multithreaded requesters, TMF frees them from having to produce and maintain process pairs. Fault-Tolerant Facility The fault-tolerant facility is software that HP provides but that you must explicitly call to cause a loadfile to be executed as a process pair. You must include a NONSTOP directive in your compilation before the PROCEDURE DIVISION header. You must include one STARTBACKUP statement to create the backup process, and a number of CHECKPOINT statements to transmit restart information to the backup process. Finally, you must run the program as a named process (to learn how, see Process Names). HP COBOL Manual for TNS and TNS/R Programs —522555-006 32- 3 Fault-Tolerant Processes Process Pairs After you have done these things, the fault-tolerant facility does the remainder of the work to assure fault-tolerant operation. Topics: • • • • • Process Pairs Checkpointing Using the Fault-Tolerant Facility Designing Programs for the Fault-Tolerant Facility Debugging Programs That Use the Fault-Tolerant Facility The information in these topics is general. For specific details on checkpointing, see the Guardian Programmer’s Guide. For details on the STARTBACKUP and CHECKPOINT statements, see STARTBACKUP and CHECKPOINT. Process Pairs A process is the basic executable unit known to the operating environment—the execution (in a processor) of a program. Specifically, the term program indicates a group of instruction codes and initialized data—an HP COBOL run unit; the term process denotes the changing states of an executing program. The same loadfile can be executing concurrently a number of times, but each execution is a separate process. An application process can be designed to recover from any type of hardware failure except one—a failure of the processor in which it is executing. One way to provide fault tolerance is to establish the process as a process pair. A process pair consists of two executions of the same loadfile: the primary process executes in one processor; the backup process executes in another. Control in the program indicates whether the process is executing in the primary mode to perform its task or in the backup mode to monitor the primary process. Figure 32-1. Process Pair Primary Process (performs the work) A Operating System Backup Process (monitors the primary process) A' Checkpoint Messages System Messages VST716.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 32- 4 Fault-Tolerant Processes Process Pairs In this primary-plus-backup structure, the fault-tolerant facility (as directed by the primary process) keeps the backup process informed of the executing state of the primary process. At critical points in the processing, the primary process sends checkpoint messages to the backup process to pass the current state of the data, the file buffers, and the files to the backup process. When the backup process learns of the failure of its primary process (by the receipt of a process-failure or processor-failure system message through $RECEIVE), the backup process becomes the primary process and continues with the application’s work (possibly starting a new backup process for itself). The fault-tolerant facility provides the means of writing application programs that can recover from a processor module failure. When the primary process executes a STARTBACKUP statement, a fault-tolerant facility routine in the primary process directs the operating environment to start the backup process. When the primary process executes a CHECKPOINT statement, a fault-tolerant facility routine transmits pertinent data to the backup process. While the primary process is operating, a fault-tolerant facility routine in the backup process automatically monitors and accepts checkpoint information from the primary process. If the backup process is notified of the failure of its primary process, the fault-tolerant facility causes the backup process to begin executing at the statement following the latest CHECKPOINT statement. (The notification to the backup process of the failure of the primary process comes in the form of a processor-down, stop, or abend message delivered through $RECEIVE and handled automatically by the HP COBOL fault-tolerant facility.) Figure 32-2 illustrates the activity of a process pair. The backup process stays in monitor state while the primary process is operating. If the primary fails, the backup leaves the monitor state and begins executing at the point indicated by the last call to CHECKPOINT by the primary. Figure 32-2. Activity of a Process Pair "primary" "backup" OPEN files monitor primary STARTBACKUP process READ entry from terminal READ ... READ record from disk READ ... update record in memory CHECKPOINT WRITE updated record to disk update ... CHECKPOINT WRITE ... VST717.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 32- 5 Fault-Tolerant Processes Checkpointing This sequence of actions occurs when a process pair runs: 1. The primary process opens any files required for its execution. 2. The primary process starts its backup process in another processor module by executing a STARTBACKUP verb. This action also opens the files for the backup process and checkpoints the state of the primary process to the backup process. A process pair opens files in a manner that permits both members of the pair to have a file open while retaining the ability to exclude other processes from accessing a file. When a disk file has been opened by a process pair in this manner, a record or file lock by the primary process is also an equivalent lock by the backup process. 3. The backup process, at the beginning of its execution, automatically begins monitoring the primary process. This is the extent to which the backup process executes unless a failure of the primary process occurs. 4. The primary process begins executing its main processing loop. At critical points through the execution loop, typically before each write to a disk file, the primary process executes a CHECKPOINT statement to copy part of its environment and pertinent file control information to the backup process (marking a restart point for the backup process). Typically, a program contains several CHECKPOINT statements, each of which checkpoints only a portion of the primary process’s environment. 5. If the primary process fails, the backup process begins executing at the restart point indicated by the latest execution of a CHECKPOINT statement. The backup process is then considered to be the primary process. 6. If the reason the primary process failed was a processor failure (that is, the backup process received a processor-down message), the fault-tolerant facility in the new primary (former backup) process automatically starts a new backup process when the failed processor has been repaired and brought back on line. This new backup process is then ready to take over if the primary process fails. Checkpointing When the primary process executes a CHECKPOINT statement, one of its faulttolerant facility routines formats a message containing the information to be checkpointed and sends it to the backup process in the form of an interprocess message. A fault-tolerant facility routine in the backup process receives and acts upon the message. The two types of information you must usually checkpoint are data items and sync blocks. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32- 6 Fault-Tolerant Processes Checkpointing Topics: • • • • Data Items Sync Blocks General Rules Rules for Servers to Follow With Fault-Tolerant Requesters Data Items These are usually file record areas but can be any desired data items in the File Section or the Working-Storage Section of the Data Division. You can only checkpoint data items in the Extended-Storage Section if your program runs in the CRE or is a native process. You must checkpoint any data items that are part of the program’s state—specifically the disk record that is about to be written, the terminal or tape record that was just read, and any data that is necessary to resume processing at the site of the checkpoint statement. The reason for checkpointing data items is to give the backup process all the information it needs to reexecute an I-O request if the primary process fails. Usually, you checkpoint a data item just before writing the data to disk. You can also use dataitem checkpointing to eliminate the need for the backup process to reexecute an I-O request. An example of this is an entry received from a terminal. You checkpoint the data item received from a terminal by a READ statement immediately after executing the READ statement to minimize the possibility that the operator has to reenter data. Sync Blocks A sync block contains control information about the current state of a disk file (such as the current value of the file pointers). The purpose of checkpointing the sync block is twofold: • • To ensure that a write operation is not duplicated when a backup process takes over from its primary process To pass the current file pointers’ values to the file system of the backup processor When a process executes a checkpoint of a sync block, the operating environment passes the information in the sync block to the file system of the backup processor. The reason for preventing duplicate operations is illustrated in Figure 32-3. In Figure 32-3, a primary process completes a sequential write operation (that is, append to end of file) successfully, but fails before a subsequent checkpoint to its backup process. On the takeover from the primary process, the backup process reexecutes the operations just completed by the primary process. If the write operation was performed as requested, it duplicates the record, but at the new end-of-file location. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32- 7 Fault-Tolerant Processes Checkpointing Figure 32-3. Duplication in Takeover Restart point (c) Checkpoint data and sync block x Write log-rec *** FAILURE OF PRIMARY PROCESS*** VST718.vsd To prevent such duplicate write operations by the backup process, you must specify a nonzero SYNCDEPTH parameter in the OPEN statement. This action allows the file system to record the completion status of each input-output operation. If the backup process requests an operation already completed by the primary process, the file system recognizes this condition. Then, instead of performing the operation, the file system returns the recorded completion status of the operation to the backup process. If, however, the requested operation has not been performed, it is performed and the completion status is returned to the backup process. The course of action taken by the file system is completely invisible to the backup process. The file system can save the completion status of the latest 15 disk-file operations and relate those completions with up to 15 operations requested by a backup process upon takeover from a failed primary process. (For $RECEIVE or other processes handled as files, the number of saved completion status values is 255.) Use the SYNCDEPTH parameter to specify the maximum number of completion status values that the file system is to save. The SYNCDEPTH value is typically the same as the maximum number of operations that write to a file without an intervening checkpoint of the file’s sync block. The default SYNCDEPTH value is 1. In a Pathway application, the SYNCDEPTH value must be 1. General Rules You can checkpoint the entire data area of the program and checkpoint each file after the execution of each statement in your program, but this places a tremendous burden on the interprocess message system and degrades the performance of your process and all processes executing on the same processors as your process pair. Minimize the number of checkpoints in a processing loop and the amount of data checkpointed for each CHECKPOINT statement. One approach is to checkpoint only the items necessary to establish a restart point. Verify that you have captured all necessary data items (you might want to group them in the Data Division). Also, if you checkpoint the contents of a record area, verify that the remainder of the data storage is still valid in case of a takeover by the backup process. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32- 8 Fault-Tolerant Processes Using the Fault-Tolerant Facility When your program performs a series of updates to one or more disk files, you can combine checkpoints to reduce system overhead. Structure your program so that the series of write operations necessary to update a file are performed in a group. For each file to be checkpointed in this manner, the sync depth must equal the maximum number of write operations that occur between checkpoint operations (CHECKPOINT, OPEN, or CLOSE statements). Then, when a file is about to be updated by performing that collection of write operations, the file’s sync block and its record areas must be checkpointed. In any case, ensure the integrity of all data by checkpointing. Rules for Servers to Follow With Fault-Tolerant Requesters If a server is handling requests from a requester that is running as a process pair, there is an important rule for the server to follow for checkpointing between a $RECEIVE READ-WRITE pair for a nonretryable request. A nonretryable request is a task that must not be automatically reexecuted if the requester’s backup process takes over. For example, if a failure occurs after a request to deduct taxes from a paycheck is executed, reexecution would cause double deduction. This operation must be done only once for each calculation of the taxes; thus, it is a nonretryable request. The rule for this case is: Have at least one of the CHECKPOINT statements include the file-name (from name of the file description entry) of the output file assigned to $RECEIVE—the file-name with which the write operation is associated. Using the Fault-Tolerant Facility To use the fault-tolerant facility, your source program must include a NONSTOP directive and STARTBACKUP and CHECKPOINT statements and its process must have a name. Topics: • • • • NONSTOP Directive STARTBACKUP and CHECKPOINT Statements OPEN and CLOSE Statements PROGRAM-STATUS Data Item NONSTOP Directive To enable the fault-tolerant facility, you must specify the NONSTOP directive before the Procedure Division of the first program unit in the source text. STARTBACKUP and CHECKPOINT Statements Normally, the STARTBACKUP statement is executed once at the beginning of run-unit execution (after the opening of the files) to establish a process pair. A CHECKPOINT statement is then executed at critical points during processing to pass (that is, checkpoint) information to the backup process. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32- 9 Fault-Tolerant Processes Using the Fault-Tolerant Facility OPEN and CLOSE Statements If a process is executing as a process pair (that is, the primary process has executed a STARTBACKUP statement), checkpointing occurs automatically when any OPEN or CLOSE statement executes and when the backup process is established. The execution of STARTBACKUP and CHECKPOINT statements sets the PROGRAMSTATUS variable to indicate the outcome of the checkpointing operation. The execution of OPEN and CLOSE statements (because they establish takeover points) also sets the PROGRAM-STATUS variable. Following an OPEN or CLOSE of a file by the primary process, the sync blocks of all other files in the backup process become invalid. If the SYNCDEPTH exceeds 1, you must checkpoint both the record and the sync block of each file other than the one that was opened or closed before executing the next WRITE statement. PROGRAM-STATUS Data Item Each HP COBOL run unit contains a four-digit data item called PROGRAM-STATUS, shown in Figure 32-4. When a process is running as a process pair, this item is set by the HP COBOL fault-tolerant facility to indicate the outcome of the execution of a STARTBACKUP, OPEN, CLOSE, or CHECKPOINT statement. Figure 32-4. PROGRAM-STATUS Data Item 01 PROGRAM-STATUS. 05 PROGRAM-STATUS-1 05 PROGRAM-STATUS-2 PIC X. PIC X(3). If one of options 0 through 2 of the STARTBACKUP statement is used (that is, if the HP COBOL fault-tolerant facility monitors the backup process), then the possible values of PROGRAM-STATUS for any execution of a STARTBACKUP, CHECKPOINT, OPEN, or CLOSE statement and their meanings are as shown in Table 32-1. Table 32-1. Values for PROGRAM-STATUS When STARTBACKUP Has Option 0, 1, or 2 (page 1 of 2) PROGRAM-STATUS Value Meaning 0000 No error 0100 Takeover by backup, primary stopped 0101 Takeover by backup, primary aborted 0102 Takeover by backup, primary processor module failed 0103 Takeover by backup, primary called CHECKSWITCH 1000 Backup processor down 2nnn Communication error; nnn = file system error number 3nnn CHECKOPEN failure; nnn = file system error number HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -10 Fault-Tolerant Processes Using the Fault-Tolerant Facility Table 32-1. Values for PROGRAM-STATUS When STARTBACKUP Has Option 0, 1, or 2 (page 2 of 2) PROGRAM-STATUS Value 4nnn Meaning In the non-CRE environment, 4nnn indicates a NEWPROCESS failure. If nnn is less than or equal to 255, nnn is the file system error associated with the disk file where the loadfile was to be found. If nnn is one of these values, the cause of the failure is: 901 = Undefined externals 902 = No PCB available 904 = Unable to allocate map 905 = Unable to get virtual disk space 906 = Illegal file format 907 = Unlicensed privileged program 910 = Unable to communicate with system monitor process Errors in the 900 range are not likely to occur and are generally symptomatic of a system or fault-tolerant facility problem (typically, a shortage of some resource). In the CRE, 4nnn indicates a PROCESS_CREATE_ failure. For more information, see the Guardian Procedure Calls Reference Manual. 5000 Too many failure-restart cycles (takeovers by backup) or a logic error in program 6000 Parameter or logic error If option 3 of the STARTBACKUP statement is specified (that is, if your program monitors the backup process), then the possible values of PROGRAM-STATUS are as shown in Table 32-2. Table 32-2. Values for PROGRAM-STATUS When STARTBACKUP Has Option 3 First Digit of PROGRAM-STATUS Statement 0 1 2 3 4 5 6 STARTBACKUP Yes Yes Yes Yes Yes No Yes CHECKPOINT Yes Yes Yes No No No Yes OPEN Yes Yes Yes Yes No No No CLOSE Yes Yes Yes No No No No If the primary process fails and a proper takeover occurs, PROGRAM-STATUS is set to a take-over status values (such as “01nn ”) when the backup process begins executing. Successive checkpoints set PROGRAM-STATUS to other values (such as “1000”). HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -11 Fault-Tolerant Processes Using the Fault-Tolerant Facility The action your program should take in response to an exception status (a status other than “0000”) depends upon your application and the location of the error in your HP COBOL program. A takeover might need special processing. Most of the other status values indicate a program coding problem or a system configuration problem. Report the latter problem to the appropriate authority for your system. How far and whether processing should continue following a nontakeover status is a subject for careful analysis. If a checkpoint failure occurs (that is, status “1000”, “2nnn ”, or “3nnn ”), the backup process might remain in an invalid state; therefore, the HP COBOL fault-tolerant facility stops the backup process if such a failure occurs. If the STARTBACKUP option 0, 1, or 2 was specified (signifying that the HP COBOL fault-tolerant facility is to monitor the backup process), the facility tries to restart the backup process at the next execution of the CHECKPOINT statement. If the checkpoint failure persists for 10 restart cycles, the HP COBOL fault-tolerant facility stops reestablishing a backup process and sets PROGRAM-STATUS to “5000.” Example 32-1. Key Parts of Fault-Tolerant HP COBOL Program (page 1 of 2) ?NONSTOP ?SAVE PARAM * * Compiler directive specifies that the program is to be compiled for execution as a process pair. FILE SECTION. FD TEST-FILE LABEL RECORD IS OMITTED RECORD CONTAINS 100 CHARACTERS DATA RECORD IS TEST-REC. 01 TEST-REC. 05 REC-NUM PIC 9(4). 05 ALTKEY-1 PIC X(5). 05 ALTKEY-2 PIC X(5). ... WORKING-STORAGE SECTION. 01 CKPT-DATA. * This defines pertinent control information that is * checkpointed to the backup process 05 KEYNUM PIC 9 VALUE 0. 05 CURR-REC PIC 9(4). 05 CR REDEFINES CURR-REC. 10 FILLER PIC XX. 10 CR-1 PIC 9. 10 CR-2 PIC 9. 05 OLD-BASE PIC 9(4). 05 NEW-BASE PIC 9(4) VALUE 0. 77 BCPU PIC S9(4) COMP VALUE -1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -12 Fault-Tolerant Processes Designing Programs for the Fault-Tolerant Facility Example 32-1. Key Parts of Fault-Tolerant HP COBOL Program (page 2 of 2) PROCEDURE DIVISION. CENTRAL SECTION. ... OPEN I-O TEST-FILE SHARED SYNCDEPTH 1. PERFORM GET-CPUNUM. STARTBACKUP BCPU, 1. IF PROGRAM-STATUS NOT = "0000" DISPLAY "STARTBACKUP UNSUCCESSFUL, STATUS = ", PROGRAM-STATUS. STOP RUN. PERFORM UPDATE-RECS UNTIL UPDATES-DONE. ... GET-CPUNUM. ENTER "GETBACKUPCPU" IN COBOLLIB GIVING BCPU. IF BCPU < 0 OR BCPU > 15 DISPLAY "BACKUP CPU INVALID, RUNNING WITHOUT BACKUP". UPDATE-RECS. ... READ TEST-FILE WITH LOCK. ... CHECKPOINT TEST-FILE, TEST-REC, CKPT-DATA. IF PROGRAM-STATUS > "0000" AND PROGRAM-STATUS < "1000" DISPLAY "Backup took over". REWRITE TEST-REC WITH UNLOCK. ... After the program is compiled and debugged, it must be run as a named process (see Process Names). Designing Programs for the Fault-Tolerant Facility You must design a program to use the fault-tolerant facility. It is very difficult, if not impossible, to retrofit the use of the fault-tolerant facility to an existing program. A checkpoint is a location in the program at which processing resumes when a takeover occurs. All data from the primary process that is part of the program state must be checkpointed to the backup process if the takeover is to succeed. You must checkpoint before any nonretryable operation, such as a write to disk. You can (for operator convenience) checkpoint after a read from a terminal. You can (for programming convenience) checkpoint after a read from tape. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -13 Fault-Tolerant Processes Debugging Programs That Use the Fault-Tolerant Facility If your SYNCDEPTH exceeds one, and you open or close a file during checkpointprotected operation, you must checkpoint the sync blocks and record areas of all other files before the next nonretryable operation. If you need to checkpoint data that is in the Extended-Storage Section, you must compile your program to run in the CRE. Debugging Programs That Use the Fault-Tolerant Facility Debugging a program that uses the fault-tolerant facility requires at least as careful an analysis as designing the program. This list of suggestions is not exhaustive. • • • • Test the program thoroughly as a simple batch job. You might create files of transactions that the job must successfully process before you try testing the faulttolerance mechanisms. You can have the program read the files instead of having the program read from $RECEIVE. You can compile your program with STARTBACKUP and CHECKPOINT statements in place, but disable them for batch testing by running the program with the run-time parameter NONSTOP OFF. With NONSTOP OFF, the program does not attempt to execute the STARTBACKUP and CHECKPOINT statements. To establish the run-time parameter, use the TACL command PARAM (or the SMU routine PUTPARAMTEXT or SMU_Param_PutText_ if you use a COBOL process to start your batch test programs). When you are convinced that the program works without being fault tolerant, start testing the fault tolerance. Execute the program as a process pair, and use a symbolic debugger to set breakpoints at which you stop the primary process. You can set different breakpoints in the primary and backup processes to determine whether the backup process takes over properly. When all controlled testing is complete, obtain the use of a dedicated system and try full integrated testing in which you run the application as a process pair and stop one of the two processors on which the application is running. TMF TMF simplifies the task of maintaining data consistency for distributed databases that are being updated by several independent processes. TMF was developed to help solve two problems faced by designers of database processing applications: • • What happens if a transaction starts to change a database and fails to complete all of its changes? How can a database be recovered after a catastrophic, multicomponent system failure? HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -14 Fault-Tolerant Processes Concepts Before TMF was available, the answer to the first question was to write application code to back out partial transactions and restore the affected parts of the database to the condition they were in when the failed transaction began. Further, this application code had to be fault tolerant to overcome possible single points of failure. The answer to question two was to stop the system periodically and make tape or disk backups. Then if a catastrophic failure occurred, you could restore the database from the tape or disk and redo the transactions that had been done since the backup. This required considerable design and coding effort, particularly if you had to do it for several applications. TMF has packaged the solution to these two questions of backout and recovery. TMF automatically backs out incomplete transactions and provides a mechanism for periodically taking online dumps and a roll-forward procedure to automate the repetition of post-backup transactions. Topics: • • • • • Concepts Designing Programs for the TMF Subsystem The TMF Subsystem and Requester Screen Transactions The TMF Subsystem for Batch Jobs Debugging Programs That Use the TMF Subsystem Concepts The basic concepts of TMF are: • • • • • • • Transactions in General Multiple-File Transactions Multiple Changes to a Single File Defining Transactions Audit Trails Online Dump and Roll-Forward Recovery Record Locking Transactions in General A transaction is a multistep operation that affects the consistency of a database by transforming the database from one consistent state to a new consistent state. A transaction is also a unit of recovery. During a transaction, the database can be inconsistent. But either the entire transaction must happen, or none of it must happen. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -15 Fault-Tolerant Processes Concepts Each transaction has a unique transaction identifier. The identifier includes information about the starting time of the transaction. If your transaction involves more than one file or if the single file it involves is available to other transactions, you can introduce inconsistency into the database. Multiple-File Transactions Suppose your process is maintaining a corporate personnel system in which each department has its own file of information. You want to move an employee’s record from one file to another. It does not matter whether the process writes the record in the new file before deleting it from the old file or the reverse. During the interval between the two events, the database is inconsistent. The employee record is either absent from the database or present in two places. Multiple Changes to a Single File Suppose that the corporate personnel system does not use multiple files, but a single file. If you want to move an employee’s record from one department’s portion of the file to another department’s portion of the file, the same problem arises as that with multiple files. If the record is deleted from one place in the file and written to another place in the file, there is an interval during which the database is inconsistent. Defining Transactions Because you, as the application programmer, are in the best position to define what constitutes a transaction, TMF gives you the authority to specify the beginning and the end of the transaction. In a Pathway application, the SCREEN COBOL terminal program uses the BEGINTRANSACTION and END-TRANSACTION statements for this purpose. In TAL, FORTRAN, and HP COBOL programs outside of the Pathway environment, you must call the operating system routines BEGINTRANSACTION and ENDTRANSACTION explicitly. If a terminal program determines that a transaction cannot or must not complete, it uses the SCREEN COBOL ABORT-TRANSACTION statement to instruct TMF to back it out and not retry it. If a process written in TAL, FORTRAN, or HP COBOL needs to abort a transaction, it calls the ABORTTRANSACTION routine. If a terminal program determines that a transaction should be aborted and retried as a new transaction (because of a locking contention problem, for example), it can use the SCREEN COBOL RESTART-TRANSACTION statement to initiate the operation. The TAL, FORTRAN, or HP COBOL process must explicitly use the ABORTTRANSACTION routine and handle its own restarting. After TMF is informed of the boundaries of a transaction, it can assure that either the entire transaction is performed or none of it is performed. TMF does this by using audit trails. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -16 Fault-Tolerant Processes Concepts Audit Trails An audit trail is a set of disk files in which a record is kept of before-images and afterimages of all records changed by each transaction that occurs in a certain file. A file is described as audited when it has an audit trail. In TMF, every disk file in which records are to be changed can be audited. If a disk is involved in transactions whose failure could leave the database in an inconsistent state, that disk file should be audited. On NonStop systems, under DP2 (Disk Process 2), all disks permit TMF auditing. To instruct TMF to audit a file, use the attribute AUDITED, which you set with the FUP command SET or ALTER. The AUDITED attribute is an attribute of the disk file itself; an HP COBOL program is unaware of and cannot affect this attribute. Every disk operation that changes the contents of a database protected by TMF is recorded in an audit trail. The before and after values of the information are both recorded, and the database is changed. If the transaction does not complete, TMF backs out the transaction—replaces the changed value with the previous value. You can specify that some files in a transaction are audited and some are not audited; however, this practice is risky. If a server updates an unaudited file having alternate keys, a single-component failure can interrupt a transaction between the updating of the prime key and alternate keys. In this case, the prime and alternate keys are inconsistent. If you do not protect such a file with auditing, you must code the server as a process pair to protect the consistency of the keys. The TMF subsystem requires audit trails for both transaction backout and roll-forward recovery. Eventually, the space required for audit trails can exceed available resources. For this reason, the audit trails must periodically be dumped to tape and their disk space thereby reclaimed. The system manager can configure TMF to automatically dump the audit trails. Even after a transaction is committed and its audit trail is no longer needed for backout, you might need the audit trail for a roll-forward recovery; therefore, tapes containing the dumped audit trails should be stored until you are certain that they are no longer needed. Online Dump and Roll-Forward Recovery The TMF subsystem can perform an online dump of the database periodically. The system manager is responsible for configuring TMF to do this at appropriate intervals. In the event of a total system failure, the operator directs TMF to restore the database from dump files. Then the operator directs TMF to conduct a roll-forward recovery to repeat the transactions that have occurred since the last online dump. A roll-forward recovery is the action of repeating each transaction that occurred to the database between the time of the last online dump and the time of the system failure. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -17 Fault-Tolerant Processes Designing Programs for the TMF Subsystem Record Locking As a transaction progresses in TMF, these types of resources must be locked: • • • Records that are changed or inserted into the database Records whose values affect the course of the transaction Keys of deleted records If you are going to rewrite a record in an audited file, you must first lock it when you read it. The TMF subsystem automatically locks records that are inserted and keys of records that are deleted. If a process attempts to rewrite a record in an audited file without that record being locked, the operation terminates with a file system error 80 (invalid operation attempted on audited file or non-audited disk volume) and file status code “30” (permanent error). If the process executes an UNLOCK operation on a record that was locked and modified in an audited file, TMF prevents the record from actually being unlocked until the transaction is completed or aborted. The TMF subsystem automatically unlocks these locked records at the end of a transaction, whether the process explicitly unlocks them or not. If there is any chance that the same logic will be run on audited files at some times and on non-audited files at other times, it is best to specify explicit unlocking operations. If you unlock a record in a nonaudited file in TMF or unlock a record that you locked but did not modify, the unlock operation occurs immediately. Designing Programs for the TMF Subsystem Like any other programming task, the most important part of designing for TMF is planning. Someone must plan the training, hardware, development, installation, testing, and operation. Before development can proceed, the designers must be trained in TMF. Eventually, some training is necessary for everyone involved. When the designers understand TMF, the project must be planned. Identify the transactions in the system. Do all transactions need to be protected by TMF? Are the transactions of appropriate size (number of SEND operations and number of screens involved)? The entire installation must be scheduled, whether you are converting to TMF, adding a TMF project on a system that is already using TMF, or creating a new system. Testing must be planned. Application code should be tested first without TMF, then with TMF. Operations and development groups must practice recovery procedures. Daily operation must be planned. Determine the frequency of online dumps and whether the dump is to tape or disk. Determine how the archival tapes or disks are transported to storage and how they are retrieved. Have a disaster recovery script. Practice disaster recovery occasionally. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -18 Fault-Tolerant Processes The TMF Subsystem and Requester Screen Transactions The TMF Subsystem and Requester Screen Transactions Because the server’s TMF protection is governed by the requester, you need to coordinate the designs of the two. If the terminal user needs to traverse more than one screen for each transaction, you must consider how to package the transaction. Transactions that consist of several screens are easy and straightforward to program but can be expensive. If a transaction spans several screens, it can keep records locked for long periods; however, if you design for single-screen transactions, you might have some problems when a series of screens makes up a single conceptual transaction. You recover from a failure during the series by adopting a strategy to protect records by allocating a field to mark the record “in use.” Then other transactions can read the record but agree not to attempt to change it. This mechanism puts more responsibility on the designer and the maintenance staff. The “in-use” field identifies the terminal that is using the record so that, in the event of major failure and recovery, the restored system can resume properly. You can also collect information from the database without locking records and pass the information back to the requester. Then, when the requester makes its final request to update the database, it can send the server the before and after versions of the data, and the server can read and lock the records. Then the server can verify that the records have not been changed and can rewrite the new records, or the server can respond to the requester with the new information and have the requester ask the terminal operator what to do with the record in its revised form. This strategy increases the context that is carried by the requester, which affects performance. The TMF Subsystem for Batch Jobs The TMF subsystem is appropriate for any batch job where you cannot afford the time to rerun it if it fails near its completion. Suppose your system must be available to process interactive transactions daily from 6 AM to 9 PM, and overnight a 5-hour batch job updates the database. There are only 9 hours between the suspension and resumption of interactive work. In that 9 hours, you must dump the database to tape and then update it. If the update fails, you must reload from the tape and repeat the update. There is not enough time to do this if the failure occurs a few hours into the batch update. In such a batch update, the update cannot be one big transaction. Not only must the audit trail for each transaction remain on disk until the transaction is complete, but backing out the incomplete transaction takes about as long as the transaction had been running at the time of the failure; however, the I-O overhead of making each batch transaction a TMF transaction might be burdensome. It is best to cluster about 20 to 100 batch transactions as one TMF transaction. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -19 Fault-Tolerant Processes Debugging Programs That Use the TMF Subsystem Debugging Programs That Use the TMF Subsystem There are no debugging tools specific to TMF application debugging. You can use a symbolic debugger, to set breakpoints in both SCREEN COBOL terminal programs and in server programs. If the symbolic debugger that you use can accept its commands from an OBEY command file, you can create a script that interrupts transactions at various points in the requester and the server and tests the recovery mechanisms. HP COBOL Manual for TNS and TNS/R Programs —522555-006 32 -20 33 Migrating TNS Programs to Native Programs Note. This section applies to migrating TNS HP COBOL programs to TNS/R or TNS/E HP COBOL programs. To migrate TNS/R HP COBOL programs to TNS/E HP COBOL programs, see the COBOL Manual for TNS/E Programs. HP NonStop Series/RISC and HP NonStop Series/Itanium enable you to write programs that are fully optimized for NonStop Series/RISC and NonStop Series/Itanium systems such as HP NonStop systems. The term “native” means the program uses the process, memory, and instruction set architectures that are native to RISC and Itanium processors. A TNS program is “nonnative” in that it uses the process, memory, and instruction set architectures of CISC processors. For further explanation of native mode and native tools, see the introduction to either the TNS/R Native Application Migration Guide or the TNS/E Native Application Conversion Guide. HP provides these compilers for HP COBOL source programs: Compiler Objects Produced COBOL85 TNS NMCOBOL TNS/R ECOBOL TNS/E The NMCOBOL and ECOBOL compilers are available both on NonStop systems and on the PC. In this section, “NMCOBOL compiler” refers to both of the NMCOBOL compilers and “ECOBOL compiler” refers to both of the ECOBOL compilers, unless otherwise noted. Taking an HP COBOL source program that was compiled with the COBOL85 compiler and recompiling it with the NMCOBOL or ECOBOL compiler (so that the resulting object program runs in native mode) is called “migrating to native mode.” Migrating to native mode might require source program changes, both to the source code itself and to the way you develop and manage the source code. You can write HP COBOL source programs that can be compiled with any version of the COBOL85 compiler after product version D32 and, without source program changes, can also be compiled with any version of the NMCOBOL or ECOBOL compiler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33- 1 Migrating TNS Programs to Native Programs Reasons to Migrate Topics: • • • • • • • Reasons to Migrate Migrating HP COBOL Programs Data Alignment Source Program Changes Development and Management Changes Maintaining Common Source Code Using the Inspect and Visual Inspect Debuggers Reasons to Migrate A cost is associated with migrating from TNS HP COBOL to native HP COBOL, but in most cases, it is minor. You must decide whether the long-term return justifies the expense. The reasons to migrate to native HP COBOL are: • • Native object code does not need to be accelerated More code space The code space limit for a TNS HP COBOL program is 128 KB. For a native HP COBOL program, it is 32 megabytes. • More data space The data space limit of approximately 60 KB for the sum of all of the WorkingStorage Sections and File Sections of a TNS process does not apply to native HP COBOL programs. The Working-Storage Section and the Extended-Storage Section are the same in native HP COBOL. The small data area is limited to 32,768 characters, but you can use the LARGEDATA directive to put additional data items in the large data space. • Native SRLs (for TNS/R) or DLLs (for TNS/E) are consulted automatically If a TNS HP COBOL program calls utility routines, it must put the libraries that contain those routines (one or more of COBOLLIB, CBL85UTL, and CLULIB) on search lists (using the compiler directives SEARCH, LIBRARY, and CONSULT). HP COBOL Manual for TNS and TNS/R Programs —522555-006 33- 2 Migrating TNS Programs to Native Programs Migrating HP COBOL Programs For a native HP COBOL program, search lists are optional. If a program does not have search lists, or if the compiler cannot find an external reference in the files on the search lists: • TNS/R TNS/E The NMCOBOL compiler automatically searches the SRLs ZCOBSRL and ZCRESRL and then the file NMCOBEXT (the TNS/R equivalent of COBOLEXT). The ECOBOL compiler automatically searches the DLLs ZCOBDLL and ZCREDLL and then the file ECOBEXT (the TNS/E equivalent of COBOLEXT). ZCOBSRL contains the COBOL utility routines which, for TNS HP COBOL, resided in the system library, COBOLLIB, and CBL85UTL. ZCOBDLL contains the COBOL utility routines which, for TNS HP COBOL, resided in the system library, COBOLLIB, and CBL85UTL. ZCRESRL contains the run-time routines which, for TNS HP COBOL, resided in the system library or in CLULIB. ZCREDLL contains the run-time routines which, for TNS HP COBOL, resided in the system library or in CLULIB. Native routines Many new products and interfaces exist only in native mode (HP NonStop TUXEDO Release 2, for example). If you want your HP COBOL programs to interface with these products, you must migrate your HP COBOL programs to native mode. • Native COBOL cross compiler The native COBOL cross compiler enables you to build applications for NonStop systems on a personal computer (PC). The native COBOL cross compiler and related companion tools have been integrated into this environment that targets both the Guardian and OSS environments. For more information, see Section 34, Native COBOL Cross Compiler on PC. Migrating HP COBOL Programs The recommended procedure for migration from TNS HP COBOL to native HP COBOL is: 1. Change your program so that it runs in the CRE, if it does not already (see Section 18, HP COBOL CRE Support). 2. Verify that you have adequate system resources for the migrated programs. Native object files use approximately the same amount of disk space as accelerated object files. Native processes use approximately the same amount of processor memory as TNS processes running in accelerated mode. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33- 3 Migrating TNS Programs to Native Programs Migrating HP COBOL Programs 3. If necessary, change your source program (see Source Program Changes). To learn whether you must change your source program, compile it with the NMCOBOL or ECOBOL compiler, which will issue warnings when it encounters source constructs that it does not accept. Running the NMCOBOL or ECOBOL compiler with the new DIAGNOSE-85 directive is especially recommended. This directive causes the NMCOBOL or ECOBOL compiler to issue warnings when it encounters source constructs that could cause the program to produce different results than it would if it were compiled with the COBOL85 compiler. For a complete description of the DIAGNOSE-85 directive, see DIAGNOSE-85 and NODIAGNOSE-85. 4. If your program calls TNS programs, migrate them to native mode. Native programs cannot call TNS programs, and TNS/R and TNS/E programs cannot call each other. Migrate your program and the programs that it calls to either TNS/R or TNS/E, not a combination of the two. For general migration information, see the TNS/R Native Application Migration Guide For this list of languages, follow these instructions. The last one, Data Alignment, applies to several languages. “Native” means either TNS/R or TNS/E, whichever you have chosen. ° HP C and HP C++ Recompile HP C and HP C++ programs with the native HP C and HP C++ compilers, respectively. Specify the SYMBOLS pragma when recompiling an HP C or HP C++ program that your HP COBOL program references in a CALL or ENTER statement (so that the native compiler can validate calls and parameters to the HP C or HP C++ module). For information on tools that can help you migrate HP C or HP C++ programs to native mode, see the C/C++ Programmer’s Guide. ° TAL Convert TAL programs to pTAL (see the pTAL Conversion Guide). Some CRE library routines might no longer exist, so you might have to change calls to them. Also, if you want to reference an object in a CALL or ENTER statement, you must compile your pTAL program with symbols. If any of your TAL programs use the FORTRAN convention for determining the length of a string parameter (that is, if they use the ENTER routine and do not specify the language TAL), convert them to use another method (for example, use the string :length convention or pass the length as a separate parameter). HP COBOL Manual for TNS and TNS/R Programs —522555-006 33- 4 Migrating TNS Programs to Native Programs ° Migrating HP COBOL Programs FORTRAN and Pascal There are no native FORTRAN or Pascal compilers. Rewrite FORTRAN and Pascal programs in native HP C, native HP C++, native HP COBOL, or pTAL. You need not use the same language for all of them. ° Data Alignment The COBOL85 and NMCOBOL compilers generate code with the same data alignment. You need not change any data alignment directives before migrating a TNS HP COBOL program to native HP COBOL. You need not regenerate Data Definition Language (DDL) source files that TNS HP COBOL and native HP COBOL programs share. The ECOBOL compiler aligns each level-01 item and each level-77 item on a physical 8-byte boundary, not on a physical 2-byte boundary as the COBOL85 and NMCOBOL compilers do. Offsets from the containing level-01 or level-77 item are the same in all three compilers. The difference in alignment of level-01 and level-77 items for the ECOBOL compiler will not affect a program unless the program depends on the relative placement in memory of distinct level-01 or level-77 items. If your program depends on such relative placement, correct it. By default, the TNS compilers for HP C, HP C++, and TAL generate code with different data alignment than the corresponding native compilers for HP C, HP C++, and pTAL. To migrate a TNS HP C, TNS HP C++, or TAL program to native mode, you must do one of: ° If DDL was not used, use SHARED2 pragmas in pTAL programs and CSHARED2 pragmas in native HP C programs. ° If DDL was used, regenerate DDL source files that TNS and native programs share. DDL adds pragmas to ensure that all compilers generate code with the same data alignment. For more information, see the TNS/R Native Application Migration Guide. See also Data Alignment. 5. (Optional) Put converted routines in a user library. If you want to put the routines that you converted to native mode in Step 4 in a user library (instead of in a TNS user library, which your program can no longer use), follow the directions in User Library. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33- 5 Migrating TNS Programs to Native Programs Data Alignment 6. Compile your source program with the NMCOBOL or ECOBOL compiler. For the Guardian environment, see Running the Compiler. For the OSS environment, see Section 19, Using HP COBOL in the OSS Environment. The NMCOBOL or ECOBOL compiler needs more symbol table space than the COBOL85 compiler does. If the NMCOBOL or ECOBOL compilation fails due to dictionary overflow, use the PARAM SYMBOL-BLOCKS command to increase the space available for the symbol table and embedded SQL/MP statements and then recompile. 7. Run the HP COBOL program that you compiled in Step 6. 8. If necessary, debug the program. The debuggers handle native processes slightly differently than TNS processes. The debuggers have environment registers for TNS processes, but not for native processes; therefore, variables might remain in memory and never be written to memory—it depends on compiler optimization level. Data Alignment On TNS systems, a word is 16 bits. The TNS instruction set includes data access instructions that use 32-bit byte addresses that must be even-byte aligned (that is, aligned 0 modulo 2) for correct operation. In TNS mode and accelerated mode, addresses that are odd-byte aligned (that is, aligned 1 modulo 2) are called misaligned. TNS processors consistently “round down” misaligned addresses (that is, they ignore the low-order bit). TNS/R and TNS/E processors handle the misaligned addresses of TNS programs inconsistently, rounding down some but not others and behaving differently in TNS mode and accelerated mode. Compilers cannot catch misaligned addresses that are computed at run time. The behavior of TNS programs with misaligned addresses on TNS/R and TNS/E processors is almost impossible to predict. If you are not sure that your program has only aligned addresses, you can use the tracing facility to detect whether programs are using misaligned pointers and, if so, where. You should then change the programs to avoid misalignment. The round-downs occur only in TNS-compiled programs, not in TNS/R and TNS/E native programs. In native mode, unexpected misalignments can slow down a program, but they cannot cause errors. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33- 6 Migrating TNS Programs to Native Programs Misalignment Tracing Facility In addition to HP COBOL, the data misalignment issue might affect programs that use this NonStop software. If you use these products, see the appropriate document: Product T Number Document Accelerator T9276 Accelerator Manual Data Alignment Addendum TNS C T9255 C/C++ Programmer’s Guide TNS C++ T9541 TNS c89 T8629 TNS/R pTAL T9248 pTAL Reference Manual TNS TAL T9250 TAL Programmer’s Guide Data Alignment Addendum Topics: • • • Misalignment Tracing Facility Misalignment Handling Causes of Misalignment in HP COBOL Programs Misalignment Tracing Facility The misalignment tracing facility is enabled or disabled on a system-wide basis (that is, for all processors in the node). By default, it is enabled (set to ON). It can be disabled (set to OFF) only by the persons who configure the system, using the Subsystem Control Facility (SCF) attribute MISALIGNLOG. Instructions are in the SCF Reference Manual for the Kernel Subsystem. Note. HP recommends that the MISALIGNLOG attribute be left ON (its default setting) so that any process that is subject to rounding of misaligned addresses will generate log entries, facilitating diagnosis and repair of the code. Only if the volume of misalignment events affects performance should this attribute be turned OFF. When a misaligned address causes an exception that TNS processor product versions prior to G06.17 would have rounded down, the tracing facility traces the exception. Note. The tracing facility does not count and trace every misaligned address, only those that cause round-down exceptions. Other accesses that use misaligned addresses without rounding them down do not cause exceptions and are not counted or traced. Also, only a periodic sample of the counted exceptions is traced using its own EMS event messages. While a process runs, the tracing facility: • • Counts the number of misaligned-address exceptions that the process causes (the exception count) Records the program address and code-file name of the instruction that causes the first misaligned-address exception HP COBOL Manual for TNS and TNS/R Programs —522555-006 33- 7 Migrating TNS Programs to Native Programs Misalignment Handling Because a process can run for a long time, the tracing facility samples the process (that is, checks its exception data) periodically (approximately once an hour). If the process recorded an exception since the previous sample, the tracing facility records an entry in the EMS log. If the process ends and an exception has occurred since the last sample, the operating system produces a final Event Management Service (EMS) event. The EMS event includes: • • The process’s exception count Details about one misaligned-address exception, including the program address, data address, and relevant code-file names Sampling is short and infrequent enough to avoid flooding the EMS log, even for a continuous process with many misaligned-address exceptions. One sample logs a maximum of 100 events, and at most one event is logged for any process. If misaligned-address exceptions occur in different periods of a process, the operating system produces multiple EMS events for the same process, and these EMS events might have different program addresses. For more information about EMS events or the EMS log, see the EMS Manual. Misalignment Handling Misalignment handling is determined by these SCF attributes, which are set systemwide (that is, for all processors in the node) by those who configure the system: • • • MISALIGNLOG TNSMISALIGN NATIVEATOMICMISALIGN (does not apply to TNS HP COBOL programs) MISALIGNLOG enables or disables the tracing facility (see Misalignment Tracing Facility). TNSMISALIGN applies to all programs running in TNS mode or accelerated mode. NATIVEATOMICMISALIGN applies to calls to pTAL atomic functions in programs running in TNS/R and TNS/E native mode. Nonatomic accesses in TNS/R and TNS/E native mode are always NOROUND (for the definition of NOROUND, see Table 33-1). Table 33-1 lists and describes the possible settings for TNSMISALIGN. Each setting represents a different misalignment handling method. For more information about TNSMISALIGN, see the SCF Reference Manual for the Kernel Subsystem. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33- 8 Migrating TNS Programs to Native Programs Misalignment Handling Table 33-1. TNS Misalignment Handling Methods Method Description ROUND (default)* After rounding down a misaligned address, the system proceeds to access the address, as done in G06.16 and earlier RVUs. FAIL Instead of rounding down a misaligned address and proceeding to access the target, the operating system considers the instruction to have failed. For a Guardian process, this failure generates an Instruction Failure trap (trap #1). By default, this trap causes the process to go into the debugger, but the program can specify other behavior (for example, process termination or calling a specified trap-handling procedure). For information about trap handling, see the Guardian Programmer’s Guide. For an OSS process, this failure generates a SIGILL signal (signal #4). By default, this signal causes process termination, but the program can specify other behavior (for example, entering the debugger or calling a specified signal-handler procedure). The signal cannot be ignored. For information about signal handling, see the explanation of the sigaction() function in the Open System Services System Calls Reference Manual. NOROUND The system uses the operand’s given odd address (not rounded down) to complete the operation. If the operation is an atomic operation, atomicity is no longer guaranteed. * Use this method on production systems to avoid changing the semantics of old TNS programs. FAIL could cause possibly fatal Instruction Failure traps in faulty TNS programs. NOROUND might change the semantics of some faulty programs. The method that you choose does not apply to every misaligned address, only to those that would have been rounded down in RVUs prior to G06.17. Note. ROUND and NOROUND misalignment handling are both intended as temporary solutions, not as a substitute for changing your program to ensure that it has only aligned addresses. Programs that depend on NOROUND misalignment handling cannot be safely migrated to all present and future NonStop platforms or to systems configured with ROUND or FAIL misalignment handling. Programs that depend on ROUND misalignment handling cannot be safely migrated “as is” to future NonStop platforms or to systems configured with NOROUND or FAIL misalignment handling. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33- 9 Migrating TNS Programs to Native Programs Causes of Misalignment in HP COBOL Programs Causes of Misalignment in HP COBOL Programs In native HP COBOL programs, misaligned addresses might slow down program execution, but the misaligned addresses are never “rounded down” and do not cause the program to terminate abnormally. In TNS HP COBOL programs, reference parameters and the targets of pointers to BINARY or COMPUTATIONAL data items must be aligned on 2-byte memory boundaries for correct operation. The results of odd-byte addresses depend on the specific NonStop server and the system configuration, but they might include erratic “rounding down” and abnormal program termination. In a TNS HP COBOL program, some actions that can cause misaligned addresses are: • Using the POINTER data type and explicit pointer operations These are rarely used HP extensions to COBOL. Their potential problems are the same as those of pointers and pointer operations in C/C++ and TAL (see C/C++ Programmer’s Guide and TAL Programmer’s Guide Data Alignment Addendum). • Using incompatible descriptions of corresponding REFERENCE parameters in a calling program and a called program This situation is the most likely cause of misaligned addresses in HP COBOL programs. If the called program's Linkage Section describes a REFERENCE parameter as a group containing BINARY or COMPUTATIONAL data items, the calling program must describe the corresponding actual parameter in an equivalent way. If identical descriptions are not possible, the calling program must describe the actual parameter as a level-01 or level-77 data item so that it is aligned. The calling program must not describe the actual parameter as an unstructured alphanumeric data item within a larger group, because then the compiler cannot prealign the actual parameter as needed. See Example 33-1. • Passing an alphanumeric data item or a reference modifier as an actual parameter If the calling program passes an alphanumeric item or a reference modifier (that is, a substring from a larger item) as an actual parameter, the called program has two choices: • ° Describe the corresponding formal parameter as an alphanumeric item (in the Linkage Section) ° Copy the bytes of the actual parameter to an aligned group before accessing any BINARY or COMPUTATIONAL data items Appending a sequence of objects inside an alphanumeric data item If an HP COBOL program appends a sequence of objects within an alphanumeric data item, it must ensure that BINARY or COMPUTATIONAL data items (and records containing them) are aligned on even-byte boundaries; otherwise, the program must move the objects back to an aligned record before using them. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -10 Migrating TNS Programs to Native Programs • Causes of Misalignment in HP COBOL Programs Using an explicit number for the offset of a record or for the size of a record This practice can cause misaligned addresses by overlooking the “implicit” filler bytes that the COBOL85 compiler adds to records: ° Within records, to ensure that every BINARY or COMPUTATIONAL field begins at an even-byte offset from the beginning of the structure ° At the end of any record that has an odd number of bytes, to give it an even number of bytes Example 33-1. Misalignment (page 1 of 2) Separately Compiled Main Program: IDENTIFICATION DIVISION. PROGRAM-ID. PROG-1. DATA DIVISION. EXTENDED-STORAGE SECTION. 01 aligned-group. * 7-word (14 byte) word-aligned group containing * 1-word, 2-word, and 4-word binary numeric items: 05 v16 PIC S9(4) COMP. 05 v32 PIC s9(9) COMP. 05 v64 PIC S9(18) COMP. 01 group-2. 05 aligned-buff PIC X(14). 05 big-buff PIC X(100). * aligned-buff and big-buff happen to start at even byte 05 pad PIC X. 05 unaligned-buff PIC X(14). * unaligned-buff starts at odd byte PROCEDURE DIVISION. main. legal-ways-always-work. CALL "PROG-2" USING aligned-group. wrong-type-works-when-even. MOVE aligned-group TO aligned-buff. CALL "PROG-2" USING aligned-buff. MOVE aligned-group TO big-buff(21:14). CALL "PROG-2" USING big-buff(21:14). wrong-type-fails-when-odd. MOVE aligned-group TO unaligned-buff. CALL "PROG-2" USING unaligned-buff. MOVE aligned-group TO big-buff(22:14). CALL "PROG-2" USING big-buff(22:14). END PROGRAM PROG-1. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -11 Migrating TNS Programs to Native Programs Causes of Misalignment in HP COBOL Programs Example 33-1. Misalignment (page 2 of 2) Subprogram: IDENTIFICATION DIVISION. PROGRAM-ID. PROG-2. DATA DIVISION. * * LINKAGE SECTION. Prog-2's reference containing 1-word, 01 indirect-group. 05 v16 PIC S9(4) 05 v32 PIC s9(9) 05 v64 PIC S9(18) parameter is a 16-bit-word-aligned group 2-word, and 4-word binary numeric items: COMP. COMP. COMP. PROCEDURE DIVISION USING indirect-group. main. * This subprogram expects its "indirect-group" parameter to begin * at an even-byte memory location, allowing use of TNS instructions * for loading or storing binary numbers. MOVE 16 to v16. MOVE 32 to v32. MOVE 64 to v64. * References to v16 and v64 misbehave if caller passes an * alphanumeric string beginning at an odd-byte memory location. * On TNS/R but not TNS, references to v32 usually behave as expected * even when an incorrect odd address is given. END PROGRAM PROG-2. The compiler’s PORT directive avoids misaligned address problems by inserting extra run-time code that copies all potentially misaligned operands to aligned temporary data items before using them. Note. This extra run-time code can slow down the program significantly. The PORT directive also removes “implicit” filler bytes from records, aligning BINARY or COMPUTATIONAL data items on any byte, except where the SYNCHRONIZED clause appears. The SYNCHRONIZED clause aligns BINARY and COMPUTATIONAL data items on 2-byte boundaries. Because it changes the default record layout, the PORT directive must be applied to either all or none of the modules and programs of all the compilation units of a single program (that is, the run unit) and to all other run units with which it shares data records. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -12 Migrating TNS Programs to Native Programs Source Program Changes Source Program Changes Source program changes fall into these categories: • • • • • General Migration Tasks Removal Required Possible Changes Required Removal Optional New Features (Optional) General Migration Tasks If your HP COBOL program calls obsolete or changed Guardian procedures, replace them. Change any calls to procedures affected by either the Kernel Managed Swap Facility (KMSF) or the native process architecture (for example, process creation calls). For more information on the obsolete or changed procedures, seethe TNS/R Native Application Migration Guide. If your HP COBOL program calls COBOL-environment versions of Saved Message Utility (SMU) routines, replace them with their CRE equivalents, which are listed in Table 13-11. Removal Required Remove these directives, statements, and library references from your HP COBOL source program before compiling it with the NMCOBOL or ECOBOL compiler. • ENV OLD Directive If you specify the ENV OLD directive, the NMCOBOL or ECOBOL compiler reports an error. Native HP COBOL programs always run in the CRE. • SQL Directive If your program contains SQL/MP statements, include the SQL directive in the NMCOBOL or ECOBOL compiler command line. Do not use the SQL option RELEASE1. • CHECKPOINT and STARTBACKUP Statements If you are migrating to TNS/R and your NMCOBOL compiler is earlier than RVU D46.00 or G06.00, software product revision T8107AAT (run-time library T8108AAR), it does not support process pairs, so you must remove any CHECKPOINT and STARTBACKUP statements. (In all other cases, you can leave CHECKPOINT and STARTBACKUP statements in your program.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -13 Migrating TNS Programs to Native Programs • Removal Required USE DEBUGGING Statement The 1985 COBOL standard classifies the USE DEBUGGING statement as obsolete, so you are advised not to use it even in TNS HP COBOL programs. The NMCOBOL and ECOBOL compilers do not recognize the USE DEBUGGING statement, and the COBOL85 compiler no longer recognizes the names of the debug items, which are: • ° ° ° ° ° ° ° DEBUG-CONTENTS DEBUG-ITEM DEBUG-LINE DEBUG-NAME DEBUG-SUB-1 DEBUG-SUB-2 DEBUG-SUB-3 GLOBAL Keyword in USE AFTER EXCEPTION Statement in Declaratives Portion Like the COBOL85 compiler, the NMCOBOL and ECOBOL compilers allow the GLOBAL keyword in USE AFTER EXCEPTION in the Declaratives Portion; however, if the GLOBAL keyword appears in that context and a nested program implicitly references the declarative by means of an I/O statement, the NMCOBOL or ECOBOL compiler issues an error message. If your TNS program has GLOBAL in a USE AFTER EXCEPTION in the Declaratives Portion—that is, if it has a global declarative exception procedure— duplicate the global declarative exception procedure in each nested program. This might require that you add the GLOBAL clause to each data item that the global declarative exception procedure uses, so that the copy in the nested program references it correctly. Remove any references to these TNS libraries, which NMCOBOL and ECOBOL compilers cannot use and do not need (see Native SRLs (for TNS/R) or DLLs (for TNS/E) are consulted automatically): • • • CBL85UTL COBOLLIB CLULIB Make these substitutions: With ... Replace ... TNS/R TNS/E COBOLEX0 NMCOBEX0 ECOBEX0 COBOLEX1 NMCOBEX1 ECOBEX1 COBOLEXT NMCOBEXT ECOBEXT HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -14 Migrating TNS Programs to Native Programs Possible Changes Required References to TNS libraries can appear in these contexts: • • • • • CONSULT directive LIBRARY directive SEARCH directive File-mnemonic clause of the SPECIAL-NAMES paragraph OF or IN clause of the CALL or ENTER statement Possible Changes Required The COBOL85, NMCOBOL, and ECOBOL compilers handle these items differently: • • • • Checkpointing Directives ENTER Statement Floating-Point Arithmetic Make any necessary changes to these items before compiling your HP COBOL source program with the NMCOBOL or ECOBOL compiler. Checkpointing The COBOL85 compiler automatically checkpoints data items that are stored directly on the stack in two or fewer bytes (that is, if they are level 01 or 77, in the WorkingStorage Section, and fewer than three characters long). The D44 product version of the NMCOBOL compiler does not checkpoint data items under any circumstances. If the D44 NMCOBOL compiler finds a CHECKPOINT statement, it ignores it and issues a warning. Beginning with the D46 and G06 product versions, software product revision T8107AAT (run-time library T8108AAR), the NMCOBOL compiler checkpoints only those data items that one or more CHECKPOINT statements specify explicitly. For more information on the CHECKPOINT statement, see CHECKPOINT. Directives • BLANK and NOBLANK For the COBOL85 compiler, BLANK is the default. For the NMCOBOL and ECOBOL compilers, NOBLANK is the default. For a complete description of these directives, see BLANK and NOBLANK. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -15 Migrating TNS Programs to Native Programs • Possible Changes Required CONSULT For the NMCOBOL compiler, each object-name in a CONSULT directive must designate a TNS/R native object file (otherwise the compiler reports an error). For the ECOBOL compiler, each object-name in a CONSULT directive must designate a TNS/E native object file (otherwise the compiler reports an error). If a native HP COBOL program references the object in a CALL or ENTER statement, the object must have been compiled with symbols. For a complete description of this directive, see CONSULT and NOCONSULT. • LARGEDATA For the COBOL85 compiler, the LARGEDATA directive determines whether individual data items are located in the user data space or the user extended space. The default value for the LARGEDATA directive’s parameter is 256. For the NMCOBOL compiler, the LARGEDATA directive determines whether individual data items are located in the small data area or the large data area. The default value for the LARGEDATA directive’s parameter is 64. The ECOBOL compiler ignores the LARGEDATA directive and issues a warning. For a complete description of this directive, see LARGEDATA. • LIBRARY The NMCOBOL and ECOBOL compilers ignore the LIBRARY directive and issue a warning. Instead of the LIBRARY directive, specify the name of your user library as explained in Specifying a User Library. For a complete description of this directive, see LIBRARY. • OPTIMIZE The NMCOBOL compiler handles OPTIMIZE 2 as if it were OPTIMIZE 1, because native COBOL does not support global optimization. The ECOBOL compiler handles OPTIMIZE 2 as the COBOL85 compiler does. OPTIMIZE 0 (no optimization) is recommended when you are debugging a program using the NMCOBOL or ECOBOL compiler. OPTIMIZE 1 (most optimizations) is recommended for production. For a complete description of this directive, see OPTIMIZE. • RUNNAMED The RUNNAMED directive works in the NMCOBOL and ECOBOL compilers only if you specify the new RUNNABLE directive (see RUNNABLE directive). For a complete description of this directive, see RUNNAMED. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -16 Migrating TNS Programs to Native Programs • Possible Changes Required SAVEABEND and NOSAVEABEND The SAVEABEND and NOSAVEABEND directives work in the NMCOBOL and ECOBOL compilers only if you specify the new RUNNABLE directive (see RUNNABLE directive). For a complete description of these directives, see SAVEABEND and NOSAVEABEND. • SEARCH For the NMCOBOL compiler, each object-name in a SEARCH directive must designate a TNS/R native object file (otherwise the compiler reports an error). For the ECOBOL compiler, each object-name in a SEARCH directive must designate a TNS/E native object file (otherwise the compiler reports an error). If a native HP COBOL program references the object in a CALL or ENTER statement, the object must have been compiled with symbols. For a complete description of this directive, see SEARCH and NOSEARCH. • SUBTYPE The SUBTYPE directive works in the NMCOBOL and ECOBOL compilers only if you specify the new RUNNABLE directive (see RUNNABLE directive). For a complete description of this directive, see SUBTYPE. ENTER Statement The language parameter of the ENTER statement is unnecessary, because the NMCOBOL and ECOBOL compilers can determine the language in which the program is written. If you do specify language, it must be HP C or TAL. If you specify TAL, the NMCOBOL or ECOBOL compiler requires a pTAL program (it does not accept TAL programs). If you specify FORTRAN or Pascal, the NMCOBOL or ECOBOL compiler gives an error message. (You must convert any FORTRAN, Pascal, or TAL programs that your HP COBOL program calls to native languages, as Step 4 of Migrating HP COBOL Programs explains.) Although a native HP COBOL program can use the ENTER statement to call HP C++ or pTAL programs, language cannot have the value HP C++ or pTAL. Floating-Point Arithmetic For floating-point arithmetic, the COBOL85 compiler can produce slightly different results than the NMCOBOL and ECOBOL compilers produce. This is most likely to cause problems for exponentiation with a negative or fractional exponent (such as 10**-3 or 2**0.3). You can avoid this problem by including the ROUNDED Phrase in statements that perform floating-point arithmetic. With the ROUNDED phrase, both compilers produce the same results. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -17 Migrating TNS Programs to Native Programs Removal Optional Removal Optional The NMCOBOL and ECOBOL compilers ignore these items, so you can (but need not) remove them from your source program. The NMCOBOL and ECOBOL compilers give a warning when they find these items, except as noted. • CODE and NOCODE directives The NMCOBOL and ECOBOL compilers do not produce an octal code listing. If you need to display an object file, use one of these utilities: • Compiler Utility Documentation NMCOBOL noft noft Manual ECOBOL enoft enoft Manual COMPACT and NOCOMPACT directives These directives determine whether BINSERV attempts to compact the code space of the target file. The NMCOBOL and ECOBOL compilers do not use BINSERV. • CROSSREF and NOCROSSREF directives The NMCOBOL and ECOBOL compilers do not produce a cross-reference listing. If you need one, use the appropriate utility from the table in CODE and NOCODE directives with the XREFPROC flag. • ENV COMMON directive Native HP COBOL programs always run in the CRE. The NMCOBOL and ECOBOL compilers do not issue a warning if you use this directive. • ENV LIBRARY directive Instead of using the ENV LIBRARY directive to build a TNS user library, use the directive UL to build a user library or the directive SHARED to build a DLL. • EXTENDED-STORAGE SECTION header Native HP COBOL does not need an Extended-Storage Section. The NMCOBOL and ECOBOL compilers handle any data items that are described in the ExtendedStorage Section as if they were described in the Working-Storage Section. The NMCOBOL and ECOBOL compilers do not issue a warning if you use the EXTENDED-STORAGE SECTION header. • • • FLOAT and NOFLOAT directives HEAP directive HIGHPIN directive Native HP COBOL programs always run at a high PIN. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -18 Migrating TNS Programs to Native Programs • Removal Optional HIGHREQUESTERS directive Native HP COBOL programs can always run as servers that communicate with requesters running at high PINs. • ICODE and NOICODE directives The NMCOBOL and ECOBOL compilers ignore these directives, warning you that they have done so. Use the INNERLIST and NOINNERLIST directives instead (see INNERLIST and NOINNERLIST directives). • LESS-CODE For the COBOL85 and NMCOBOL compilers, the LESS-CODE directive determines whether the program generates code that initializes the WorkingStorage Section or Extended-Storage Section or uses a system call to initialize the Extended-Storage Section. The ECOBOL compiler ignores the LESS-CODE directive and issues a warning. • LMAP and NOLMAP directives The LMAP and NOLMAP directives determine which load maps the compiler obtains from BINSERV. The NMCOBOL and ECOBOL compilers do not use BINSERV. • • NOCONSULT directive NONSTOP directive For the NMCOBOL compiler, native HP COBOL programs cannot be process pairs until RVU D46.00 and G06.00, software product revision T8107AAT (run-time library T8108AAR). • • NOSEARCH directive NOSQL directive This is the default for native HP COBOL programs. • SQLMEM directive The concept of extended memory does not exist in native mode. • TRAP2 and NOTRAP2 directives Native HP COBOL programs have traps set by default. • TRAP2-74 and NOTRAP2-74 directives Native HP COBOL programs cannot call COBOL 74 programs. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -19 Migrating TNS Programs to Native Programs New Features (Optional) New Features (Optional) You can (but need not) add these new features to your HP COBOL source program before you compile it with the NMCOBOL or ECOBOL compiler. • CALL-SHARED directive The CALL-SHARED directive generates shared code (PIC). See CALL-SHARED. For the ECOBOL compiler, this is the default. • DIAGNOSE-85 directive The DIAGNOSE-85 directive causes the NMCOBOL and ECOBOL compilers to issue warnings when they encounter source constructs that could cause the program to produce different results than it would if it were compiled with the COBOL85 compiler. For a complete description of the DIAGNOSE-85 directive, see DIAGNOSE-85 and NODIAGNOSE-85. • FMAP The FMAP directive causes the NMCOBOL and ECOBOL compilers to produce a source file map, which shows the fully qualified name and timestamp of the IN file and each file specified by a SOURCE directive or COPY statement. For more information, see FMAP. • INNERLIST and NOINNERLIST directives The INNERLIST and NOINNERLIST directives determine whether the NMCOBOL or ECOBOL compiler lists the mnemonic version of each source statement immediately after that source statement. For a complete description of the INNERLIST and NOINNERLIST directives, see INNERLIST and NOINNERLIST. • RUNNABLE directive The RUNNABLE directive causes the NMCOBOL or ECOBOL compiler to use one of these linkers to produce a loadfile if there were no compilation errors: Compiler Directive Linker Documentation NMCOBOL NON-SHARED (default) nld nld Manual CALL-SHARED or SHARED ld ld Manual eld eld Manual ECOBOL HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -20 Migrating TNS Programs to Native Programs Development and Management Changes This is not the default. If you run the NMCOBOL or ECOBOL compiler without the RUNNABLE directive and no compilation errors occur, you can produce a loadfile by running the appropriate linker separately. If you do this, you must specify these libraries: Linker Libraries Documentation nld ZCOBSRL ZCRESRL nld Manual ld ZCOBSRL ZCRESRL ld Manual eld ZCOBDLL ZCREDLL eld Manual The libraries reside in the active subvolume $SYSTEM.SYSnn. For instructions for determining the active subvolume, see the documentation. You must compile your native program with the RUNNABLE directive if you use the SAVEABEND, NOSAVEABEND, or SUBTYPE directive. For a complete description of the RUNNABLE directive, see RUNNABLE. • SHARED directive The SHARED directive generates shared code (PIC) for a DLL. See SHARED. Development and Management Changes The NMCOBOL and ECOBOL compilers and the native environment do not support these features of the COBOL85 compiler and the TNS environment. If your program development or management procedures depend on any of these features, you must change your procedures. • Overriding libraries specified at compile time In the TNS environment, you can specify libraries at compile time and then override them at run time. In the native environment, if you specify libraries at compile time, you cannot override them at run time. If you need to change the libraries, you must change the source code and recompile it. • Manipulating individual procedures and data blocks In the TNS environment, Binder produces object files; in the native environment, the nld, ld, or eld utility produces object files. Binder and the nld, ld, or eld utility have different syntax and operate on different object file types. Binder can replace individual procedures and data blocks in an object file or build an object file from individual procedures and data blocks; the nld, ld, or eld utility cannot. The nld, ld, or eld utility operates on procedures and data blocks, but only in terms of an entire object file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -21 Migrating TNS Programs to Native Programs Development and Management Changes The nld, ld, or eld utility does not support the Binder product’s SELECT SEARCH behavior. You can usually achieve similar results with the nld, ld, or eld utility by using archive files (files created by the ar utility). Because of this difference between Binder and the nld, ld, or eld utility, you might need to change the way you specify files in CONSULT and SEARCH directives. More information: • Topic Source nld utility (including differences between Binder and the nld utility) nld Manual ld utility ld Manual eld utility eld Manual Embedding SQL/MP statements in user libraries In the TNS environment, user libraries can contain embedded SQL/MP statements; in the native environment, they cannot. • Cross-reference listing The COBOL85 compiler can produce a cross-reference listing (see CROSSREF and NOCROSSREF), but the NMCOBOL and ECOBOL compilers cannot. If you need a cross-reference listing for a native HP COBOL program, use the appropriate utility from the table in CODE and NOCODE directives with the XREFPROC flag. HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -22 Migrating TNS Programs to Native Programs Maintaining Common Source Code Maintaining Common Source Code To maintain “common source code” that can be compiled with D32.00 and later RVUs of the COBOL85 compilers, D44.01 and later RVUs of the NMCOBOL compiler, and H06.01 and later RVUs of the ECOBOL compiler, follow these guidelines: • Either do not use HP COBOL language features that are not supported by all compilers, or use conditional compilation to isolate those features. You can effect conditional compilation with these directives: • • ° ° ° ° IF and IFNOT ENDIF SETTOG RESETTOG Use separate build scripts to run TNS and native tools, including the COBOL85, NMCOBOL, and ECOBOL compilers. For each compilation, use the appropriate file (or files) of dummy routines. Files of dummy routines enable the compilers to accept ENTER statements that are to be resolved at program load time (see Table 13-4). Using the Inspect and Visual Inspect Debuggers Note. You must use Visual Inspect to debug PIC loadfiles. The Inspect and Visual Inspect interactive symbolic debuggers handle TNS and native HP COBOL programs differently. For a native HP COBOL program, the Inspect debugger’s STEP command is line-oriented. If the current statement is on a single line, the STEP command steps to the next statement (that is, the debugger works as the command STEP 1 V works for a TNS HP COBOL program). If the current statement is on the same line as another statement or statements, the STEP command steps to the next line on which a new statement starts. The Inspect debugger cannot step one sentence in a native HP COBOL program (that is, the command STEP 1 S does not work). HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -23 Migrating TNS Programs to Native Programs Using the Inspect and Visual Inspect Debuggers HP COBOL Manual for TNS and TNS/R Programs —522555-006 33 -24 34 Native COBOL Cross Compiler on PC The native COBOL cross compiler is an optional cross compiler that runs on the PC platforms in Table 34-1. Table 34-1. COBOL Cross Compiler Platforms Operating System Platform Cross Compiler Name Product Number Windows 98 Windows NT 4.0 Windows 2000 Windows XP TDS1 Tandem COBOL T0328 Yes Yes No No ETK2 NonStop COBOL for TNS/R T2776 No Yes Yes Yes PC command line3 nmcobol T2776 No Yes Yes Yes 1. HP Tandem Development Suite 2. HP Enterprise Toolkit—NonStop Edition 3. G06.14 and later RVUs Topics: • • • • • • • • Cross Compiler Features NonStop COBOL for TNS/R (ETK) Tandem COBOL (TDS) nmcobol (PC Command Line) Linking Debugging Tools and Utilities Documentation HP COBOL Manual for TNS and TNS/R Programs —522555-006 34- 1 Native COBOL Cross Compiler on PC Cross Compiler Features Cross Compiler Features The native COBOL cross compiler allows you to: • Write, compile, and link these kinds of NonStop RISC-based server applications on the PC and transfer them to the OSS or Guardian platform for use in production: ° ° ° ° Executable programs Static libraries User libraries DLLs (ETK, RVU G06.20 and later) Object files built on the PC platform using the native COBOL compiler are compatible with object files built on the NonStop RISC-based server platform using the NMCOBOL compiler. Note. The native COBOL cross compiler version on your PC must be compatible with the COBOL run-time library on your NonStop RISC-based server. For TDS, see the PC COBOL file README. For ETK, see the softdoc for the RVU. • • • • Link NMCOBOL, C/C++, and pTAL objects into a single object file. When multiple RVUs are installed, choose any installed RVUs of the cross compilers, tools, and libraries. On the ETK and TDS platforms, enter ADD, MODIFY, SET, and DELETE statements into a TACL DEFINE file [see TACL DEFINE Tool (ETK and TDS)]. On the ETK and command-line platforms, compile SQL/MP or SQL/MX statements embedded in native COBOL source code. Your PC must be connected to the NonStop host to perform certain SQL/MP or SQL/MX compile-time operations and to run your applications. The native COBOL cross compiler is delivered on a separate independent product CD using Scout for NonStop Servers, but it is not available on the site update tape (SUT) for the NMCOBOL compiler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 34- 2 Native COBOL Cross Compiler on PC NonStop COBOL for TNS/R (ETK) NonStop COBOL for TNS/R (ETK) The optional native COBOL cross compiler for use with the ETK is called NonStop COBOL for TNS/R. The ETK is a GUI-based extension package to Visual Studio .NET that provides full application development functions targeted for NonStop servers. From the GUI, you can choose native COBOL cross-compiler options. Development, editing, and building functions are very similar on Visual Studio .NET and the ETK. NonStop COBOL for TNS/R components are: Component Name File NonStop COBOL driver executable nmcobol.exe NonStop COBOL driver DLL coboldvr.dll NonStop COBOL front end cobol.dll The directory structure of NonStop COBOL for TNS/R is: Directory Files bin nmcobol.exe nld.exe ld.exe cmplr coboldvr.dll cobol.dll ugen.dll as1.dll nld.dll ld.dll lib nmcobext.o libcob.srl libraries in libc.obey You can embed SQL/MP or SQL/MX statements in NonStop COBOL source code. Valid NonStop COBOL for TNS/R source files have these extensions: Extension Meaning .cob or .cbl COBOL source code with or without embedded SQL/MP or SQL/MX statements .ecob or .ecbl COBOL source code with embedded SQL/MP or SQL/MX statements Your PC must be connected to the NonStop host to perform certain SQL/MP or SQL/MX compile-time operations and to run your applications. For PC and NonStop server hardware and software requirements, see the ETK online help. For instructions for accessing the online help, see Documentation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 34- 3 Native COBOL Cross Compiler on PC Tandem COBOL (TDS) Tandem COBOL (TDS) The optional native COBOL cross compiler for use with the TDS is called Tandem NMCOBOL. TDS allows you to select Tandem NMCOBOL options from the TDS addon to the Borland integrated development environment (IDE) GUI. You can develop, edit, and build COBOL applications from within the IDE. You can embed SQL/MP or SQL/MX statements in Tandem NMCOBOL source code. Valid Tandem NMCOBOL source files, with or without embedded SQL/MP or SQL/MX statements, have the extension *.cob or *.cbl. Your PC must be connected to the NonStop host to perform certain SQL/MP or SQL/MX compile-time operations and to run your applications. For PC and NonStop server hardware and software requirements, see the TDS online help. For instructions for accessing the online help, see Documentation. nmcobol (PC Command Line) Beginning with RVU G06.14, you can invoke the native COBOL cross compiler, nmcobol, at the command line (DOS prompt) on your PC. nmcobol -c -g -o cobol-opt comp-opt link-opt sqlmx-opt nmcobol-opt file outfile sqlmp-opt VST820.vsd nmcobol must be typed as shown, in lowercase letters. -c -g -o outfile are as described in the Open System Services Shell and Utilities Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 34- 4 Native COBOL Cross Compiler on PC nmcobol (PC Command Line) cobol-opt is one of these nmcobol flags: cobol-opt Sources -Wcobol="arguments " Using the Command-Line Cross Compilers on Windows (see Documentation) -Wcopylib=file Open System Services Shell and Utilities Reference Manual comp-opt is one of these nmcobol flags: • • • • • • • • • • • • • • • -I directory -O [ 0 | 1 ] -Wcall_shared -Wcolumns=N -Werrors=N -W[no]innerlist -W[no]list -W[no]map -Wnon_shared -Woptimize={0|1} (The PC does not accept -Woptimize=2.) -Wshared -W[no]suppress -Wsyntax -Ww -Wsystype={guardian|oss} -Wsystype={guardian|oss} determines whether nmcobol creates loadfiles for the Guardian environment or for the OSS environment. The default is the Guardian environment. For descriptions of the other flags, see the Open System Services Shell and Utilities Reference Manual. link-opt is one of these nmcobol flags: • • • • • • • • • • • -L -l -s -Wansistreams -WBdllsonly -WBdynamic -WBstatic -Wheap -Whighpin -Whighrequesters -W[no]include_whole HP COBOL Manual for TNS and TNS/R Programs —522555-006 34- 5 Native COBOL Cross Compiler on PC • • • • • • • • • • • • • nmcobol (PC Command Line) -W[no]inspect -Wld -Wld_obey -Wnld -Wnld_obey -Wnostdlib -W[no]optional_lib -Wr -W[no]reexport -Wrunnamed -W]no]saveabend -Wu -Wx sqlmp-opt is described in Using the Command-Line Cross Compilers on Windows (see Documentation). sqlmx-opt is described in Using the Command-Line Cross Compilers on Windows (see Documentation). nmcobol-opt is one of these nmcobol flags: • • • • • • -Wdryrun -Whelp -Wsavetemps -Wusage -Wv -Wverbose file is the source file name. On the Guardian platform, you issue these commands (if desired) before you issue the compilation command: On the PC, you put these arguments in the -Wcobol flag in the compilation command: DEFINE1 DEFINE name [=] value PARAM SYMBOL-BLOCKS count 2 SYMBOL-BLOCKS [=] count 1. For information about DEFINE, see DEFINEs 2. For information about PARAM SYMBOL-BLOCKS, see PARAM SYMBOL-BLOCKS. HP COBOL Manual for TNS and TNS/R Programs —522555-006 34- 6 Native COBOL Cross Compiler on PC Linking You can embed SQL/MP or SQL/MX statements in NonStop COBOL source code. Valid NonStop COBOL source files have these extensions: Extension Meaning .cob or .cbl COBOL source code with or without embedded SQL/MP statements .ecob or .ecbl COBOL source code with embedded SQL/MX statements To complete SQL/MP or SQL/MX compilation, you must specify the host and the user logon. Specifying the NonStop server location (Guardian subvolume or OSS directory) is optional. For more information, see Using the Command-Line Cross Compilers on Windows. The command-line interface allows you to create batch scripts for use on multiple platforms. Linking Native COBOL cross compiler linking is performed using either Windows nld (on the ETK and the TDS) or Windows ld (on ETK). The ETK and the TDS provide a GUIbased interface for you to select linking options. When you invoke nld or ld through the command line, you must specify the run-time libraries to nld or ld. For information about Windows nld and nld options, see the nld Manual. For information about Windows ld and ld options, see the ld Manual. Note. You cannot link PIC and non-PIC object files into a single object file. Debugging • • • ETK and TDS Platforms Command-Line Platform RUNV ETK and TDS Platforms On the ETK and TDS platform, debug native COBOL source code using Visual Inspect. After it is installed on your workstation, you can either configure Visual Inspect as an external tool (in the ETK) or configure the TDS so that you can invoke Visual Inspect from the Tools menu. HP COBOL Manual for TNS and TNS/R Programs —522555-006 34- 7 Native COBOL Cross Compiler on PC Command-Line Platform Command-Line Platform On the command-line platform, debug loadfiles that were compiled with the native COBOL cross compiler either with Visual Inspect on Windows (some restrictions might apply for files containing SQL/MX statements) or by running Inspect on the NonStop server. To use Inspect, you must copy the loadfiles and the source files to the host (see PC-to-NonStop-Host Transfer Tools). Note. You must use Visual Inspect to debug PIC loadfiles. For information about Visual Inspect, see its online help. For information about Inspect, see the Inspect Manual. RUNV RUNV, which is a TACL macro in the Guardian environment and a script in the OSS environment, starts a program under the control of Visual Inspect. RUNV program-file / run-option-list / program-parameter-list VST805.vsd RUNV without program-file, displays the RUNV help. program-file is the name of the loadfile to run. program-file can be represented as a filesystem file name or (in the Guardian environment) a DEFINE name. programfile is added to the list in Visual Inspect’s Application Control View. For information about Visual Inspect, see its online help. run-option-list run-option , run-option VST332.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 34- 8 Native COBOL Cross Compiler on PC RUNV run-option IN OUT accept-device display-device VST333.vsd is an option of the RUN command, described in the TACL Reference Manual. For COBOL programs, two of the run options, IN and OUT, have special significance: accept-device has a value that designates a terminal or a process and can be a filesystem file name or (in the Guardian environment) a DEFINE name. accept-device specifies the device from which an unqualified ACCEPT statement retrieves input. If you omit this option, unqualified ACCEPT statements retrieve input from the home terminal (unless PARAM EXECUTION-LOG specifies a different device). display-device can be a file-system file name or (in the Guardian environment) a DEFINE name. Its value designates a terminal, line printer, process, existing entrysequenced disk file, or operator console to which unqualified DISPLAY statements are to deliver output. If you omit display-device, unqualified DISPLAY statements deliver output to the home terminal (unless PARAM EXECUTION-LOG specifies a different device). program-parameter-list program-parameter , program-parameter VST806.vsd program-parameter is a parameter of the program that is to be run. In the Guardian environment, the NonStop TCP/IP address of your workstation is automatically detected when you invoke RUNV. HP COBOL Manual for TNS and TNS/R Programs —522555-006 34- 9 Native COBOL Cross Compiler on PC Tools and Utilities In the OSS environment, you must either set the _TANDEM_VISUALINSPECT_WSADDR environment variable in your $HOME/.profile file or enter the workstation IP address as a command-line parameter. RUNV reads the IP address from the environment variable or from the command line. If you have set the environment variable but enter a different IP address on the RUNV command line, the command-line entry overrides the environment variable definition. You define the workstation IP address in your $HOME/.profile file only once unless the IP address changes. Tools and Utilities These tools and utilities allow you to use the native COBOL cross compiler more efficiently: • • • NonStop ar Utility TACL DEFINE Tool (ETK and TDS) PC-to-NonStop-Host Transfer Tools NonStop ar Utility The NonStop ar utility creates and maintains archive libraries. The NonStop ar utility can process a set of arguments that you enter, or you can use an OBEY command file to supply arguments to the ar utility. When an archive contains one or more TNS/R (native) object files, Windows nld can use the archive as an object file library, replacing most functions provided by the Binder SELECT SEARCH command. For information about Windows nld, see the nld Manual. The Windows-hosted ar utility does not differentiate between OSS and Guardian target files. To avoid run-time errors, be sure that procedures in archives used for resolving references work on the target platform. Note. The ar utility can also use archives created from TNS/R PIC linkable files by the ld utility. For information about the ld utility, see the ld Manual. TACL DEFINE Tool (ETK and TDS) On the ETK and TDS platform, this GUI-based tool allows you to add ADD, MODIFY, SET, and DELETE statements to a DEFINE file. The TACL DEFINE tool automatically sets the first entry in the DEFINE command file to be SET DEFMODE ON. You can leave this default or change it to SET DEFMODE OFF. Files created by the TACL DEFINE tool have the extension .tdf. HP COBOL Manual for TNS and TNS/R Programs —522555-006 34 -10 Native COBOL Cross Compiler on PC PC-to-NonStop-Host Transfer Tools PC-to-NonStop-Host Transfer Tools The ETK allows you to transfer loadfiles and source files to the NonStop host using the Deploy command or the Transfer Tool. Deploy builds and copies each project in the active solution to the NonStop host. The Transfer Tool moves files to the NonStop host for execution and debugging. The Transfer Tool is better for transferring very large, complex applications to the NonStop host. For most applications, Deploy is more convenient. The TDS provides the FTP tool to move files to the NonStop host for execution and debugging. To use the FTP tool, you must have the Winsock TCP/IP configured on your PC. From the PC command line, you can use any FTP application to transfer loadfiles and source files to the NonStop host. Documentation The ETK and the TDS have online help that provides conceptual, reference, taskoriented, and error message information, as well as a quick-start tutorial. To access the online help, you can either: • • From the Help menu, choose Contents, Index, or Search. Click the Help in any ETK or TDS dialog box. The command-line documentation, Using the Command-Line Cross Compilers on Windows, is available: • • On the native COBOL cross compiler CD In the ETK online help under References Syntax information for individual cross compilers is also available from the commandline: Cross Compiler Command C/C++ c89 -Whelp COBOL nmcobol -Whelp pTAL ptal -Whelp HP COBOL Manual for TNS and TNS/R Programs —522555-006 34 -11 Native COBOL Cross Compiler on PC HP COBOL Manual for TNS and TNS/R Programs —522555-006 34 -12 Documentation Part III. Syntax Summary Title Section 35, Commands Section 36, Compiler Directives Section 37, Source Program Organization and Format Section 38, Language Elements and Expressions Section 39, Data References Section 40, Identification Division Section 41, Environment Division Section 42, Data Division Section 43, Procedure Division Section 44, Intrinsic Function Calls Section 45, CBL85UTL and ZCOBSRL Routine Calls Section 46, COBOLLIB, CLULIB, and ZCRESRL Routine Calls HP COBOL Manual for TNS and TNS/R Programs —522555-006 Part III. Syntax Summary HP COBOL Manual for TNS and TNS/R Programs —522555-006 35 • • • Commands Guardian Environment OSS Environment nmcobol (PC Command Line) Guardian Environment • • • • • • Before Running the Compiler (Optional) Running the COBOL85 Compiler Running the NMCOBOL Compiler Running the Native Cross Compiler Under Visual Inspect Before Running the Compiled Program (Optional) Running the Compiled Program Before Running the Compiler (Optional) Note. The NMCOBOL compiler does not accept the PARAM SAMECPU command. PARAM SAMECPU dummy-value VST417.vsd PARAM SWAPVOL $ ns volume VST418.vsd PARAM SYMBOL-BLOCKS count VST419.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 35- 1 Commands Running the COBOL85 Compiler Running the COBOL85 Compiler COBOL85 IN / / source-file , OUT list-file , other-option target-name , ( obj-1 , copy-library ; compiler-directive obj-n ) VST256.vsd source-file file-name-1 define-name VST257.vsd list-file file-name-2 define-name VST259.vsd target-name file-name-4 define-name VST261.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 35- 2 Commands Running the NMCOBOL Compiler obj-1 ... obj-n file-name-4 define-name VST261.vsd copy-library file-name-4 define-name VST261.vsd Running the NMCOBOL Compiler NMCOBOL / IN source-file / , OUT list-file , other-option target-name , copy-library ; compiler-directive VST728.vsd source-file list-file target-name obj-1 ... obj-n copy-library See source-file through copy-library. HP COBOL Manual for TNS and TNS/R Programs —522555-006 35- 3 Commands Running the Native Cross Compiler Under Visual Inspect Running the Native Cross Compiler Under Visual Inspect RUNV program-file / run-option-list / program-parameter-list VST805.vsd run-option-list run-option , run-option VST332.vsd run-option IN OUT accept-device display-device VST333.vsd program-parameter-list program-parameter , program-parameter VST806.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 35- 4 Commands Before Running the Compiled Program (Optional) Before Running the Compiled Program (Optional) • • • • ASSIGN CLEAR FIXERRS PARAM ASSIGN ASSIGN cobol-file-name program-name . * , system-file , characteristic VST334.vsd system-file name #IN #OUT #TERM #TEMP $RECEIVE VST335.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 35- 5 Commands Before Running the Compiled Program (Optional) characteristic EXT size-list CODE file-code EXCLUSIVE SHARED PROTECTED INPUT OUTPUT I-O REC record-size BLOCK block-size VST336.vsd size-list pri-extent-size ( ) pri-extent-size , sec-extent-size VST337.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 35- 6 Commands Before Running the Compiled Program (Optional) CLEAR CLEAR ALL ASSIGN PARAM ASSIGN assignation PARAM DEBUG EXECUTION-LOG INSPECT NONSTOP PRINTER-CONTROL WAITED-IO SWITCH- nn parameter-name VST340.vsd assignation COBOL-file-name program-name . * VST638.vsd FIXERRS FIXERRS error-file ; tedit-command VST372.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 35- 7 Commands Before Running the Compiled Program (Optional) PARAM PARAM name-value-pair , name-value-pair VST338.vsd name-value-pair SWITCH-nn ON DEBUG OFF NONSTOP INSPECT WAITED-IO EXECUTION-LOG system-file-name define-name * TAPE-DIALOGUE ON OFF PRINTER-CONTROL parameter-name cobol-file-name parameter-value VST339.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 35- 8 Commands Running the Compiled Program Running the Compiled Program RUN program-file RUND / run-option-list / program-parameter-list VST331.vsd run-option-list run-option , run-option VST332.vsd run-option IN OUT accept-device display-device VST333.vsd program-parameter-list program-parameter , program-parameter VST806.vsd OSS Environment • • • • Before Running the Compiler (Optional) Running the cobol (COBOL85) Compiler Running the nmcobol Compiler Running the Compiled Program HP COBOL Manual for TNS and TNS/R Programs —522555-006 35- 9 Commands Before Running the Compiler (Optional) Before Running the Compiler (Optional) To change one or more of the defaults in Table 35-1 before executing the cobol or nmcobol command, use the OSS export command. To execute a cobol or nmcobol command with a specified set of environment variables, use the OSS env function with the environment variables in Table 35-1. Table 35-1. Environment Variables Variable Effect Default COBOL Determines the pathname of the COBOL85 compiler that the cobol utility calls /G/system/system/cobol85 NMCOBOL Determines the pathname of the NMCOBOL compiler that the nmcobol utility calls /G/system/system/cobolfe BIND1 Determines the pathname of the Binder that the cobol utility calls /G/system/system/bind AXCEL1 Determines the pathname of the Accelerator that the cobol utility calls /G/system/system/axcel SWAPVOL1 Determines the disk volume on which the COBOL85 compiler, Binder, Accelerator, and SQL/MP compiler create temporary files Same as in the Guardian environment—see PARAM SWAPVOL SQLCOMP Determines the pathname of the SQL/MP compiler that the cobol or nmcobol utility calls /G/system/system/sqlcomp MXSQLCO2 Determines the pathname of the alternate COBOL SQL/MX preprocessor that the nmcobol utility calls /usr/tandem/sqlmx/bin/ MXCMP2 Determines the pathname of the alternate SQL/MX compiler that the nmcobol utility calls /G/system/system/ SQLCLIO2 Determines the pathname of the object file that describes the SQL/MX API to the nmcobol utility /usr/tandem/sqlmx/lib/sqlc li.o 1. For the COBOL85 compiler only. 2. For the NMCOBOL compiler only. HP COBOL Manual for TNS and TNS/R Programs —522555-006 35 -10 Commands Running the cobol (COBOL85) Compiler Running the cobol (COBOL85) Compiler cobol pathname flag operand operand VST621.vsd flag is as described in the Open System Services Shell and Utilities Reference Manual. operand pathname -l library VST622.vsd pathname ns file ns . cbl cob a o srl VST623.vsd Running the nmcobol Compiler nmcobol pathname flag operand operand VST733.vsd flag is as described in the Open System Services Shell and Utilities Reference Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 35 -11 Commands Running the Compiled Program operand pathname -l library VST622.vsd pathname ns file ns . cbl cob ecbl ecob a m o srl VST623.vsd Note. The file suffixes (cbl, cob, and so on) are not case-sensitive. Running the Compiled Program Type the name of the loadfile and press Return; for example: a.out To run the program with the selected debugger, enter: run -debug a.out If the current directory is not in your search path, add it with this command: export PATH=$PATH:. HP COBOL Manual for TNS and TNS/R Programs —522555-006 35 -12 Commands nmcobol (PC Command Line) nmcobol (PC Command Line) Beginning with RVU G06.14, you can invoke the native COBOL cross compiler, nmcobol, from the command line (DOS prompt) on your PC. nmcobol -c -g -o cobol-opt comp-opt link-opt sqlmx-opt nmcobol-opt file outfile sqlmp-opt VST820.vsd -c -g -o outfile -cobol-opt -comp-opt -link-opt -sqlmp-opt -sqlmx-opt -nmcobol-opt file See nmcobol (PC Command Line). HP COBOL Manual for TNS and TNS/R Programs —522555-006 35 -13 Commands nmcobol (PC Command Line) HP COBOL Manual for TNS and TNS/R Programs —522555-006 35 -14 36 Compiler Directives On the compiler command line: directive ; , directive VST263.vsd In the program source text: ? directive ; , directive VST264.vsd In the OSS environment, include compiler directives in the cobol or nmcobol command line with the -Wcobol flag. Note. “Default:” identifies the default for the compiler directive itself, not for its optional parameter(s). This default applies if a program does not contain the compiler directive at all. • • • • • • • • • • • • • ANSI BLANK and NOBLANK CALL-SHARED CANCEL and NOCANCEL CHECK CODE and NOCODE COLUMNS COMPACT and NOCOMPACT COMPILE CONSULT and NOCONSULT CROSSREF and NOCROSSREF DIAGNOSE-74 and NODIAGNOSE-74 DIAGNOSE-85 and NODIAGNOSE-85 HP COBOL Manual for TNS and TNS/R Programs —522555-006 36- 1 Compiler Directives • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • DIAGNOSEALL and NODIAGNOSEALL ENDIF ENDUNIT ENV ERRORFILE ERRORS FIPS and NOFIPS FLOAT and NOFLOAT FMAP HEADING HEAP HIGHPIN HIGHREQUESTERS ICODE and NOICODE IF and IFNOT INNERLIST and NOINNERLIST INSPECT and NOINSPECT LARGEDATA LD LESS-CODE LIBRARY LINES LIST and NOLIST LMAP and NOLMAP MAIN MAP and NOMAP NLD NLD NON-SHARED OPTIMIZE HP COBOL Manual for TNS and TNS/R Programs —522555-006 36- 2 Compiler Directives • • • • • • • • • • • • • • • • • • • • • • • • • • PERFORM-TRACE PORT and NOPORT RESETTOG RUNNABLE RUNNAMED SAVE SAVEABEND and NOSAVEABEND SEARCH and NOSEARCH SECTION SETTOG SHARED SHOWCOPY and NOSHOWCOPY SHOWFILE and NOSHOWFILE SOURCE SQL and NOSQL SQLMEM SUBSET SUBTYPE SUPPRESS and NOSUPPRESS SYMBOLS and NOSYMBOLS SYNTAX TANDEM TRAP2 and NOTRAP2 TRAP2-74 and NOTRAP2-74 UL WARN and NOWARN HP COBOL Manual for TNS and TNS/R Programs —522555-006 36- 3 Compiler Directives ANSI ANSI ANSI TANDEM VST266.vsd Default: TANDEM Placement: Anywhere Scope: ANSI or TANDEM within a section of text obtained from a copy library or source library is effective only for the length of that text section. When the compiler reverts to the source file where it found the COPY verb or SOURCE directive, the previously active reference format applies. Dependencies: None References: TANDEM BLANK and NOBLANK BLANK NOBLANK VST267.vsd Default: BLANK for the COBOL85 compiler NOBLANK for the NMCOBOL compiler Placement: Anywhere Scope: The last BLANK or NOBLANK in the program applies. Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36- 4 Compiler Directives CALL-SHARED CALL-SHARED Note. The COBOL85 compiler does not recognize this directive. CALL-SHARED NON-SHARED SHARED VST802.vsd Default: NON-SHARED Placement: Anywhere Scope: The last CALL-SHARED, NON-SHARED, or SHARED in the compilation unit applies to the entire compilation unit. Dependencies: • • • • • • References: If RUNNABLE is active, CALL-SHARED uses the linker to create a PIC executable object file; otherwise, CALL-SHARED creates a PIC linkfile. Do not use with UL. NON-SHARED SHARED RUNNABLE UL CANCEL and NOCANCEL CANCEL NOCANCEL VST383.vsd Default: CANCEL Placement: Anywhere Scope: Applies to the program that contains it. CANCEL and NOCANCEL do not apply to initial programs, which are initialized every time they are called. Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36- 5 Compiler Directives CHECK CHECK CHECK check-level VST268.vsd Default: CHECK 1 Placement: Anywhere Scope: In each separately compiled program, the last CHECK in the program unit determines the check level for the code block being produced. Dependencies: None check-level What is Checked Comments 0 Nothing CHECK 0 results in the fastest execution time. 1 (default) Nothing CHECK 1 might have a different meaning in future versions of HP COBOL for HP NonStop systems (“HP COBOL”). For the fastest execution (and no subscript checking) in current and future versions of HP COBOL, specify CHECK 0. 2 Validity of subscripts and indexes 3 Validity of subscripts, indexes, and reference modifiers Specifies the maximum level of checking that HP COBOL currently provides. 4-15 Validity of subscripts, indexes, and reference modifiers 4 - 15 might have different meanings in future versions of HP COBOL. For the maximum level of checking that HP COBOL currently provides, specify CHECK 3. For maximal checking, specify CHECK 15 (which could increase the program’s run-time overhead in future versions of HP COBOL if additional checking levels are implemented). HP COBOL Manual for TNS and TNS/R Programs —522555-006 36- 6 Compiler Directives CODE and NOCODE CODE and NOCODE Note. The NMCOBOL compiler issues warnings for these directives. CODE NOCODE VST269.vsd Default: NOCODE Placement: Anywhere Scope: In each separately compiled program, the last CODE or NOCODE in the program unit applies to the entire program unit. Dependencies: CODE works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 36- 7 Compiler Directives COLUMNS COLUMNS COLUMNS length VST270.vsd Default: COLUMNS 132 • Placement: • • On a directive line, COLUMNS must begin with a question mark (?) in column 1, regardless of any active ANSI directive. In a COPY library or a source library, COLUMNS must be the only directive on its line and must precede all SECTION directives in that library. The COBOL85 compiler accepts at most one COLUMNS for each source file (that is, one for the primary source file and one for each COPY library or source library called by the primary source file). Scope: When the compiler shifts from reading the primary source file to reading a COPY library (in compliance with a COPY statement) or a source library (in compliance with a SOURCE directive), it saves the current (default or specified) logical length for source lines. That length applies to all source lines in the COPY library or source library, unless a COLUMNS directive occurs in the COPY library file (as mentioned in the preceding item). In this case, the compiler reverts to the saved logical length when it resumes reading text from the primary source file. Dependencies: COLUMNS works only if TANDEM is active. References: • • • ANSI SOURCE TANDEM COMPACT and NOCOMPACT Note. The NMCOBOL compiler, which does not use BINSERV, issues warnings for these directives. COMPACT NOCOMPACT VST271.vsd Default: COMPACT Placement: Anywhere Scope: The last COMPACT or NOCOMPACT in the compilation unit applies. Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36- 8 Compiler Directives COMPILE COMPILE COMPILE SYNTAX VST272.vsd Default: COMPILE Placement: Outside the boundaries of a separately compiled program; that is, not between the Identification Division header of a separately compiled program and its end, which is marked by one of: • • • The corresponding END PROGRAM statement ENDUNIT The end of the source file Scope: The last COMPILE or SYNTAX in the compilation unit applies to the entire compilation unit. Dependencies: None CONSULT and NOCONSULT Note. The NMCOBOL compiler ignores the NOCONSULT directive and issues a warning. CONSULT object-name-list ( object-name-list ) NOCONSULT VST273.vsd object-name-list object-name , object-name VST274.vsd Default: NOCONSULT Placement: Anywhere Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36- 9 Compiler Directives CROSSREF and NOCROSSREF CROSSREF and NOCROSSREF Note. The NMCOBOL compiler issues warnings for these directives and does not produce a cross-reference listing. If you need one, use the noft utility with the XREFPROC flag (see the noft Manual). CROSSREF class-list NOCROSSREF VST275.vsd class-list class , ONLY class INCLUDE EXCLUDE VST276.vsd class Class COBOL Identifiers Selected ALL All classes CONDITIONS * Condition-names DATANAMES (or VARIABLES) * Data-names (FILLER not included) FILES * (COBOL) file names FUNCTIONS INDEXES * * Index-names LITERALS Literals (numeric and nonnumeric) MNEMONICS * PROCNAMES (or LABELS) * PROGRAMS UNREFS Routine-names of functions (routines that return a value) * File-mnemonics Procedure-names (paragraph-names, sectionnames) Program-names, routine-names Items defined but not referenced (technically, not a class but a generalized request for all such items) HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -10 Compiler Directives DIAGNOSE-74 and NODIAGNOSE-74 Default: NOCROSSREF Placement: Anywhere Scope: CROSSREF applies to all separately compiled program units, regardless of nesting; that is, all programs within a nest appear in the same crossreference listing. You need not repeat the CROSSREF directive for each program unit in a compilation unit; the class list active at the end of one program unit applies to the next program unit until explicitly altered by a NOCROSSREF directive. Dependencies: CROSSREF works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS DIAGNOSE-74 and NODIAGNOSE-74 DIAGNOSE-74 NODIAGNOSE-74 VST277.vsd Default: NODIAGNOSE-74 Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None DIAGNOSE-85 and NODIAGNOSE-85 Note. The COBOL85 compiler does not recognize these directives. DIAGNOSE-85 NODIAGNOSE-85 VST719.vsd Default: NODIAGNOSE-85 Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -11 Compiler Directives DIAGNOSEALL and NODIAGNOSEALL DIAGNOSEALL and NODIAGNOSEALL DIAGNOSEALL NODIAGNOSEALL VST470.vsd Default: NODIAGNOSEALL Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None ENDIF ENDIF toggle-number VST278.vsd Default: None Placement: Must be either on a directive line of its own or be the last of a sequence of directives Dependencies: Requires a preceding IF or IFNOT directive with the same togglenumber References: IF and IFNOT ENDUNIT ENDUNIT VST279.vsd Default: The compiler detects the end of a Procedure Division by encountering either an END PROGRAM statement or the end of the file. Placement: Must be either on a directive line of its own or be the last of a sequence of directives Scope: Applies to program unit Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -12 Compiler Directives ENV ENV Note. This directive is useful only for the COBOL85 compiler. The NMCOBOL compiler accepts this directive with the COMMON option (the default for this compiler), reports an error for the OLD option, and issues a warning for the LIBRARY option. ENV COMMON LIBRARY OLD VST280.vsd Default: ENV OLD Placement: Must appear before any source code lines Scope: Applies to all programs in its source file Dependencies: None ERRORFILE ERRORFILE file-name define-name VST281.vsd Default: None Placement: Either on the compiler command line or in the source file before the Identification Division Scope: Applies to the compilation unit Dependencies: None ERRORS ERRORS error-limit VST282.vsd Default: ERRORS 100 Placement: Anywhere Scope: Applies to the compilation unit Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -13 Compiler Directives FIPS and NOFIPS FIPS and NOFIPS FIPS flag-option-list ( flag-option-list ) NOFIPS VST468.vsd flag-option-list flag-option , flag-option VST469.vsd flag-option Value Identified OBSOLETE Obsolete language elements ABOVEMIN Language elements above the minimum subset ABOVEINTER Language elements above the intermediate subset LEVEL1COM * Communication language elements ABOVELEVEL1COM * Communication language elements above level 1 of communication LEVEL1DEB Debug language elements ABOVELEVEL1DEB * Debug language elements above level 1 of Debug REPORTWRITER * Report Writer language elements LEVEL1SEG Segmentation language elements ABOVELEVEL1SEG Segmentation language elements above level 1 of segmentation NONSTANDARDEXT Nonstandard extensions to COBOL * This option does not affect compilation because the compiler does not support this module. If you use this option, the compiler issues a warning and ignores the option. Default: NOFIPS Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -14 Compiler Directives FLOAT and NOFLOAT FLOAT and NOFLOAT Note. The NMCOBOL compiler ignores this directive and issues a warning. FLOAT NOFLOAT VST818.vsd Default: FLOAT Placement: Outside the boundaries of any program Scope: Applies to all subsequent programs Dependencies: None FMAP Note. The COBOL85 compiler does not recognize this directive. FMAP VST731.vsd Default: The NMCOBOL compiler does not produce a source file map. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: NOLIST and SUPPRESS do not suppress the source file map that FMAP produces. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -15 Compiler Directives HEADING HEADING HEADING " character-string " VST283.vsd character-string Default values is all spaces. Default: Standard top-of-page line Placement: Anywhere Scope: Applies until another HEADING overrides it Dependencies: None HEAP Note. The NMCOBOL compiler ignores this directive and issues a warning. HEAP size VST738.vsd Default: Guardian environment: the heap is nonexistent by default. PC and OSS environments: the heap is large by default and cannot be made larger. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: HEAP works only if the program runs in the CRE in the Guardian environment and calls HP C functions that use heap space. HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -16 Compiler Directives HIGHPIN HIGHPIN Note. The NMCOBOL compiler ignores this directive and issues a warning. A native HP COBOL program always runs at a high PIN. HIGHPIN VST284.vsd Default: TNS program runs with a low PIN (less than or equal to 255). Placement: Any of: • • • Anywhere in the source program (but it is good practice to put it before the first program in a compilation unit) On the compiler command line In a stand-alone Binder session Scope: Applies to the program in which or before which it appears and to all subsequent programs in the compilation unit Dependencies: Program must be compiled with ENV COMMON. References: ENV HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -17 Compiler Directives HIGHREQUESTERS HIGHREQUESTERS Note. The NMCOBOL compiler ignores this directive and issues a warning. A native HP COBOL program always runs at a high PIN. HIGHREQUESTERS VST285.vsd Default: Program cannot run as a server that accepts requesters running with high PINs (greater than 255). Placement: Any of: • • • Anywhere in the source program (but it is good practice to put it in the main program, because that is the only program it affects—that is, Binder assumes that a run unit can accept high PIN requesters only if HIGHREQUESTERS is specified for the main program in the run unit) On the compiler command line In a stand-alone Binder session Scope: Applies to the main program in which or before which it appears in the compilation unit Dependencies: Program must be compiled with ENV COMMON and HIGHPIN. References: • • ENV HIGHPIN ICODE and NOICODE Note. The NMCOBOL compiler ignores these directives and issues warnings. For the NMCOBOL compiler, use INNERLIST and NOINNERLIST instead. ICODE NOICODE VST286.vsd Default: NOICODE Placement: Anywhere Scope: Last ICODE or NOICODE applies to program unit. Dependencies: ICODE works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -18 Compiler Directives IF and IFNOT IF and IFNOT IF toggle-number IFNOT VST287.vsd Default: None Placement: IF must be either on a directive line of its own or be the last of a sequence of directives. IFNOT can be anywhere. Scope: IF or IFNOT applies until matching ENDIF appears. Dependencies: Requires a preceding IF or IFNOT directive with the same togglenumber References: IF and IFNOT INNERLIST and NOINNERLIST Note. The COBOL85 compiler does not recognize these directives. For the COBOL85 compiler, use ICODE and NOICODE instead. INNERLIST NOINNERLIST VST724.vsd Default: NOINNERLIST Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: INNERLIST works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -19 Compiler Directives INSPECT and NOINSPECT INSPECT and NOINSPECT INSPECT NOINSPECT VST288.vsd Default: INSPECT Placement: Anywhere Scope: The last INSPECT or NOINSPECT in the compilation unit applies to the compilation unit. Dependencies: NOINSPECT and SAVEABEND override each other (whichever is last is active). References: SAVEABEND and NOSAVEABEND LARGEDATA Note. This directive is useful only in the CRE. LARGEDATA item ( ) item , item VST725.vsd Default: None Placement: Anywhere Scope: If LARGEDATA specifies constants, or has no item, and precedes the PROCEDURE DIVISION header in the program that contains it, then it applies to the program that contains it and to subsequent programs. If LARGEDATA directive specifies constants, or has no item, and follows the PROCEDURE DIVISION header in the program that contains it, then it applies only to subsequent programs. Dependencies: Program must be compiled with ENV COMMON or ENV LIBRARY. References: ENV HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -20 Compiler Directives LD LD Note. The COBOL85 compiler does not accept this directive. LD ( option ) VST111.vsd Default: None Placement: In the command line Scope: Applies to the compilation unit Dependencies: None LESS-CODE Note. The compiler ignores this directive and issues a warning. For the description of this directive, see the COBOL85 Manual for TNS and TNS/R. LESS-CODE bits-to-set VST384.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -21 Compiler Directives LESS-CODE bits-to-set Value of bits-to-set Decimal Binary Result 0 000 Compiler generates code to initialize all areas. 1 001 Compiler generates code to initialize all areas except the Extended-Storage Section in: • • Main programs Other programs that are not initial programs and have NOCANCEL directives active Size of object file increases significantly, amount of code generated decreases significantly, and execution time decreases slightly. 2 010 Compiler generates code to initialize all areas except the Extended-Storage Section in: • Programs that are not main programs and are either initial programs or do not have NOCANCEL directives active Size of object file decreases significantly and amount of code generated decreases significantly. Execution time increases under either of these conditions: • • The program is an initial program and is called more than once The program is not an initial program and is cancelled several times Execution time decreases under either of these conditions: • The program is an initial program and is only called once The program is not an initial program and is never cancelled 3 011 Same as 1 and 2 combined 4 100 Compiler generates code to initialize all areas except the Working-Storage Section in: • • Main programs Programs that are not main programs and are either initial programs or do not have NOCANCEL directives active Size of object file can increase by a maximum of 65,536 bytes for each program to which the conditions apply. Amount of code generated and execution time can decrease. 5 101 Same as 1 and 4 combined 6 110 Same as 2 and 4 combined 7 111 Same as 1, 2, and 3 combined HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -22 Compiler Directives LIBRARY Default: None Placement: The compiler accepts it anywhere, but to be effective, it must be before the main program. Scope: Applies to the compilation unit Dependencies: None LIBRARY Note. The NMCOBOL compiler ignores this directive and issues a warning. LIBRARY file-name VST289.vsd Default: None Placement: Anywhere, but the COBOL85 compiler and the Binder do not propagate LIBRARY from called to calling programs; therefore, calling programs cannot reference library objects in called programs unless you use one of these methods: • • • Use a separate bind step on the final object with a SET LIBRARY file-name command. Use the LIB parameter on the RUN command. Specify the LIBRARY directive on the main compilation. Scope: The last LIBRARY applies to the loadfile produced by the compilation. Dependencies: None LINES LINES lines-per-page VST290.vsd Default: LINES 60 Placement: Anywhere Scope: Applies until another LINES overrides it Dependencies: LINES works only if paging applies to the compilation list device. HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -23 Compiler Directives LIST and NOLIST LIST and NOLIST LIST NOLIST VST291.vsd Default: LIST Placement: Anywhere Scope: Applies until overridden by its opposite Dependencies: SUPPRESS overrides LIST (and therefore CODE, CROSSREF, ICODE, LMAP, MAP, SHOWCOPY, and SQL). NOLIST suppresses INNERLIST. References: • • • • • • • • • SUPPRESS and NOSUPPRESS CODE and NOCODE CROSSREF and NOCROSSREF ICODE and NOICODE INNERLIST and NOINNERLIST LMAP and NOLMAP MAP and NOMAP SHOWCOPY and NOSHOWCOPY SQL and NOSQL HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -24 Compiler Directives LMAP and NOLMAP LMAP and NOLMAP Note. The NMCOBOL compiler, which does not use BINSERV, ignores these directives and issues warnings. LMAP lm-option-list ( lm-option-list ) * NOLMAP lm-option-list ( lm-option-list ) VST292.vsd lm-option-list lm-option , lm-option VST293.vsd For LMAP, the default value for lm-option-list is ALPHA; for NOLMAP, it is ALPHA, LOC, XREF. lm-option Value Load Map Requested (by LMAP) or Suppressed (by NOLMAP) ALPHA Programs and subprograms sorted by procedure-name LOC Programs and subprograms sorted by starting address XREF Cross-reference listing of entry-point and data-block names Default: LMAP ALPHA Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: LMAP works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -25 Compiler Directives MAIN MAIN Note. Put this directive before the Identification Division header of the first program unit in the compilation unit. MAIN program-name VST294.vsd Default: Every program unit that does not have a Linkage Section is compiled as a main program. If more than one program unit of a compilation unit qualifies as a main program, the compiler reports this as an error, compiles the first qualifying program unit as the main program, and produces multiple object files. Placement: Before the Identification Division header of the first program unit in the compilation unit Scope: Applies to the program that contains it Dependencies: None MAP and NOMAP MAP NOMAP VST295.vsd Default: NOMAP Dependencies: MAP works only if LIST is active and SUPPRESS is not. Scope: The last MAP or NOMAP applies. Dependencies: MAP works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -26 Compiler Directives NLD NLD Note. The compiler does not accept this directive. For the description of this directive, see the COBOL85 Manual for TNS and TNS/R. NLD ( option ) VST082.vsd Default: None Placement: In the command line Scope: Applies to the compilation unit Dependencies: None NONSTOP Note. • • Do not use this directive in the OSS environment. Before RVU D46.00 and G06.00, software product revision T8107AAT (run-time library T8108AAR), the NMCOBOL compiler ignores this directive and issues a warning. NONSTOP VST296.vsd Default: The program cannot run as a process pair (even if it contains a PARAM NONSTOP ON command). Placement: Must appear before the Identification Division of the first program unit in the source text Scope: Applies to the program unit Dependencies: PARAM NONSTOP OFF command suppresses NONSTOP. References: PARAM Command HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -27 Compiler Directives NON-SHARED NON-SHARED Note. The COBOL85 compiler does not recognize this directive. NON-SHARED CALL-SHARED SHARED VST803.vsd Default: NON-SHARED Placement: Anywhere Scope: The last NON-SHARED, CALL-SHARED, or SHARED in the compilation unit applies to the entire compilation unit. Dependencies: If RUNNABLE is active, NON-SHARED creates a non-PIC executable object file; otherwise, NON-SHARED creates a non-PIC nonexecutable object file. References: • • • CALL-SHARED SHARED RUNNABLE HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -28 Compiler Directives OPTIMIZE OPTIMIZE OPTIMIZE level VST297.vsd level Effect Level COBOL85 Compiler NMCOBOL Compiler 0 Code is not optimized. Provided in case other optimization levels cause errors. Supports symbolic debugging; data is always in memory. Code is not optimized. Provided in case other optimization levels cause errors. Supports symbolic debugging; data is always in memory. 1 (default) Code is optimized within statements, but not across statement boundaries. Appropriate for application programs still being developed and tested. Supports symbolic debugging; data is not always in memory. Code is optimized within statements and across statement boundaries. The resulting code is more efficient than that produced by lower levels of optimization. Supports symbolic debugging; data is not always in memory. 2 Code is optimized within statements and across statement boundaries, and the resulting code is more efficient than code produced by lower levels. Uses level 1 instead. Default: OPTIMIZE 1 Placement: Outside the boundary of a separately compiled program Scope: The optimization level active at the beginning of a separately compiled program determines the level of optimization for that program and any programs it contains. Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -29 Compiler Directives PERFORM-TRACE PERFORM-TRACE PERFORM-TRACE VST800.vsd Default: The compiler does not provide additional information if run-time error 148 occurs. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: None PORT and NOPORT PORT 1 2 3 NOPORT VST600.vsd Default: NOPORT Placement: Anywhere Scope: Applies to the compilation unit Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -30 Compiler Directives RESETTOG RESETTOG RESETTOG toggle-number-list VST298.vsd toggle-number-list toggle-number , toggle-number VST299.vsd Default value is all toggles. Default: None Placement: Must be either on a directive line of its own or be the last of a sequence of directives Scope: Applies until SETTOG overrides it Dependencies: SETTOG overrides it. References: SETTOG HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -31 Compiler Directives RUNNABLE RUNNABLE Note. The COBOL85 compiler does not recognize this directive. RUNNABLE VST729.vsd Default: The NMCOBOL compiler does not use the linker to produce a loadfile if there were no compilation errors. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: SYNTAX overrides RUNNABLE. You must specify RUNNABLE to use RUNNAMED, SAVEABEND, NOSAVEABEND, or SUBTYPE in the NMCOBOL compiler. Without CALL-SHARED or SHARED, RUNNABLE uses the linker to produce a non-PIC loadfile. With CALL-SHARED, RUNNABLE uses the linker to produce a PIC loadfile. With SHARED, RUNNABLE uses the linker to produce a PIC library file (DLL). References: • • • • • • SYNTAX RUNNAMED SAVEABEND and NOSAVEABEND SUBTYPE CALL-SHARED SHARED HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -32 Compiler Directives RUNNAMED RUNNAMED RUNNAMED VST300.vsd Default: None Placement: Any of: • • • Anywhere in a source program In a stand-alone Binder session In a linker session (specify -change) Scope: Applies to the program in which or before which it appears, to all subsequent programs in the compilation unit, and to all target files Dependencies: For the NMCOBOL compiler, RUNNAMED is appropriate only if the program was compiled with RUNNABLE (because a linkfile is not a run unit).. References: RUNNABLE HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -33 Compiler Directives SAVE SAVE Note. Do not use this directive in the OSS environment. SAVE save-option-list ( ) save-option-list VST301.vsd save-option-list save-option , save-option VST302.vsd save-option PARAM STARTUP ASSIGNS ALL count VST303.vsd Default: The compiler does not save initialization messages. Placement: Anywhere Scope: Applies to the compilation unit Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -34 Compiler Directives SAVEABEND and NOSAVEABEND SAVEABEND and NOSAVEABEND SAVEABEND NOSAVEABEND VST304.vsd Default: NOSAVEABEND Placement: Anywhere Scope: The last SAVEABEND or NOSAVEABEND in the compilation unit applies to the entire compilation unit. Dependencies: SAVEABEND and NOINSPECT override each other (whichever is last is active). For the NMCOBOL compiler, SAVEABEND and NOSAVEABEND are appropriate only if the program was compiled with RUNNABLE. References: • • INSPECT and NOINSPECT RUNNABLE HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -35 Compiler Directives SEARCH and NOSEARCH SEARCH and NOSEARCH Note. The NMCOBOL compiler ignores the NOSEARCH directive and issues a warning. SEARCH object-name-list ( object-name-list ) NOSEARCH VST305.vsd object-name-list object-name , object-name VST306.vsd Default: NOSEARCH Placement: Anywhere Scope: Applies to the compilation unit Dependencies: Must be used with either RUNNABLE or CONSULT if you are creating a PIC object file • • References: RUNNABLE CONSULT and NOCONSULT SECTION SECTION text-name , TANDEM ANSI VST307.vsd If you do not specify TANDEM or ANSI, the compiler assumes that the format of the text is the current source-text format. Default: None Placement: Must be on a directive line of its own. If it appears in the text of the compilation source file (the IN file), it is ignored. Scope: Applies only to the section of text that it specifies Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -36 Compiler Directives SETTOG SETTOG Note. The SETTOG directive must either be on a directive line of its own or be the last of a sequence of directives. SETTOG toggle-number-list VST308.vsd toggle-number-list toggle-number , toggle-number VST299.vsd Default value is all toggles. Default: None Placement: Must either be on a directive line of its own or be the last of a sequence of directives. Scope: Applies until RESETTOG overrides it Dependencies: None References: RESETTOG HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -37 Compiler Directives SHARED SHARED Note. The COBOL85 compiler does not recognize this directive. SHARED CALL-SHARED NON-SHARED VST804.vsd Default: NON-SHARED Placement: Anywhere Scope: The last SHARED, CALL-SHARED, or NON-SHARED in the compilation unit applies to the entire compilation unit. Dependencies: • • • • • • References: If RUNNABLE is active, SHARED uses the linker to create a PIC library file (DLL); otherwise, SHARED creates a PIC linkfile. Do not use with CALL-SHARED, NON-SHARED, or UL. CALL-SHARED NON-SHARED RUNNABLE UL SHOWCOPY and NOSHOWCOPY SHOWCOPY NOSHOWCOPY VST310.vsd Default: SHOWCOPY Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: SHOWCOPY works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -38 Compiler Directives SHOWFILE and NOSHOWFILE SHOWFILE and NOSHOWFILE SHOWFILE NOSHOWFILE VST311.vsd Default: NOSHOWFILE Placement: Anywhere Scope: Applies until its opposite overrides it Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -39 Compiler Directives SOURCE SOURCE SOURCE edit-file-name ( section-name-list ) VST312.vsd section-name-list section-name , section-name VST313.vsd Default value is entire file. Default: None Placement: Must be the last directive on its line. Dependencies: None Format of a source library: section-text pre-text VST252.vsd section-text ? SECTION text-name , format text-line VST253.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -40 Compiler Directives SQL and NOSQL SQL and NOSQL Note. The NMCOBOL compiler ignores the NOSQL directive and issues a warning. SQL sql-option-list ( ) sql-option-list NOSQL VST315.vsd sql-option-list sql-option , sql-option VST316.vsd sql-option RELEASE1 RELEASE2 PAGES num-pages SQLMAP WHENEVERLIST VST317.vsd Default: None. If the program contains SQL/MP statements, the SQL directive is required; otherwise, it is unnecessary. Placement: The COBOL85 compiler accepts SQL and NOSQL in either the source code (before the first Identification Division in the program) or the compiler command line; the NMCOBOL compiler accepts them only in the compiler command line. Scope: Applies to the compilation unit Dependencies: SQL works only if LIST is active and SUPPRESS is not. References: • • LIST and NOLIST SUPPRESS and NOSUPPRESS HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -41 Compiler Directives SQLMEM SQLMEM Note. The NMCOBOL compiler ignores this directive and issues a warning. The concept of extended memory does not exist for TNS/R processes. SQLMEM USER EXT VST318.vsd Default: SQLMEM EXT Placement: The first SQLMEM in a program must be preceded by SQL. Subsequent SQLMEMs can appear anywhere in the program. Scope: Applies to all SQL/MP tatements between it and the next SQLMEM Dependencies: SQLMEM is allowed only in programs that also contain SQL. References: SQL and NOSQL HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -42 Compiler Directives SUBSET SUBSET Note. Put this directive before the Identification Division header of the first program unit in the compilation unit. SUBSET parameter-list ( parameter-list ) VST319.vsd parameter-list parameter , parameter VST320.vsd parameter HIGH EXTENDED DEB1 SEG1 SEG2 OBSOLETE VST321.vsd Default: None Placement: Must appear before the first COBOL source program (that is, before the first Identification Division header). Scope: The last valid SUBSET in the program applies. Dependencies: None HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -43 Compiler Directives SUBTYPE SUBTYPE Note. Do not use this directive in the OSS environment. SUBTYPE subtype-number VST323.vsd Default: SUBTYPE 0 Placement: Anywhere Scope: The last SUBTYPE in the program applies. Dependencies: For the NMCOBOL compiler, SUBTYPE is appropriate only if the program was compiled with RUNNABLE. References: RUNNABLE SUPPRESS and NOSUPPRESS SUPPRESS NOSUPPRESS VST324.vsd Default: NOSUPPRESS Placement: Accepted anywhere, but to suppress the compiler listing without altering the source text, put SUPPRESS on the command line. Scope: Applies until its opposite overrides it Dependencies: SUPPRESS overrides LIST (and therefore, it also overrides CODE, CROSSREF, ICODE, LMAP, MAP, SHOWCOPY, and SQL). References: • • • • • • • • LIST and NOLIST CODE and NOCODE CROSSREF and NOCROSSREF ICODE and NOICODE LMAP and NOLMAP MAP and NOMAP SHOWCOPY and NOSHOWCOPY SQL and NOSQL HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -44 Compiler Directives SYMBOLS and NOSYMBOLS SYMBOLS and NOSYMBOLS SYMBOLS NOSYMBOLS VST325.vsd Default: NOSYMBOLS Placement: Accepted anywhere, but to affect a program other than the first program in a compilation unit, SYMBOLS must follow either an ENDUNIT directive or an END PROGRAM statement, which signals the end of the preceding program’s Procedure Division. If you want a symbol table for a given separately compiled program, put SYMBOLS before its Identification Division header. If the compiler encounters a subsequent SYMBOLS or NOSYMBOLS directive within the text of that separately compiled program, it issues a warning and ignores that directive. Scope: Applies until its opposite overrides it Dependencies: SYMBOLS does not work when SYNTAX is active. For SYMBOLS to affect a program other than the first program in a compilation unit, it must be preceded by either an ENDUNIT directive or an END PROGRAM statement, which signals the end of the preceding program’s Procedure Division. References: • • ENDUNIT SYNTAX HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -45 Compiler Directives SYNTAX SYNTAX SYNTAX COMPILE VST326.vsd Default: COMPILE Placement: Outside the boundaries of a separately compiled program; that is, not between the Identification Division header of a separately compiled program and its end, which is marked by one of: • • • The corresponding END PROGRAM statement ENDUNIT The end of the source file Scope: The last COMPILE or SYNTAX in the compilation unit applies to the entire compilation unit. Dependencies: SYNTAX overrides RUNNABLE. • • References: ENDUNIT RUNNABLE TANDEM TANDEM ANSI VST327.vsd Default: TANDEM Placement: Anywhere Scope: TANDEM or ANSI within a section of text obtained from a copy library or source library is effective only for the length of that text section. When the compiler reverts to the source file where it found the COPY verb or SOURCE directive, the previously active reference format applies. Dependencies: None References: ANSI HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -46 Compiler Directives TRAP2 and NOTRAP2 TRAP2 and NOTRAP2 Note. The NMCOBOL compiler, which has traps set by default, ignores these directives and issues warnings. Use the NOTRAP2 directive only during the process of conversion from COBOL 74 to HP COBOL. It is provided to enable programs that do not include SIZE ERROR phrases to be compiled and executed in HP COBOL without investing programmer time in analyzing the potential for overflow problems. The availability of this directive might be discontinued after a period of time. TRAP2 NOTRAP2 VST328.vsd Default: TRAP2 Placement: Anywhere Scope: The last TRAP2 or NOTRAP2 before the END PROGRAM statement for the outermost program applies to the entire separately compiled program (the outermost program of a compilation and any programs contained within it). Dependencies: NOTRAP2-74 overrides TRAP2. References: TRAP2-74 and NOTRAP2-74 HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -47 Compiler Directives TRAP2-74 and NOTRAP2-74 TRAP2-74 and NOTRAP2-74 Note. The NMCOBOL compiler, which cannot call COBOL 74 programs, ignores these directives and issues warnings. Use the NOTRAP2-74 directive only during the process of conversion from COBOL 74 to HP COBOL. It is provided to enable programs that do not include SIZE ERROR phrases to be compiled and executed in HP COBOL without investing programmer time in analyzing the potential for overflow problems. The availability of this directive might be discontinued after a period of time. TRAP2-74 NOTRAP2-74 VST329.vsd Default: TRAP2-74 Placement: Anywhere Scope: The last TRAP2-74 or NOTRAP2-74 before the END PROGRAM statement for the outermost program applies to the entire separately compiled program (the outermost program of a compilation and any programs contained within it). Dependencies: NOTRAP2-74 overrides TRAP2. References: TRAP2 and NOTRAP2 UL Note. The COBOL85 compiler does not recognize this directive. UL VST735.vsd Default: None Placement: Before the first IDENTIFICATION DIVISION header of the first program in the compilation unit Scope: Applies to the compilation unit Dependencies: • References: • • • If RUNNABLE is active, UL uses the linker to create a PIC library file (DLL); otherwise, UL creates a PIC linkfile. Do not use with CALL-SHARED, NON-SHARED, or SHARED. CALL-SHARED SHARED HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -48 Compiler Directives WARN and NOWARN WARN and NOWARN WARN NOWARN VST330.vsd Default: WARN Placement: Anywhere Scope: Applies to the compilation unit Dependencies: If LIST is not enabled, the last line of source text processed is also listed to provide a point of reference for each warning message. References: LIST and NOLIST HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -49 Compiler Directives WARN and NOWARN HP COBOL Manual for TNS and TNS/R Programs —522555-006 36 -50 37 Source Program Organization and Format • • Separately Compiled Source Program Reference Format Separately Compiled Source Program Identification Division Environment Division Data Division Procedure Division COBOL85 source program end-program-header VST373.vsd end-program-header PROGRAM END program-name . VST374.vsd Division syntax: • • • • Section 40, Identification Division Section 41, Environment Division Section 42, Data Division Section 43, Procedure Division HP COBOL Manual for TNS and TNS/R Programs —522555-006 37- 1 Source Program Organization and Format Reference Format Reference Format • • TANDEM ANSI TANDEM Figure 37-1. Tandem Reference Format Margin: C Column: A 1 2 B 3 4 5 6 R 7 Area A 8 9 10 ... n* *n <= 132 Area B Indicator Area Line VST500.vsd Table 37-1. Valid Indicator Field Characters (Tandem Reference Format) Valid Character Character Name Means that the line is a … ? Question mark Compiler directive * Asterisk Ordinary comment / Slash Comment to be printed at the top of the next page D Uppercase D Debugging line d Lowercase d Debugging line - Hyphen Continuation line Space Text line HP COBOL Manual for TNS and TNS/R Programs —522555-006 37- 2 Source Program Organization and Format ANSI ANSI Figure 37-2. ANSI Reference Format Margin: L Column: C 1 2 3 4 Sequence Number Area A 5 6 7 8 B R 9 10 11 12 ... 72 73 ... 80 Area A Indicator Field Area B Identification Field Line VST524.vsd Table 37-2. Valid Indicator Area Characters (ANSI Reference Format) Valid Character Character Name Indicates that the line is a … ? Question mark Compiler directive * Asterisk Ordinary comment / Slash Comment to be printed at the top of a page D Uppercase D Debugging line d Lowercase d Debugging line - Hyphen Continuation line HP COBOL Manual for TNS and TNS/R Programs —522555-006 37- 3 Source Program Organization and Format HP COBOL Manual for TNS and TNS/R Programs —522555-006 37- 4 ANSI 38 Language Elements and Expressions • • • • • COBOL Character Set Character-Strings Arithmetic Expressions Conditional Expressions Concatenation Expressions See also Section 21, Reserved Words. COBOL Character Set Figure 38-1. COBOL Character Set COBOL Character Set Alphanumeric Characters (for COBOL words) Letters (A – Z a–z) Digits (0 – 9) Hyphen (–) Punctuation Characters Special Characters VST503.vsd • • • Table 38-1, Alphanumeric Characters (for COBOL Words), on page 38-2 Table 38-2, Punctuation Characters, on page 38-2 Table 38-3, Special Characters, on page 38-2 HP COBOL Manual for TNS and TNS/R Programs —522555-006 38- 1 Language Elements and Expressions Table 38-1. Alphanumeric Characters (for COBOL Words) Characters Name of Character Set 0 through 9 Digits A through Z Uppercase letters a through z Lowercase letters - Hyphen or minus sign Table 38-2. Punctuation Characters Character Name of Character Space , Comma ; Semicolon : Colon . Period " Quotation mark ( Left parenthesis ) Right parenthesis = Equal sign Table 38-3. Special Characters Character Name of Character + Plus sign - Hyphen or minus sign * Asterisk / Stroke or slash $ Dollar sign > Greater than sign < Less than sign HP COBOL Manual for TNS and TNS/R Programs —522555-006 38- 2 COBOL Character Set Language Elements and Expressions Character-Strings Character-Strings • • • COBOL Word Literals PICTURE Character-Strings COBOL Word char-1 ns char-n ns VST741.vsd Maximum length: 30 characters. Literals • • • • Numeric Literals ° ° Decimal Numeric Literal Hexadecimal Numeric Literal Nonnumeric Literals ° ° Simple Nonnumeric Literal Hexadecimal Nonnumeric Literal National Literal Figurative Constants Decimal Numeric Literal ns digits ns + - dp ns digits dp ns digits VST743.vsd Maximum number of digits in one decimal numeric literal: 18. HP COBOL Manual for TNS and TNS/R Programs —522555-006 38- 3 Language Elements and Expressions Literals Hexadecimal Numeric Literal ns H ns ns " hex-digit ns hex-digit " ns VST612.vsd Maximum number of hexadecimal digits: 16 (8 pairs). Simple Nonnumeric Literal char " " VST744.vsd Maximum number of characters: 160. Hexadecimal Nonnumeric Literal ns X ns ns hex-digit " ns hex-digit ns " VST613.vsd Maximum number of hexadecimal digits: 320 (160 pairs). National Literal " char " N n VST745.vsd Maximum number of characters: 160. HP COBOL Manual for TNS and TNS/R Programs —522555-006 38- 4 Language Elements and Expressions Literals Figurative Constants Table 38-4. Figurative Constants Figurative Constant * What It Represents ZERO ZEROS ZEROES One or more of the character zero (0), depending on the context SPACE SPACES One or more spaces, depending on the context HIGH-VALUE HIGH-VALUES One or more of the character that has the highest position in the program collating sequence, except in the SPECIAL-NAMES paragraph, where it represents the character that has the highest position in the ASCII character set (the 256th character, which is all binary ones) or in the national character set (default is hexadecimal FFFF) LOW-VALUE LOW-VALUES One or more of the character that has the lowest position in the program collating sequence, except in the SPECIAL-NAMES paragraph, where it represents the character that has the lowest position in the ASCII character set (the first character, the NUL, which is all binary zeros) or in the national character set (default is hexadecimal 0000) QUOTE QUOTES One or more of the character quotation mark (") symbolic-character One or more of the character specified as the value of symbolic-character in the SYMBOLIC CHARACTERS clause of the SPECIAL-NAMES paragraph ALL literal The value of literal must contain one or more of: You cannot use either of these words instead of quotation marks to enclose a nonnumeric literal. • • • • A nonnumeric literal A national literal A symbolic-character One of the other reserved words previously defined as figurative constants (except that you cannot precede an ALL literal form of figurative constant with another ALL) When literal is a nonnumeric literal or a national literal, this form implies repetition of the literal’s value to the extent required by the context. For the other cases, the word ALL is redundant and is used for readability only. * Singular and plural forms are equivalent and can be used interchangeably. HP COBOL Manual for TNS and TNS/R Programs —522555-006 38- 5 Language Elements and Expressions PICTURE Character-Strings PICTURE Character-Strings • • • PICTURE Character-String Editing Characters Precedence Rules for PICTURE Symbols Precedence Rules for PICTURE Symbols Table 38-5. PICTURE Character-String Editing Characters Character Editing Operation B Space insertion Z Zero suppression 0 Zero + Plus - Minus CR Credit DB Debit * Check protect $ Currency sign , Comma or decimal point . Period or decimal point / Slash HP COBOL Manual for TNS and TNS/R Programs —522555-006 38- 6 Language Elements and Expressions PICTURE Character-Strings Figure 38-2. Precedence Rules for PICTURE Symbols First Symbol Second Symbol NonFloating Insertion Symbols Nonfloating Insertion Symbols Other Symbols Floating Insertion Symbols B 0 / , . + – + CR cs – DB Z Z * * + – + – cs cs 9 A S X V B x x x x x x x x x x x x x x x x x 0 x x x x x x x x x x x x x x x x x / x x x x x x x x x x x x x x x x x , x x x x x x x x x x x x x x x x . x x x x x x x + - x x x x x x x x x x x x x x CR DB x x x x x x x x x x x x x x x x x x x x x P P x + - cs Floating Insertion Symbols Other Symbols x Z * x x x x Z * x x x x + - x x x x + - x x x x cs x x x x cs x x x x x x 9 x x x x x x A X x x x V x x x x x x x x x x x x P x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x x S P x x x cs = currency symbol VST525.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 38- 7 Language Elements and Expressions Arithmetic Expressions Arithmetic Expressions num-id + - num-lit arith-expr arith-expr + * / ** ( arith-expr ) VST739.vsd • • • • Table 38-6, Arithmetic Operators, on page 38-8 Table 38-7, Hierarchy of Operators, on page 38-8 Table 38-8, Precedence in Arithmetic Expressions, on page 38-9 Table 38-9, Operator-Operand Combinations, on page 38-9 Table 38-6. Arithmetic Operators Operator Symbol Kind Meaning + Unary Multiplication by +1 Binary Addition Unary Multiplication by -1 Binary Subtraction * Binary Multiplication / Binary Division ** Binary Exponentiation - Table 38-7. Hierarchy of Operators Hierarchy Operators 1st Unary plus and minus 2nd Exponentiation 3rd Multiplication and division 4th Addition and subtraction HP COBOL Manual for TNS and TNS/R Programs —522555-006 38- 8 Language Elements and Expressions Conditional Expressions Table 38-8. Precedence in Arithmetic Expressions Ambiguous Interpretation *C (A / B) * C A/B/C (A / B) / C A ** B ** C (A ** B) A/B A+B/C+D ** E * F - G ** C ((A + (B / C)) + ((D ** E) * F)) - G Table 38-9. Operator-Operand Combinations Successor Element First Element Variable Binary Operator + - * / ** Unary Operator + or - ( ) Identifier or literal No Yes No No Yes Binary Operator + - * / ** Yes No Yes Yes No Unary Operator + or - Yes No No Yes No ( Yes No Yes Yes No ) No Yes No No Yes Conditional Expressions • • • • • • Simple Relation Condition Simple Class Condition Simple Sign Condition Negated Condition Combined Condition Abbreviated Combined Relation Condition Simple Relation Condition • • Nonpointer Operands Pointer Operands HP COBOL Manual for TNS and TNS/R Programs —522555-006 38- 9 Language Elements and Expressions Simple Relation Condition Nonpointer Operands subject relationship object IS VST118.vsd relationship GREATER NOT LESS THAN EQUAL TO > < = GREATER LESS OR THAN EQUAL TO >= <= VST119.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 38 -10 Language Elements and Expressions Simple Class Condition Pointer Operands pointer-subject relationship pointer-object IS VST602.vsd pointer-subject pointer-object ADDRESS OF identifier-1 identifier-2 NULL NULLS VST603.vsd relationship EQUAL IS NOT TO = VST604.vsd Simple Class Condition identifier IS NOT NUMERIC ALPHABETIC ALPHABETIC-LOWER ALPHABETIC-UPPER class-name VST120.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 38 -11 Language Elements and Expressions Simple Sign Condition Simple Sign Condition arithmetic-expression IS NOT POSITIVE NEGATIVE ZERO VST121.vsd Negated Condition simple-condition NOT ( condition ) VST122.vsd Combined Condition condition condition AND OR VST123.vsd Abbreviated Combined Relation Condition rel-condition combined-part VST124.vsd combined-part AND OR object NOT rel-operator VST125.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 38 -12 Language Elements and Expressions Concatenation Expressions Concatenation Expressions & literal-1 literal-2 figurative-constant figurative-constant concatenation-expr VST801.vsd Table 38-10. Maximum Length of Result of Concatenation Expression Class of Operands Length of Result Alphanumeric 160 alphanumeric character positions National 80 national character positions A figurative constant occupies one character position. Table 38-11. Class of Result of Concatenation Expression Number of Operands That Are Figurative Constants Class of Result 0 Same class as the operands (neither of which is a figurative constant) 1 Same class as the other operand (which is not a figurative constant) 2 Alphanumeric HP COBOL Manual for TNS and TNS/R Programs —522555-006 38 -13 Language Elements and Expressions Concatenation Expressions HP COBOL Manual for TNS and TNS/R Programs —522555-006 38 -14 39 • • • • • • • • • • Data References Qualified Condition-Name Qualified Data-Name Qualified Paragraph-Name Qualified Text-Name Qualified LINAGE-COUNTER Qualified Identifier Subscripted Table Element Reference Modifier OSS Pathname for OSS File OSS Pathname for Guardian File Qualified Condition-Name condition-name OF conditional-variable-name IN mnemonic-name VST001.vsd Qualified Data-Name OF data-name data-name IN OF file-name IN VST002.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 39- 1 Data References Qualified Paragraph-Name Qualified Paragraph-Name OF paragraph-name section-name IN VST003.vsd Qualified Text-Name text-name OF library-name IN VST004.vsd Qualified LINAGE-COUNTER OF LINAGE-COUNTER file-name IN VST005.vsd Qualified Identifier data-name OF qualified-name IN ( ( subscript ) leftmost-character-position : ) length VST009.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 39- 2 Data References Subscripted Table Element Subscripted Table Element ( data-name ) subscript condition-name VST006.vsd subscript integer + - qualified-name index-name offset VST007.vsd Reference Modifier identifier ( leftmost-character-position : ) length VST008.vsd OSS Pathname for OSS File ns OSS /E/ ns node filename / ns ns directory / ns VST634.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 39- 3 Data References OSS Pathname for Guardian File OSS Pathname for Guardian File " ns GUARDIAN ns device " file-id-1 OSS file-id-2 ns /E/ ns ns node VST734.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 39- 4 40 Identification Division IDENTIFICATION DIVISION . PROGRAM-ID paragraph «AUTHOR paragraph» «INSTALLATION paragraph» «DATE-WRITTEN paragraph» «DATE-COMPILED paragraph» «SECURITY paragraph» VST010.vsd PROGRAM-ID paragraph . PROGRAM-ID . program-name program-type IS PROGRAM VST011.vsd program-kind INITIAL COMMON COMMON INITIAL VST012.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 40- 1 Identification Division «AUTHOR paragraph» AUTHOR . comment-entry VST400.vsd «INSTALLATION paragraph» . INSTALLATION comment-entry VST401.vsd «DATE-WRITTEN paragraph» . DATE-WRITTEN comment-entry VST402.vsd «DATE-COMPILED paragraph» . DATE-COMPILED comment-entry VST013.vsd «SECURITY paragraph» SECURITY . comment-entry VST404.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 40- 2 41 Environment Division ENVIRONMENT DIVISION . CONFIGURATION section INPUT-OUTPUT section VST014.vsd • • Configuration Section Input-Output Section Configuration Section CONFIGURATION SECTION . SOURCE-COMPUTER paragraph OBJECT-COMPUTER paragraph SPECIAL-NAMES paragraph VST015.vsd • • • SOURCE-COMPUTER Paragraph OBJECT-COMPUTER Paragraph SPECIAL-NAMES Paragraph HP COBOL Manual for TNS and TNS/R Programs —522555-006 41- 1 Environment Division SOURCE-COMPUTER Paragraph SOURCE-COMPUTER Paragraph . SOURCE-COMPUTER . name DEBUGGING MODE WITH VST016.vsd OBJECT-COMPUTER Paragraph . OBJECT-COMPUTER . name «MEMORY-SIZE clause» PROGRAM COLLATING SEQUENCE clause «SEGMENT-LIMIT clause» CHARACTER-SET clause VST017.vsd «MEMORY-SIZE clause» MEMORY integer SIZE WORDS CHARACTERS MODULES VST018.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41- 2 Environment Division OBJECT-COMPUTER Paragraph PROGRAM COLLATING SEQUENCE clause SEQUENCE PROGRAM COLLATING alphabet-name IS VST019.vsd «SEGMENT-LIMIT clause» segment-number SEGMENT-LIMIT IS VST020.vsd CHARACTER-SET clause character-set-type CHARACTER-SET IS VST021.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41- 3 Environment Division SPECIAL-NAMES Paragraph SPECIAL-NAMES Paragraph SPECIAL-NAMES . . System-Name clause File-Mnemonic clause ALPHABET clause SYMBOLIC CHARACTERS clause CLASS clause CURRENCY SIGN clause DECIMAL-POINT clause VST022.vsd System-Name clause system-name IS mnemonic-name STATUS phrase VST023.vsd STATUS phrase on-phrase off-phrase off-phrase on-phrase VST746.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41- 4 Environment Division SPECIAL-NAMES Paragraph on-phrase switch-on ON STATUS IS VST025.vsd off-phrase switch-off OFF STATUS IS VST026.vsd File-Mnemonic clause FILE IS system-file-name file-mnemonic define-name-literal system-file-name-word VST027.vsd ALPHABET clause ALPHABET alphabet-name IS STANDARD-1 STANDARD-2 NATIVE EBCDIC literal-phrase VST028.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41- 5 Environment Division SPECIAL-NAMES Paragraph literal-phrase literal-1 THROUGH literal-2 THRU ALSO literal-3 VST029.vsd SYMBOLIC-CHARACTERS clause character-list SYMBOLIC CHARACTERS VST030.vsd character-list IS symbolic-char position ARE alphabet-name IN VST031.vsd CLASS clause CLASS class-name IS literal-phrase VST032.vsd literal-phrase literal-1 THROUGH literal-2 THRU VST033.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41- 6 Environment Division Input-Output Section CURRENCY-SIGN clause sign CURRENCY SIGN IS VST034.vsd DECIMAL-POINT clause DECIMAL-POINT COMMA IS VST380.vsd Input-Output Section INPUT-OUTPUT SECTION . FILE-CONTROL paragraph I-O-CONTROL paragraph RECEIVE-CONTROL paragraph VST035.vsd • • • FILE-CONTROL Paragraph I-O-CONTROL Paragraph RECEIVE-CONTROL Paragraph HP COBOL Manual for TNS and TNS/R Programs —522555-006 41- 7 Environment Division FILE-CONTROL Paragraph FILE-CONTROL Paragraph . file-control-entry FILE-CONTROL VST036.vsd file-control-entry • • • • • • Sequential File Line Sequential File Relative File Indexed File Queue File Sort-Merge File Sequential File SELECT clause ASSIGN clause . RESERVE clause ORGANIZATION clause PADDING CHARACTER clause RECORD DELIMITER clause ACCESS MODE clause ALTERNATE RECORD KEY clause FILE STATUS clause VST037.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41- 8 Environment Division FILE-CONTROL Paragraph SELECT clause SELECT file-name OPTIONAL VST038.vsd ASSIGN clause ASSIGN system-file-name define-name-literal TO VST039.vsd RESERVE clause RESERVE number AREA AREAS VST040.vsd ORGANIZATION clause SEQUENTIAL ORGANIZATION IS VST041.vsd PADDING CHARACTER clause pad-char PADDING IS CHARACTER VST042.vsd RECORD DELIMITER clause RECORD DELIMITER STANDARD-1 IS rec-delim VST043.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41- 9 Environment Division FILE-CONTROL Paragraph ACCESS MODE clause ACCESS SEQUENTIAL MODE IS VST044.vsd ALTERNATE RECORD KEY clause ALTERNATE RECORD IS KEY alt-key WITH DUPLICATES VST045.vsd FILE STATUS clause filestat STATUS FILE IS VST046.vsd Line Sequential File SELECT clause ASSIGN clause . RESERVE clause ORGANIZATION clause ACCESS MODE clause FILE STATUS clause VST624.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -10 Environment Division FILE-CONTROL Paragraph SELECT clause SELECT file-name OPTIONAL VST038.vsd ASSIGN clause ASSIGN system-file-name TO VST640.vsd RESERVE clause Ignored. ORGANIZATION clause LINE SEQUENTIAL IS ORGANIZATION VST625.vsd ACCESS MODE clause ACCESS SEQUENTIAL MODE IS VST044.vsd FILE STATUS clause filestat STATUS FILE IS VST046.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -11 Environment Division FILE-CONTROL Paragraph Relative File SELECT clause . ASSIGN clause RESERVE clause ORGANIZATION clause ACCESS MODE clause ALTERNATE RECORD KEY clause FILE STATUS clause VST047.vsd SELECT clause SELECT file-name OPTIONAL VST038.vsd ASSIGN clause ASSIGN system-file-name define-name-literal TO VST039.vsd RESERVE clause RESERVE number AREA AREAS VST040.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -12 Environment Division FILE-CONTROL Paragraph ORGANIZATION clause RELATIVE ORGANIZATION IS VST048.vsd ACCESS MODE clause ACCESS MODE IS SEQUENTIAL RANDOM RELATIVE KEY clause DYNAMIC VST049.vsd RELATIVE KEY clause rel-key RELATIVE KEY IS VST050.vsd ALTERNATE RECORD KEY clause ALTERNATE RECORD IS KEY alt-key WITH DUPLICATES VST045.vsd FILE STATUS clause filestat STATUS FILE IS VST046.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -13 Environment Division FILE-CONTROL Paragraph Indexed File SELECT clause ASSIGN clause RESERVE clause ORGANIZATION clause ACCESS MODE clause . RECORD KEY clause ALTERNATE RECORD KEY clause FILE STATUS clause VST051.vsd SELECT clause SELECT file-name OPTIONAL VST038.vsd ASSIGN clause ASSIGN system-file-name define-name-literal TO VST039.vsd RESERVE clause RESERVE number AREA AREAS VST040.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -14 Environment Division FILE-CONTROL Paragraph ORGANIZATION clause INDEXED ORGANIZATION IS VST052.vsd ACCESS MODE clause ACCESS SEQUENTIAL MODE IS RANDOM DYNAMIC VST053.vsd RECORD KEY clause reckey RECORD KEY IS VST054.vsd ALTERNATE RECORD KEY clause ALTERNATE RECORD IS KEY alt-key WITH DUPLICATES VST045.vsd FILE STATUS clause filestat STATUS FILE IS VST046.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -15 Environment Division FILE-CONTROL Paragraph Queue File SELECT clause ASSIGN clause RESERVE clause ORGANIZATION clause ACCESS MODE clause RECORD KEY clause . FILE STATUS clause VST740.vsd For descriptions of clauses, see Indexed File. Sort-Merge File SELECT clause ASSIGN clause . VST055.vsd SELECT clause SELECT sd-name VST056.vsd ASSIGN clause ASSIGN system-file-name TO define-name-literal VST039.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -16 Environment Division I-O-CONTROL Paragraph I-O-CONTROL Paragraph • • Line Sequential File All Other File Types Line Sequential File I-O-CONTROL . «RERUN clause» . SAME AREA clause VST632.vsd For descriptions of clauses, see All Other File Types. All Other File Types I-O-CONTROL . «RERUN clause» . SAME AREA clause «MULTIPLE FILE clause» VST057.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -17 Environment Division I-O-CONTROL Paragraph «RERUN clause» Note. The 1985 COBOL standard classifies the RERUN clause as obsolete, so you are advised not to use it. RERUN rerun-file ON system-name rerun-file-2-phrase EVERY units CLOCK-UNITS condition VST058.vsd rerun-file-2-phrase recs RECORDS REEL OF END UNIT rerun-file-2 OF VST059.vsd SAME AREA clause SAME RECORD SORT AREA FOR MERGE same-file VST060.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -18 Environment Division RECEIVE-CONTROL Paragraph «MULTIPLE FILE clause» MULTIPLE FILE TAPE CONTAINS tape-file position POSITION VST061.vsd RECEIVE-CONTROL Paragraph RECEIVE-CONTROL . . EXTERNAL TABLE OCCURS phrase SYNCDEPTH LIMIT phrase REPLY CONTAINS phrase ERROR CODE phrase MESSAGE SOURCE phrase REPORT phrase VST063.vsd TABLE OCCURS phrase TABLE OCCURS EXTENDED-STORAGE table-length TIMES VST064.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -19 Environment Division RECEIVE-CONTROL Paragraph SYNCDEPTH LIMIT phrase sync-id SYNCDEPTH LIMIT IS VST065.vsd REPLY CONTAINS phrase REPLY CONTAINS reply-length CHARACTERS file-name RECORD VST066.vsd ERROR CODE phrase error ERROR CODE IS VST067.vsd MESSAGE SOURCE phrase message SOURCE MESSAGE IS VST068.vsd REPORT phrase REPORT message-type MESSAGES VST069.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -20 Environment Division RECEIVE-CONTROL Paragraph message-type Non-CRE environment: ABEND NEWPROCESSNOWAIT-COMPLETION BREAK NODE-DOWN CLOSE NODE-UP CONTROL OPEN CONTROLBUF POWER-ON CPU-DOWN PROCESS-DELETION CPU-UP PROCESS-TIME-SIGNAL DEVICE-INFO REMOTE-CPU-DOWN DEVICE-INFO-2-COMPLETION REMOTE-CPU-UP JOB-PROCESS-CREATION RESETSYNC LOGICAL-CLOSE SETMODE LOGICAL-OPEN SETPARAM MEMORY-LOCK-COMPLETION SETTIME MEMORY-LOCK-FAILURE STATUS-3270 MESSAGE-CANCELLED STOP MESSAGE-MISSED SYSTEM NETWORK TIME-SIGNAL NEWPROCESS-COMPLETION CRE: BREAK NEWPROCESSNOWAIT-COMPLETION CLOSE NODE-DOWN CONTROL NODE-UP CONTROLBUF OPEN CPU-DOWN PATHSEND-DIALOG-ABORT CPU-UP POWER-ON DEVICE-INFO PROCESS-CREATE-COMPLETION DEVICE-INFO-2-COMPLETION PROCESS-DELETION FILE-GETINFOBYNAMECOMPLETION PROCESS-TIME-SIGNAL FILE-FILENAME-COMPLETION REMOTE-CPU-DOWN JOB-PROCESS-CREATION REMOTE-CPU-UP LOGICAL-CLOSE RESETSYNC LOGICAL-OPEN SETMODE MEMORY-LOCK-COMPLETION SETPARAM HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -21 Environment Division RECEIVE-CONTROL Paragraph MEMORY-LOCK-FAILURE SETTIME MESSAGE-CANCELLED STATUS-3270 MESSAGE-MISSED SYSTEM NETWORK TIME-SIGNAL NEWPROCESS-COMPLETION HP COBOL Manual for TNS and TNS/R Programs —522555-006 41 -22 42 Data Division DATA DIVISION . FILE Section WORKING-STORAGE Section EXTENDED-STORAGE Section LINKAGE Section VST070.vsd FILE Section FILE SECTION . 66-or-88 FD-entry 66-or-88 SD-entry 66-or-88 VST071.vsd FD-entry FD file-description 01-data-description VST072.vsd SD-entry SD sort-merge-file-description 01-data-description VST073.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42- 1 Data Division WORKING-STORAGE Section WORKING-STORAGE SECTION . 01-data-description 77-data-description 66-or-88 VST094.vsd EXTENDED-STORAGE Section EXTENDED-STORAGE SECTION . 01-data-description 77-data-description 66-or-88 VST095.vsd LINKAGE Section LINKAGE SECTION . 01-data-description 77-data-description 66-or-88 VST096.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42- 2 Data Division File Descriptions File Descriptions • • • • Sequential File Line Sequential File Relative, Indexed, or Queue File Sort-Merge File Sequential File file-name . EXTERNAL clause GLOBAL clause BLOCK CONTAINS clause RECORD CONTAINS clause «LABEL RECORDS clause» «VALUE OF clause» «DATA RECORDS clause» LINAGE clause CODE-SET clause REPORT clause VST074.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42- 3 Data Division Sequential File EXTERNAL clause EXTERNAL IS VST075.vsd GLOBAL clause GLOBAL IS VST076.vsd BLOCK CONTAINS clause BLOCK blk-2 CONTAINS blk-1 TO RECORDS CHARACTERS VST077.vsd RECORD CONTAINS clause RECORD contains-phrase-fixed «contains-phrase-range» VARYING phrase VST078.vsd contains-fixed-phrase length-fixed CONTAINS CHARACTERS VST079.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42- 4 Data Division Sequential File «contains-phrase-range» length-min TO length-max CONTAINS CHARACTERS VST405.vsd VARYING phrase VARYING IS IN SIZE CHARACTERS length-min FROM length-max TO length-var DEPENDING ON VST092.vsd «LABEL RECORDS clause» LABEL RECORD STANDARD IS OMITTED RECORDS ARE VST083.vsd «VALUE OF clause» VALUE OF label-value label-name OF VST084.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42- 5 Data Division Sequential File «DATA RECORDS clause» DATA rec-name RECORD IS RECORDS ARE VST085.vsd LINAGE clause LINAGE body IS LINES FOOTING foot AT WITH top TOP LINES AT BOTTOM LINES bottom AT VST086.vsd CODE-SET clause alphabet-name CODE-SET IS VST087.vsd REPORT clause report REPORT IS REPORTS ARE VST088.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42- 6 Data Division Line Sequential File Line Sequential File file-name . EXTERNAL clause GLOBAL clause RECORD CONTAINS clause «LABEL RECORDS clause» «VALUE OF clause» «DATA RECORDS clause» REPORT clause VST633.vsd For descriptions of clauses, see Sequential File. HP COBOL Manual for TNS and TNS/R Programs —522555-006 42- 7 Data Division Relative, Indexed, or Queue File Relative, Indexed, or Queue File . file-name EXTERNAL clause GLOBAL clause BLOCK CONTAINS clause RECORD CONTAINS clause «LABEL RECORDS clause» «VALUE OF clause» «DATA RECORDS clause» VST637.vsd For descriptions of clauses, see Sequential File. Sort-Merge File . file-name RECORD CONTAINS clause DATA RECORDS clause VST089.vsd RECORD CONTAINS clause RECORD CONTAINS phrase VARYING phrase VST090.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42- 8 Data Division Data Descriptions CONTAINS phrase length-fixed CONTAINS length-min TO length-max CHARACTERS VST091.vsd VARYING phrase VARYING IS IN length-min SIZE CHARACTERS FROM length-max TO length-var DEPENDING ON VST092.vsd DATA RECORDS clause RECORD DATA data-name IS RECORDS ARE VST093.vsd Data Descriptions • • • • • Record Item (Levels 01 through 49) Level-66 Item Level-77 Item Level-88 Item Clause for Data Descriptions in the Linkage Section HP COBOL Manual for TNS and TNS/R Programs —522555-006 42- 9 Data Division Record Item (Levels 01 through 49) Record Item (Levels 01 through 49) . level data-name-1 FILLER REDEFINES clause EXTERNAL clause GLOBAL clause PICTURE clause USAGE clause SIGN clause OCCURS clause SYNCHRONIZED clause JUSTIFIED clause BLANK WHEN ZERO clause VALUE clause VST098.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42 -10 Data Division Record Item (Levels 01 through 49) USAGE clause BINARY USAGE IS COMPUTATIONAL COMP COMPUTATIONAL-3 COMP-3 COMPUTATIONAL-5 COMP-5 DISPLAY INDEX NATIVE-2 NATIVE-4 NATIVE-8 PACKED-DECIMAL POINTER VST099.vsd SIGN clause LEADING SIGN IS TRAILING SEPARATE CHARACTER VST100.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42 -11 Data Division Record Item (Levels 01 through 49) OCCURS clause For a fixed-size table: OCCURS max TIMES key-order index INDEXED BY VST104.vsd For a variable-size table: OCCURS min TO max TIMES depend DEPENDING ON key-order INDEXED index BY VST106.vsd key-order ASCENDING DESCENDING KEY IS key VST105.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42 -12 Data Division Level-66 Item SYNCHRONIZED clause SYNCHRONIZED SYNC LEFT RIGHT VST101.vsd Level-66 Item 66 new-name THROUGH RENAMES old-name . end-name THRU VST109.vsd Level-77 Item data-name-1 77 FILLER REDEFINES data-name-2 PICTURE clause INDEX USAGE IS SIGN clause OCCURS clause SYNCHRONIZED clause JUSTIFIED clause BLANK WHEN ZERO clause VALUE clause VST110.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42 -13 Data Division Level-88 Item Level-88 Item 88 VALUE condition-name IS VALUES ARE value-1 THROUGH value-2 THRU VST112.vsd Clause for Data Descriptions in the Linkage Section ACCESS MODE IS EXTENDED-STORAGE STANDARD VST097.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 42 -14 43 Procedure Division PROCEDURE DIVISION USING parameter . declaratives-portion paragraph section VST113.vsd declaratives-portion DECLARATIVES section-name . . SECTION segment-number use-sentence paragraph END DECLARATIVES section . VST117.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43- 1 Procedure Division section section-name . SECTION segment-number sentence paragraph VST116.vsd paragraph paragraph-name . sentence VST115.vsd sentence statement . VST114.vsd statement See Statements:. procedure paragraph section VST415.vsd Statements: • • • • • ACCEPT With Mnemonic-Name ACCEPT With DATE, DAY, DAY-OF-WEEK, or TIME Phrase ADD TO ADD GIVING ADD CORRESPONDING HP COBOL Manual for TNS and TNS/R Programs —522555-006 43- 2 Procedure Division • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • ALTER CALL CANCEL CHECKPOINT CLOSE for Sequential and Line Sequential Files CLOSE for Relative, Indexed, and Queue Files COMPUTE CONTINUE COPY DELETE DISPLAY DIVIDE INTO DIVIDE GIVING DIVIDE GIVING REMAINDER ENTER ENTER COBOL EVALUATE EXIT Unconditional GO TO Conditional GO TO Delimited-Scope IF Conditional IF INITIALIZE INSPECT TALLYING INSPECT REPLACING INSPECT TALLYING REPLACING INSPECT CONVERTING LOCKFILE MERGE MOVE TO HP COBOL Manual for TNS and TNS/R Programs —522555-006 43- 3 Procedure Division • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • MOVE CORRESPONDING MULTIPLY BY MULTIPLY GIVING OPEN Unconditional PERFORM PERFORM TIMES PERFORM UNTIL PERFORM VARYING READ for Sequential or Dynamic Access READ for Line Sequential Access READ for Random or Dynamic Access RELEASE REPLACE RETURN REWRITE for Sequential, Relative, Indexed, and Queue Files REWRITE for Line Sequential Files SEARCH VARYING SEARCH ALL SET TO for Pointer Data Items SET TO for Nonpointer Data Items SET UP or SET DOWN for Pointer Data Items SET UP or SET DOWN for Nonpointer Data Items SORT START STARTBACKUP STOP STRING SUBTRACT FROM SUBTRACT GIVING SUBTRACT CORRESPONDING HP COBOL Manual for TNS and TNS/R Programs —522555-006 43- 4 Procedure Division • • • • • • • • ACCEPT With Mnemonic-Name UNLOCKFILE UNLOCKRECORD UNSTRING USE DEBUGGING USE AFTER EXCEPTION WRITE for Sequential Files WRITE for Line Sequential Files WRITE for Relative, Indexed, and Queue Files ACCEPT With Mnemonic-Name accept-name ACCEPT FROM mnemonic-name VST126.vsd ACCEPT With DATE, DAY, DAY-OF-WEEK, or TIME Phrase ACCEPT accept-name FROM DATE YYYYMMDD DAY YYYYDDD DAY-OF-WEEK TIME VST127.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43- 5 Procedure Division ADD TO ADD TO addend ADD TO result ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-ADD VST128.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43- 6 Procedure Division ADD GIVING ADD GIVING addend ADD addend GIVING TO result ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-ADD VST129.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43- 7 Procedure Division ADD CORRESPONDING ADD CORRESPONDING ADD CORRESPONDING group-1 TO group-2 CORR ROUNDED SIZE ERROR ON imperative-stmt-1 NOT ERROR SIZE ON imperative-stmt-2 END-ADD VST130.vsd ALTER ALTER TO paragraph-name destination PROCEED TO VST131.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43- 8 Procedure Division CALL CALL CALL called-entity END-CALL USING phrase on-phrase not-on-phrase historical-on-phrase VST132.vsd called-entity program-name file-mnemonic OF IN identifier VST133.vsd USING phrase USING parameter-1 REFERENCE BY CONTENT VALUE parameter-2 VST134.vsd on-phrase EXCEPTION excp-imperative-statement ON VST615.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43- 9 Procedure Division CANCEL historical-on-phrase excp-imperative-statement EXCEPTION ON OVERFLOW VST135.vsd not-on-phrase NOT EXCEPTION ON non-excp-imperative-statement VST528.vsd CANCEL CANCEL program-name OF file-mnemonic IN identifier VST136.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -10 Procedure Division CHECKPOINT CHECKPOINT Note. • • Do not use this statement in the OSS environment. Before RVU D46.00 and G06.00, software product revision T8107AAT (run-time library T8108AAR), the NMCOBOL compiler ignores this directive and issues a warning. CHECKPOINT data-name-1 FILE data-name-2 file-name FILE QUEUE checkpoint-list-name VST137.vsd CLOSE for Sequential and Line Sequential Files CLOSE file-name file-info VST138.vsd file-info UNIT REEL FOR NO WITH REMOVAL REWIND LOCK VST139.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -11 Procedure Division CLOSE for Relative, Indexed, and Queue Files CLOSE for Relative, Indexed, and Queue Files file-name CLOSE WITH LOCK VST140.vsd COMPUTE result COMPUTE ROUNDED expression = SIZE ERROR imp-stmt-1 ON NOT SIZE ERROR imp-stmt-2 ON END-COMPUTE VST141.vsd CONTINUE CONTINUE VST142.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -12 Procedure Division COPY COPY COPY . text-name OF library-name IN REPLACING phrase VST244.vsd library-name system-file-name define-name-literal VST245.vsd REPLACING phrase . REPLACING OFF original BY new VST247.vsd original pseudo-text-1 identifier-1 literal-1 word-1 VST248.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -13 Procedure Division COPY pseudo-text-1 == == text-word VST250.vsd new pseudo-text-2 identifier-2 literal-2 word-2 VST249.vsd pseudo-text-2 == == text-word VST251.vsd Format of a COPY Library section-text pre-text VST252.vsd section-text ? SECTION text-name , format text-line VST253.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -14 Procedure Division DELETE DELETE DELETE file-name RECORD imperative-stmt-1 INVALID KEY NOT imperative-stmt-2 INVALID KEY END-DELETE VST143.vsd DISPLAY DISPLAY identifier literal UPON mnemonic-name NO ADVANCING WITH VST144.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -15 Procedure Division DIVIDE INTO DIVIDE INTO DIVIDE divisor INTO dividend ROUNDED SIZE ERROR imperative-stmt-1 ON SIZE NOT ERROR ON imperative-stmt-2 END-DIVIDE VST145.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -16 Procedure Division DIVIDE GIVING DIVIDE GIVING divisor DIVIDE INTO dividend BY dividend GIVING divisor quotient ROUNDED SIZE ERROR imperative-stmt-1 ON NOT SIZE ERROR ON imperative-stmt-2 END-DIVIDE VST146.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -17 Procedure Division DIVIDE GIVING REMAINDER DIVIDE GIVING REMAINDER DIVIDE divisor INTO dividend BY dividend GIVING divisor quotient ROUNDED remainder REMAINDER SIZE ERROR imperative-stmt-1 ON SIZE NOT ERROR ON imperative-stmt-2 END-DIVIDE VST147.vsd ENTER ENTER routine-name language file-mnemonic OF IN USING parameter OMITTED GIVING return-value VST148.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -18 Procedure Division ENTER COBOL parameter data-name literal ( arithmetic-expression ) file-name VST149.vsd ENTER COBOL ENTER . COBOL VST150.vsd EVALUATE EVALUATE subject-list WHEN object-list WHEN OTHER match-imp-stmt no-match-imp-stmt END-EVALUATE VST151.vsd subject-list subject ALSO subject VST616.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -19 Procedure Division EVALUATE subject identifier literal expression TRUE FALSE VST152.vsd object-list object ALSO object VST153.vsd object ANY condition TRUE FALSE range NOT VST154.vsd range identifier-1 literal-1 THROUGH identifier-2 arith-exp-1 THRU literal-2 arith-exp-2 VST155.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -20 Procedure Division EXIT EXIT EXIT PROGRAM PARAGRAPH SECTION PERFORM CYCLE VST156.vsd Unconditional GO TO GO TO procedure-name VST158.vsd Conditional GO TO GO procedure-name TO DEPENDING ON depend VST159.vsd Delimited-Scope IF IF condition statement-1 THEN END-IF ELSE statement-2 VST160.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -21 Procedure Division Conditional IF Conditional IF IF condition THEN statement-1 NEXT SENTENCE ELSE statement-2 NEXT SENTENCE VST161.vsd INITIALIZE INITIALIZE receiver REPLACING replacement VST162.vsd replacement ALPHABETIC ALPHANUMERIC NUMERIC ALPHANUMERIC-EDITED NUMERIC-EDITED BY DATA sender literal VST163.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -22 Procedure Division INSPECT TALLYING INSPECT TALLYING INSPECT source-string tallying-phrase VST164.vsd tallying-phrase TALLYING tally FOR for-clause VST165.vsd for-clause CHARACTERS position ALL compare-string LEADING position VST166.vsd position BEFORE AFTER delim-string INITIAL VST167.vsd INSPECT REPLACING INSPECT source-string replacing-phrase VST168.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -23 Procedure Division INSPECT REPLACING replacing-phrase REPLACING absolute-replacement matching-replacement VST169.vsd absolute-replacement CHARACTERS BY replace-string position VST170.vsd position BEFORE AFTER delim-string INITIAL VST167.vsd matching-replacement ALL LEADING FIRST compare-string BY replace-string position VST172.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -24 Procedure Division INSPECT TALLYING REPLACING INSPECT TALLYING REPLACING INSPECT source-string tallying-phrase replacing-phrase VST174.vsd tallying-phrase TALLYING tally FOR for-clause VST165.vsd for-clause CHARACTERS position ALL compare-string LEADING position VST166.vsd position BEFORE AFTER delim-string INITIAL VST167.vsd replacing-phrase REPLACING absolute-replacement matching-replacement VST169.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -25 Procedure Division INSPECT TALLYING REPLACING absolute-replacement CHARACTERS BY replace-string position VST170.vsd position BEFORE AFTER delim-string INITIAL VST167.vsd matching-replacement ALL LEADING FIRST compare-string BY replace-string position VST172.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -26 Procedure Division INSPECT CONVERTING INSPECT CONVERTING INSPECT source-string CONVERTING match VST175.vsd match compare-string TO replace-string position VST173.vsd position BEFORE AFTER delim-string INITIAL VST167.vsd LOCKFILE LOCKFILE file-name TIME LIMIT wait-time VST176.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -27 Procedure Division MERGE MERGE MERGE merge-file key-specifier COLLATING SEQUENCE phrase USING phrase output-specifier VST177.vsd key-specifier ASCENDING ON DESCENDING key KEY VST178.vsd COLLATING SEQUENCE phrase SEQUENCE COLLATING alphabet-name IS VST179.vsd USING phrase USING merge-in-1 merge-in-2 merge-in-n VST180.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -28 Procedure Division MOVE TO output-specifier OUTPUT PROCEDURE outproc-1 IS THROUGH outproc-2 THRU GIVING merge-out VST181.vsd MOVE TO MOVE sender TO receiver VST182.vsd MOVE CORRESPONDING MOVE CORRESPONDING group-1 TO group-2 CORR VST183.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -29 Procedure Division MULTIPLY BY MULTIPLY BY MULTIPLY BY multiplicand multiplier ROUNDED SIZE ERROR imperative-stmt-1 ON NOT SIZE ERROR ON imperative-stmt-2 END-MULTIPLY VST184.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -30 Procedure Division MULTIPLY GIVING MULTIPLY GIVING MULTIPLY BY multiplicand multiplier GIVING result ROUNDED SIZE ERROR imperative-stmt-1 ON NOT SIZE ERROR ON imperative-stmt-2 END-MULTIPLY VST185.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -31 Procedure Division OPEN OPEN OPEN file-specification VST186.vsd file-specification INPUT input-file-description OUTPUT I-O output-file-description i-o-file-description EXTEND extend-file-description VST187.vsd input-file-description For a sequential, relative, indexed, or queue file: infile TIME LIMITS WITH SHARED SYNCDEPTH PROTECTED «REVERSED» EXCLUSIVE sync NO REWIND WITH VST188.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -32 Procedure Division OPEN For a line sequential file: infile SHARED PROTECTED EXCLUSIVE VST627.vsd output-file-description For a sequential, relative, indexed, or queue file: outfile TIME LIMITS WITH SHARED SYNCDEPTH PROTECTED sync NO EXCLUSIVE REWIND WITH VST189.vsd For a line sequential file: outfile SHARED PROTECTED EXCLUSIVE VST628.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -33 Procedure Division OPEN i-o-file-description For a sequential, relative, indexed, or queue file: iofile TIME LIMITS WITH SYNCDEPTH SHARED sync PROTECTED EXCLUSIVE VST190.vsd For a line sequential file: iofile SHARED PROTECTED EXCLUSIVE VST626.vsd extend-file-description For a sequential, relative, indexed, or queue file: extfile TIME LIMITS WITH SHARED SYNCDEPTH sync PROTECTED EXCLUSIVE VST191.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -34 Procedure Division Unconditional PERFORM For a line sequential file: extfile SHARED PROTECTED EXCLUSIVE VST629.vsd Unconditional PERFORM PERFORM procedure-group END-PERFORM imperative-statement VST192.vsd procedure-group proc-1 THROUGH proc-2 THRU VST193.vsd PERFORM TIMES PERFORM procedure-group count count TIMES TIMES imperative-statement END-PERFORM VST194.vsd procedure-group proc-1 THROUGH proc-2 THRU VST193.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -35 Procedure Division PERFORM UNTIL PERFORM UNTIL PERFORM procedure-group test-site UNTIL condition UNTIL condition test-site END-PERFORM imperative-statement VST196.vsd procedure-group proc-1 THROUGH proc-2 THRU VST193.vsd test-site TEST WITH BEFORE AFTER VST197.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -36 Procedure Division PERFORM VARYING PERFORM VARYING PERFORM procedure-group test-site varying-phrase after-phrase varying-phrase test-site after-phrase imperative-statement END-PERFORM VST198.vsd procedure-group proc-1 THROUGH proc-2 THRU VST193.vsd test-site TEST BEFORE WITH AFTER VST197.vsd varying-phrase VARYING UNTIL vary-1 FROM base-1 BY step-1 condition-1 VST199.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -37 Procedure Division READ for Sequential or Dynamic Access after-phrase AFTER FROM vary-2 UNTIL base-2 BY step-2 condition-2 VST200.vsd READ for Sequential or Dynamic Access READ file-name NEXT REVERSED RECORD INTO data-name LOCK WITH TIME PROMPT LIMIT END prompt-item wait-time imperative-stmt-1 AT NOT END imperative-stmt-2 AT END-READ VST201.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -38 Procedure Division READ for Line Sequential Access READ for Line Sequential Access READ file-name INTO data-name END imperative-stmt-1 AT NOT END imperative-stmt-2 AT END-READ VST630.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -39 Procedure Division READ for Random or Dynamic Access READ for Random or Dynamic Access READ file-name RECORD INTO data-name LOCK WITH TIME LIMIT wait-time KEY key IS INVALID imperative-stmt-1 KEY NOT INVALID KEY imperative-stmt-2 END-READ VST202.vsd RELEASE RELEASE record-name FROM data-name VST203.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -40 Procedure Division REPLACE REPLACE REPLACE pseudo-text-1 BY pseudo-text-2 . OFF VST254.vsd pseudo-text-1 == text-word == VST250.vsd pseudo-text-2 == == text-word VST251.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -41 Procedure Division RETURN RETURN RETURN file-name INTO END data-name imperative-stmt-1 AT NOT END imperative-stmt-2 AT END-RETURN VST204.vsd REWRITE for Sequential, Relative, Indexed, and Queue Files REWRITE record-name FROM data-name UNLOCK WITH INVALID imperative-stmt-1 KEY NOT INVALID KEY imperative-stmt-2 END-REWRITE VST205.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -42 Procedure Division REWRITE for Line Sequential Files REWRITE for Line Sequential Files REWRITE FROM record-name data-name END-REWRITE VST721.vsd SEARCH VARYING SEARCH table END VARYING indexer imperative-stmt-1 AT WHEN condition imperative-stmt-2 NEXT SENTENCE END-SEARCH VST206.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -43 Procedure Division SEARCH ALL SEARCH ALL SEARCH ALL table END imperative-stmt-1 AT WHEN match-1 AND match-n imperative-stmt-2 NEXT SENTENCE END-SEARCH VST207.vsd match-1 match-n identifier-1 equal-part identifier-2 literal-2 arithmetic-expression-2 condition-name-1 VST208.vsd equal-part EQUAL IS TO = VST209.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -44 Procedure Division SET TO for Pointer Data Items SET TO for Pointer Data Items SET TO pointer address VST605.vsd pointer ADDRESS OF identifier-1 identifier-2 VST606.vsd address ADDRESS OF identifier-3 identifier-4 NULL NULLS VST607.vsd SET TO for Nonpointer Data Items SET TO identifier-1 identifier-2 index-name-2 index-name-1 integer mnemonic-name TO ON OFF condition-name TO TRUE VST211.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -45 Procedure Division SET UP or SET DOWN for Pointer Data Items SET UP or SET DOWN for Pointer Data Items SET UP pointer BY number-of-locations DOWN VST608.vsd number-of-locations identifier-1 integer VST609.vsd SET UP or SET DOWN for Nonpointer Data Items SET UP index-name BY DOWN identifier integer VST212.vsd SORT SORT sd-name key-specifier DUPLICATES phrase COLLATING SEQUENCE phrase input-specifier-1 output-specifier-1 input-specifier-2 output-specifier-2 VST213.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -46 Procedure Division SORT key-specifier ASCENDING ON key DESCENDING KEY VST214.vsd DUPLICATES phrase DUPLICATES WITH IN ORDER VST215.vsd COLLATING SEQUENCE phrase SEQUENCE COLLATING alphabet-name IS VST216.vsd input-specifier-1 INPUT PROCEDURE inproc-1 IS THROUGH inproc-2 THRU VST217.vsd input-specifier-2 USING infile VST381.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -47 Procedure Division START output-specifier-1 OUTPUT PROCEDURE outproc-1 IS THROUGH outproc-2 THRU VST218.vsd output-specifier-2 GIVING outfile VST382.vsd START START file-name KEY phrase APPROXIMATE GENERIC TIME LIMIT wait-time INVALID imperative-stmt-1 KEY NOT INVALID imperative-stmt-2 KEY END-START VST219.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -48 Procedure Division START KEY phrase KEY relationship key IS position VST220.vsd relationship GREATER THAN OR EQUAL TO > >= = LESS NOT THAN < VST221.vsd If position is present, relationship is limited to: EQUAL TO = VST223.vsd position POSITION position-key BEFORE AFTER VST222.vsd Note. BEFORE is available only for the NMCOBOL compiler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -49 Procedure Division STARTBACKUP STARTBACKUP Note. • • Do not use this statement in the OSS environment. Before RVU D46.00 and G06.00, software product revision T8107AAT (run-time library T8108AAR), the NMCOBOL compiler ignores this directive and issues a warning. STARTBACKUP cpu options backup-ext VST224.vsd options 0 The fault-tolerant facility is to read and process system messages, and the primary process is to terminate abnormally if a trap condition occurs. 1 Same as option 0 except that if the primary process stops, the backup process takes over processing of the application. 2 Same as option 1 except that if the primary process encounters a trap condition, it enters the DEBUG procedure instead of being terminated abnormally. 3 The primary process, rather than the fault-tolerant facility, reads the $RECEIVE file and takes appropriate action for system messages. In addition, if the primary process encounters a trap condition, it enters the DEBUG procedure. When this option is in force and the backup process fails, the primary process must re-execute the STARTBACKUP statement to reestablish the backup. STOP STOP RUN «message» VST225.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -50 Procedure Division STRING STRING STRING DELIMITED part-1 delimiter BY INTO SIZE result POINTER pointer WITH OVERFLOW imperative-stmt-1 ON NOT OVERFLOW imperative-stmt-2 ON END-STRING VST226.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -51 Procedure Division SUBTRACT FROM SUBTRACT FROM SUBTRACT subtrahend FROM minuend-result ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-SUBTRACT VST227.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -52 Procedure Division SUBTRACT GIVING SUBTRACT GIVING SUBTRACT GIVING FROM subtrahend minuend result ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-SUBTRACT VST228.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -53 Procedure Division SUBTRACT CORRESPONDING SUBTRACT CORRESPONDING Caution. SUBTRACT CORRESPONDING is not recommended, because minor changes to one data structure can change the correspondence between its elements and those of the other data structure, and this is difficult to detect. SUBTRACT CORRESPONDING group-1 CORR FROM group-2 ROUNDED SIZE ERROR ON imperative-stmt-1 NOT SIZE ERROR ON imperative-stmt-2 END-SUBTRACT VST229.vsd UNLOCKFILE UNLOCKFILE file-name VST230.vsd UNLOCKRECORD UNLOCKRECORD file-name VST231.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -54 Procedure Division UNSTRING UNSTRING UNSTRING source DELIMITED delim-1 BY OR ALL delim-2 ALL INTO result-list POINTER pointer WITH TALLYING tally IN OVERFLOW imperative-stmt-1 ON NOT OVERFLOW imperative-stmt-2 ON END-UNSTRING VST232.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -55 Procedure Division USE DEBUGGING result-list result DELIMITER delimstore IN COUNT count IN VST233.vsd USE DEBUGGING Note. The 1985 COBOL standard classifies USE DEBUGGING as obsolete, so you are advised not to use it, even in TNS HP COBOL programs. The NMCOBOL compiler does not recognize it. USE DEBUGGING FOR ON ALL REFERENCES OF . name filename procedure ALL PROCEDURES VST234.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -56 Procedure Division USE AFTER EXCEPTION USE AFTER EXCEPTION Note. If you are using the NMCOBOL compiler, do not use GLOBAL in a USE AFTER EXCEPTION statement in the declaratives-portion. USE AFTER GLOBAL EXCEPTION STANDARD PROCEDURE ERROR ON file-name . INPUT OUTPUT I-O EXTEND VST235.vsd WRITE for Sequential Files WRITE record-name FROM ADVANCING clause NOT from-name end-of-page clause not-end-of-page clause invalid-key-phrase NOT not-invalid-key-phrase END-WRITE VST236.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -57 Procedure Division WRITE for Sequential Files ADVANCING clause BEFORE AFTER ADVANCING LINE no-of-lines LINES mnemonic-name PAGE VST237.vsd end-of-page clause END-OF-PAGE AT imperative-statement EOP VST238.vsd not-end-of-page clause END-OF-PAGE AT imperative-statement EOP VST238.vsd invalid-key-phrase INVALID imperative-statement KEY VST239.vsd not-invalid-key-phrase INVALID imperative-statement KEY VST239.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -58 Procedure Division WRITE for Line Sequential Files WRITE for Line Sequential Files WRITE record-name FROM END-WRITE from-name VST631.vsd WRITE for Relative, Indexed, and Queue Files WRITE record-name FROM from-name invalid-key NOT not-invalid-key END-WRITE VST240.vsd invalid-key INVALID imperative-statement KEY VST239.vsd not-invalid-key INVALID imperative-statement KEY VST239.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -59 Procedure Division WRITE for Relative, Indexed, and Queue Files HP COBOL Manual for TNS and TNS/R Programs —522555-006 43 -60 44 • • • • • • • • • • • • • • • • • • • • • • • • • • • • • Intrinsic Function Calls ACOS ANNUITY ASIN ATAN CHAR COS CURRENT-DATE DATE-OF-INTEGER DAY-OF-INTEGER FACTORIAL INTEGER INTEGER-OF-DATE INTEGER-OF-DAY INTEGER-PART LENGTH LOG LOG10 LOWER-CASE MAX MEAN MEDIAN MIDRANGE MIN MOD NUMVAL NUMVAL-C ORD ORD-MAX ORD-MIN HP COBOL Manual for TNS and TNS/R Programs —522555-006 44- 1 Intrinsic Function Calls • • • • • • • • • • • • • ACOS PRESENT-VALUE RANDOM RANGE REM REVERSE SIN SQRT STANDARD-DEVIATION SUM TAN UPPER-CASE VARIANCE WHEN-COMPILED ACOS FUNCTION ACOS ( argument ) VST421.vsd Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. ANNUITY FUNCTION ( ANNUITY interest-rate number-of-periods ) VST422.vsd Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. HP COBOL Manual for TNS and TNS/R Programs —522555-006 44- 2 Intrinsic Function Calls ASIN ASIN FUNCTION ( ASIN ) argument VST423.vsd Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. ATAN FUNCTION ( ATAN ) argument VST424.vsd Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. CHAR FUNCTION ( CHAR ) argument VST425.vsd COS FUNCTION COS ( argument ) VST426.vsd Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. CURRENT-DATE FUNCTION CURRENT-DATE VST427.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44- 3 Intrinsic Function Calls DATE-OF-INTEGER DATE-OF-INTEGER FUNCTION ( DATE-OF-INTEGER ) argument VST428.vsd DAY-OF-INTEGER FUNCTION ( DAY-OF-INTEGER ) argument VST429.vsd FACTORIAL FUNCTION ( FACTORIAL ) argument VST430.vsd INTEGER FUNCTION INTEGER ( argument ) VST431.vsd INTEGER-OF-DATE FUNCTION ( INTEGER-OF-DATE ) argument VST432.vsd INTEGER-OF-DAY FUNCTION INTEGER-OF-DAY ( argument ) VST433.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44- 4 Intrinsic Function Calls INTEGER-PART INTEGER-PART FUNCTION ( INTEGER-PART ) argument VST434.vsd LENGTH FUNCTION ( LENGTH ) argument VST435.vsd LOG FUNCTION LOG ( ) argument VST436.vsd LOG10 FUNCTION ( LOG10 ) argument VST437.vsd Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. LOWER-CASE FUNCTION LOWER-CASE ( string ) VST438.vsd MAX FUNCTION MAX ( argument ) VST439.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44- 5 Intrinsic Function Calls MEAN MEAN FUNCTION ( MEAN ) argument VST440.vsd MEDIAN FUNCTION ( MEDIAN ) argument VST441.vsd MIDRANGE FUNCTION MIDRANGE ( ) argument VST442.vsd MIN FUNCTION MIN ( argument ) VST443.vsd MOD FUNCTION MOD ( argument-1 argument-2 ) VST444.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44- 6 Intrinsic Function Calls NUMVAL NUMVAL FUNCTION ( NUMVAL ) string VST445.vsd string " sp " number + - sp sp number + - sp CR DB VST446.vsd number digits ns . ns digits . ns digits VST447.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44- 7 Intrinsic Function Calls NUMVAL-C NUMVAL-C FUNCTION NUMVAL-C ( ) value-1 value-2 currency-sign VST448.vsd value-1 + spaces spaces number currency-sign spaces spaces VST450.vsd value-2 spaces currency-sign spaces number spaces + - spaces CR DB VST385.vsd number ns digits digits ns ns . ns digits . ns digits VST451.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44- 8 Intrinsic Function Calls ORD ORD FUNCTION ORD ( argument ) VST452.vsd ORD-MAX FUNCTION ORD-MAX ( ) argument VST435.vsd ORD-MIN FUNCTION ORD-MIN ( ) argument VST454.vsd PRESENT-VALUE FUNCTION ( PRESENT-VALUE discount-rate ) period-end-amount VST455.vsd RANDOM FUNCTION RANDOM ( argument ) VST456.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44- 9 Intrinsic Function Calls RANGE RANGE FUNCTION ( RANGE ) argument VST457.vsd REM FUNCTION ( REM dividend divisor ) VST458.vsd REVERSE FUNCTION ( REVERSE ) argument VST459.vsd SIN FUNCTION SIN ( argument ) VST460.vsd Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. SQRT FUNCTION SQRT ( argument ) VST461.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44 -10 Intrinsic Function Calls STANDARD-DEVIATION STANDARD-DEVIATION FUNCTION ( STANDARD-DEVIATION argument ) VST462.vsd Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. SUM FUNCTION ( SUM ) argument VST463.vsd TAN FUNCTION TAN ( argument ) VST464.vsd Note. This function requires the CRE. To use this function in a TNS HP COBOL program, compile the program with the directive ENV COMMON. UPPER-CASE FUNCTION ( UPPER-CASE ) string VST465.vsd VARIANCE FUNCTION VARIANCE ( argument ) VST466.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44 -11 Intrinsic Function Calls WHEN-COMPILED WHEN-COMPILED FUNCTION WHEN-COMPILED VST467.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 44 -12 45 CBL85UTL and ZCOBSRL Routine Calls Table 45-1. CBL85UTL and ZCOBSRL Routines COBOL-Environment Routine1 CRE Routine for Guardian Environment2 COBOL85^ARMTRAP None (unnecessary) COBOL85^COMPLETION COBOL_COMPLETION_ None COBOL_CONTROL_ None COBOL_GETENV_ None COBOL_PUTENV_ COBOL85^RETURN^SORT^ERRORS3 COBOL_RETURN_SORT_ERRORS_3 COBOL85^REWIND^SEQUENTIAL COBOL_REWIND_SEQUENTIAL_ COBOL85^SET^SORT^PARAM^TEXT3 COBOL_SET_SORT_PARAM_TEXT_3 COBOL85^SET^SORT^PARAM^VALUE3 COBOL_SET_SORT_PARAM_VALUE_3 None COBOL_SET_MAX_RECORD_ None COBOL_SETMODE_ COBOL85^SPECIAL^OPEN2 COBOL_SPECIAL_OPEN_4 1. These routines are only in CBL85UTL, not in ZCOBSRL. 2. These routines are in both CBL85UTL and ZCOBSRL. 3. FastSort interface routine. 4. This routine replaces the COBOLSPOOLOPEN routine (for level 2 spooling) and Guardian environment routines (for level 3 spooling). The COBOLSPOOLOPEN routine is in the COBOLLIB library. If you omit an optional parameter when you call a CBL85UTL or ZCOBSRL routine, you must put the keyword OMITTED in its position if you specify subsequent parameters. Trailing OMITTEDs are not required. (The syntax diagrams do not reflect this, because it would make them much harder to read.) • • • • • • • • COBOL85^ARMTRAP COBOL85^COMPLETION COBOL_COMPLETION_ COBOL_CONTROL_ COBOL_GETENV_ COBOL_PUTENV_ COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ HP COBOL Manual for TNS and TNS/R Programs —522555-006 45- 1 CBL85UTL and ZCOBSRL Routine Calls • • • • • COBOL85^ARMTRAP COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ COBOL_SET_MAX_RECORD_ COBOL_SETMODE_ COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ COBOL85^ARMTRAP ns ENTER ns COBOL85^ARMTRAP " " VST341.vsd COBOL85^COMPLETION ns ENTER " ns COBOL85^COMPLETION " TAL OF library-reference USING abend-or-stop completion-code termination-info subsys-id text-length text VST342.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 45- 2 CBL85UTL and ZCOBSRL Routine Calls COBOL_COMPLETION_ COBOL_COMPLETION_ ns ENTER ns COBOL_COMPLETION_ " " TAL OF library-reference USING abend-or-stop completion-code termination-info subsys-id text VST343.vsd COBOL_CONTROL_ Caution. The HP COBOL run-time library does not attempt to validate calls to CONTROL. To avoid interfering with the operation of the HP COBOL run-time library, use COBOL_CONTROL_ only if absolutely necessary. " ENTER OF ns COBOL_CONTROL_ ns " library-reference USING file-name GIVING operation param error-return cpinfo VST610.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 45- 3 CBL85UTL and ZCOBSRL Routine Calls COBOL_GETENV_ COBOL_GETENV_ ns ENTER ns COBOL_GETENV_ " USING env-var GIVING length " return-value VST722.vsd COBOL_PUTENV_ " ENTER ns COBOL_PUTENV_ USING env-var GIVING return-value ns " VST723.vsd COBOL85^RETURN^SORT^ERRORS and COBOL_RETURN_SORT_ERRORS_ " ENTER ns COBOL85^RETURN^SORT^ERRORS ns " COBOL_RETURN_SORT_ERRORS_ OF library-reference USING sd-name error-report GIVING return-code VST344.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 45- 4 CBL85UTL and ZCOBSRL Routine Calls COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ COBOL85^REWIND^SEQUENTIAL and COBOL_REWIND_SEQUENTIAL_ ENTER " ns COBOL85^REWIND^SEQUENTIAL ns " COBOL_REWIND_SEQUENTIAL_ OF library-reference USING file-name GIVING return-code VST345.vsd COBOL85^SET^SORT^PARAM^TEXT and COBOL_SET_SORT_PARAM_TEXT_ " ENTER ns COBOL85^SET^SORT^PARAM^TEXT ns " COBOL_SET_SORT_PARAM_TEXT_ OF library-reference USING param-id sd-name param-text subsort-number GIVING return-code VST346.vsd Note. COBOL85 only: COBOL_SET_SORT_PARAM_TEXT_ use a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 45- 5 CBL85UTL and ZCOBSRL Routine Calls COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ ns " ENTER COBOL85^SET^SORT^PARAM^VALUE ns " COBOL_SET_SORT_PARAM_VALUE_ OF library-reference USING sd-name param-id param-value GIVING subsort-or-file-number return-code VST347.vsd Note. COBOL85 only: COBOL85^SET^SORT^PARAM^VALUE and COBOL_SET_SORT_PARAM_VALUE_ use a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. COBOL_SET_MAX_RECORD_ ns ENTER " USING ns COBOL_SET_MAX_RECORD_ " file-name new-length GIVING result VST737.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 45- 6 CBL85UTL and ZCOBSRL Routine Calls COBOL_SETMODE_ COBOL_SETMODE_ Caution. The HP COBOL run-time library does not attempt to validate calls to SETMODE. To avoid interfering with the operation of the HP COBOL run-time library, use COBOL_SETMODE_ only if absolutely necessary. ENTER " OF ns COBOL_SETMODE_ ns " library-reference USING file-name function param-1 param-2 lastparams cpinfo GIVING error-return VST611.vsd COBOL85^SPECIAL^OPEN and COBOL_SPECIAL_OPEN_ • • • • For Spoolers and Printers For System Log Files For Partitioned Disk Files For Tape Files in the CRE HP COBOL Manual for TNS and TNS/R Programs —522555-006 45- 7 CBL85UTL and ZCOBSRL Routine Calls For Spoolers and Printers For Spoolers and Printers ENTER ns " COBOL85^SPECIAL^OPEN ns " COBOL_SPECIAL_OPEN_ OF library-reference USING file-name open-type = 1 exclusion sync-depth no-eject level-3 location form-name report-name copies page-size flags owner max-lines max-pages code-129 form-feed GIVING return-code VST348.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 45- 8 CBL85UTL and ZCOBSRL Routine Calls For System Log Files For System Log Files ENTER " ns COBOL85^SPECIAL^OPEN ns " COBOL_SPECIAL_OPEN_ OF library-reference USING file-name open-type = 2 exclusion sync-depth GIVING time-limits return-code VST349.vsd For Partitioned Disk Files ENTER " ns COBOL85^SPECIAL^OPEN ns " COBOL_SPECIAL_OPEN_ OF library-reference USING file-name open-type = 3 exclusion sync-depth open-mode GIVING time-limits return-code VST350.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 45- 9 CBL85UTL and ZCOBSRL Routine Calls For Tape Files in the CRE For Tape Files in the CRE ns ENTER " OF ns COBOL_SPECIAL_OPEN_ " library-reference USING file-name open-type = 4 exclusion sync-depth time-limits open-mode mount-messages end-of-tape-process GIVING return-code VST614.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 45 -10 46 COBOLLIB, CLULIB, and ZCRESRL Routine Calls • • SMU Routines Non-SMU Routines Note. If you omit an optional parameter when you call a COBOLLIB routine, you must put the keyword OMITTED in its position if you specify subsequent parameters. Trailing OMITTEDs are not required. (The syntax diagrams do not reflect this, because it would make them much harder to read.) SMU Routines Programs compiled with the COBOL85 compiler can call all of the SMU routines listed in Table 46-1. Programs compiled with the NMCOBOL compiler can call only the new routines. For more information about the new SMU routines, see the CRE Programmer’s Guide. Table 46-1. Saved Message Utility (SMU) Routines (page 1 of 2) Original Routine1 New Routine2 ALTERPARAMTEXT None CHECKLOGICALNAME SMU_Assign_CheckName_ CHECKMESSAGE SMU_Message_CheckNumber_ DELETEASSIGN SMU_Assign_Delete_ DELETEPARAM SMU_Param_Delete_ DELETESTARTUP SMU_Startup_Delete_ GETASSIGNTEXT SMU_Assign_GetText_ GETASSIGNVALUE SMU_Assign_GetValue_ GETBACKUPCPU None GETPARAMTEXT SMU_Param_GetText_3 GETSTARTUPTEXT SMU_Startup_GetText_ PUTASSIGNTEXT SMU_Assign_PutText_ 1. In the COBOLLIB file. Extension to the HP COBOL and FORTRAN 77 products, except as noted. 2. In the CLULIB file for the COBOL85 compiler and the ZCRESRL file for the NMCOBOL compiler. 3. In the OSS environment, you can also use the HP C getenv function. SMU_Param_GetText_ returns only PARAM equivalents, but the HP C getenv function returns other environment variables as well. 4. Not an extension to the HP COBOL and FORTRAN 77 products. HP COBOL Manual for TNS and TNS/R Programs —522555-006 46- 1 COBOLLIB, CLULIB, and ZCRESRL Routine Calls SMU Routines Table 46-1. Saved Message Utility (SMU) Routines (page 2 of 2) Original Routine1 New Routine2 PUTASSIGNVALUE SMU_Assign_PutValue_ PUTPARAMTEXT4 SMU_Param_PutText_ PUTSTARTUPTEXT SMU_Startup_PutText_ 1. In the COBOLLIB file. Extension to the HP COBOL and FORTRAN 77 products, except as noted. 2. In the CLULIB file for the COBOL85 compiler and the ZCRESRL file for the NMCOBOL compiler. 3. In the OSS environment, you can also use the HP C getenv function. SMU_Param_GetText_ returns only PARAM equivalents, but the HP C getenv function returns other environment variables as well. 4. Not an extension to the HP COBOL and FORTRAN 77 products. • • • • • • • • • • • • • • • ALTERPARAMTEXT CHECKLOGICALNAME CHECKMESSAGE DELETEASSIGN DELETEPARAM DELETESTARTUP GETASSIGNTEXT GETASSIGNVALUE GETBACKUPCPU GETPARAMTEXT GETSTARTUPTEXT PUTASSIGNTEXT PUTASSIGNVALUE PUTPARAMTEXT PUTSTARTUPTEXT HP COBOL Manual for TNS and TNS/R Programs —522555-006 46- 2 COBOLLIB, CLULIB, and ZCRESRL Routine Calls ALTERPARAMTEXT ALTERPARAMTEXT ns ENTER OF ns ALTERPARAMTEXT " " library-reference USING portion GIVING result text cplist size VST351.vsd Note. ALTERPARAMTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. CHECKLOGICALNAME " ENTER OF ns ns CHECKLOGICALNAME " library-reference USING logical-name GIVING result VST352.vsd logical-name file-name program-unit . * VST639.vsd Note. CHECKLOGICALNAME uses a protocol different from that used by normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 46- 3 COBOLLIB, CLULIB, and ZCRESRL Routine Calls CHECKMESSAGE CHECKMESSAGE ns ENTER " ns CHECKMESSAGE " TAL OF library-reference USING message-number GIVING result VST353.vsd DELETEASSIGN ns ENTER " OF ns DELETEASSIGN " library-reference USING portion GIVING result cplist message-number VST360.vsd Note. DELETEASSIGN uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 46- 4 COBOLLIB, CLULIB, and ZCRESRL Routine Calls DELETEPARAM DELETEPARAM ns ENTER OF ns DELETEPARAM " " library-reference USING portion GIVING result cplist VST361.vsd Note. DELETEPARAM uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. DELETESTARTUP ns ENTER " OF ns DELETESTARTUP " library-reference USING portion GIVING result cplist VST362.vsd Note. DELETESTARTUP uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 46- 5 COBOLLIB, CLULIB, and ZCRESRL Routine Calls GETASSIGNTEXT GETASSIGNTEXT ns ENTER OF ns GETASSIGNTEXT " " library-reference USING portion GIVING result text message-number VST363.vsd Note. GETASSIGNTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. GETASSIGNVALUE ns ENTER " OF ns GETASSIGNVALUE " library-reference USING portion GIVING result val message-number VST364.vsd Note. GETASSIGNVALUE uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 46- 6 COBOLLIB, CLULIB, and ZCRESRL Routine Calls GETBACKUPCPU GETBACKUPCPU ns ENTER " ns GETBACKUPCPU " TAL OF library-reference GIVING result VST365.vsd GETPARAMTEXT ns ENTER " OF ns GETPARAMTEXT " library-reference USING portion GIVING result text VST366.vsd Note. GETPARAMTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 46- 7 COBOLLIB, CLULIB, and ZCRESRL Routine Calls GETSTARTUPTEXT GETSTARTUPTEXT ns ENTER OF ns GETSTARTUPTEXT " " library-reference USING portion GIVING result text VST367.vsd Note. The ENTER verb must not be followed by the keyword TAL, because GETSTARTUPTEXT uses a protocol different from that of normal TAL procedures. PUTASSIGNTEXT ns ENTER OF ns PUTASSIGNTEXT " " library-reference USING portion text cplist message-number GIVING result VST368.vsd Note. PUTASSIGNTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 46- 8 COBOLLIB, CLULIB, and ZCRESRL Routine Calls PUTASSIGNVALUE PUTASSIGNVALUE ns ENTER OF ns PUTASSIGNVALUE " " library-reference USING portion val cplist message-number GIVING result VST369.vsd Note. PUTASSIGNVALUE uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. PUTPARAMTEXT ns ENTER " OF ns PUTPARAMTEXT " library-reference USING portion GIVING result text cplist VST370.vsd Note. PUTPARAMTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 46- 9 COBOLLIB, CLULIB, and ZCRESRL Routine Calls PUTSTARTUPTEXT PUTSTARTUPTEXT ns " ENTER OF ns PUTSTARTUPTEXT " library-reference USING portion GIVING result text cplist VST371.vsd Note. PUTSTARTUPTEXT uses a protocol different from that used for normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. Non-SMU Routines Programs compiled with the COBOL85 compiler can call all of the SMU routines listed in Table 46-2. Programs compiled with the NMCOBOL compiler can call only the new routines. Table 46-2. Non-SMU COBOLLIB Routines Original Routine New Routine(s) COBOLASSIGN COBOL_ASSIGN_1, 2 COBOLFILEINFO COBOLFILEINFO2 COBOL_FILE_INFO_3, 4 COBOLSPOOLOPEN COBOL_SPECIAL_OPEN_4 CREATEPROCESS CREATEPROCESS5 CLU_PROCESS_CREATE1, 6 1. In the CLULIB file for the COBOL85 compiler and the ZCOBSRL file for the NMCOBOL compiler 2. For the Guardian environment 3. For the OSS environment 4. In the CBL85UTL file for the COBOL85 compiler and the ZCOBSRL file for the NMCOBOL compiler 5. Cannot create a high-PIN process 6. Can create a high-PIN process • • • • COBOLASSIGN COBOL_ASSIGN_ COBOLFILEINFO COBOL_FILE_INFO_ HP COBOL Manual for TNS and TNS/R Programs —522555-006 46 -10 COBOLLIB, CLULIB, and ZCRESRL Routine Calls • • COBOLASSIGN COBOLSPOOLOPEN CREATEPROCESS COBOLASSIGN ns ENTER OF ns COBOLASSIGN " " library-reference USING fd-name GIVING error-number system-file-name VST354.vsd Note. COBOLASSIGN uses a protocol different from that used by normal TAL procedures. The ENTER verb must not be followed by the keyword TAL. COBOL_ASSIGN_ ns ENTER OF " ns COBOL_ASSIGN_ " library-reference USING fd-name system-file-name file-code file-type GIVING error-number VST356.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 46 -11 COBOLLIB, CLULIB, and ZCRESRL Routine Calls COBOLFILEINFO COBOLFILEINFO ns ENTER " ns COBOLFILEINFO " TAL OF library-reference USING fd-name error-code file-name file-number VST357.vsd COBOL_FILE_INFO_ ENTER " COBOL_FILE_INFO_ " TAL OF library-reference USING file-name name-buffer name-size file-number error VST636.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 46 -12 COBOLLIB, CLULIB, and ZCRESRL Routine Calls COBOLSPOOLOPEN COBOLSPOOLOPEN ENTER COBOLSPOOLOPEN " " TAL OF library-reference USING fd-name «file-status» location form-name report-name copies page-size flags exclusion sync-depth owner level-3 GIVING error-code VST358.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 46 -13 COBOLLIB, CLULIB, and ZCRESRL Routine Calls CREATEPROCESS CREATEPROCESS ns ENTER " OF CREATEPROCESS ns " library-reference USING program-file process-name option priority processor memory process-id GIVING result VST359.vsd HP COBOL Manual for TNS and TNS/R Programs —522555-006 46 -14 Part IV. Error Message Summary Title Section 47, Compiler Diagnostic Messages Section 48, Run-Time Diagnostic Messages HP COBOL Manual for TNS and TNS/R Programs —522555-006 Part IV. Error Message Summary HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 Compiler Diagnostic Messages Topics: • • • • • • Message Indicator Line Warning Message Format Error Message Format Failure Message Format Message List Other Products’ Error Messages Table 47-1. Warning, Error, and Failure Characteristics Message Type Reports Compilation Continues Code Generation is Suppressed Object File is Suppressed Warning Questionable condition Yes No No Error Serious syntactic or semantic violation Yes For current separately compiled program In some cases Failure Condition so severe that compilation cannot continue No Yes Yes HP COBOL Manual for TNS and TNS/R Programs —522555-006 47- 1 Compiler Diagnostic Messages Message Indicator Line Message Indicator Line A message indicator line precedes each compiler diagnostic message. If possible, the message indicator line specifies the location of the problem or the unacceptable object with one or more of these: • • • A caret (^) showing where in the source line the compiler recognized the problem For the COBOL85 compiler, the phrase “Problem on line nnnnn ” where nnnnn is the line number of the source line where the compiler recognized the problem The user-defined name of the object that the problem involves The message indicator line cannot always tell you exactly where the problem is because the problem might not be recognizable (and reportable) until the compiler is past the source line that contains it. Table 47-2. Problem Discovery Time, Message Indicator Line Contents, and Problem Location Problem Discovery Time Message Indicator Line Contents Problem Location During textual or syntactic analysis of a particular source file line Caret (^) (usually), “Problem on line nnnnn ” (maybe) Language element marked by caret, source file line number nnnnn During semantic analysis of an operand phrase, clause, or statement “Problem on line nnnnn ” (usually), caret (^) (maybe) In vicinity of source file line number nnnnn, language element marked by caret After analyzing many source lines, possibly an entire source program User-defined name of object, “Problem on line nnnnn ” (maybe) With the named object, in vicinity of source file line number nnnnn Example 47-1. Message Indicator Line (COBOL85 Compiler) 13 MOVE "" TO A. ^ Problem on line 13 ** Error 30 ** Null literal Example 47-2. Message Indicator Line (NMCOBOL Compiler) 13 MOVE "" TO A. *** Error: ^ --> Null literal [Error 30] HP COBOL Manual for TNS and TNS/R Programs —522555-006 47- 2 Compiler Diagnostic Messages Warning Message Format Warning Message Format For the COBOL85 compiler, a warning message has this format: ** Warning message-number ** message-text For the NMCOBOL compiler, a warning message has this format: *** Warning: --> message-text [Warning message-number] The brackets are part of the message, not indicators that the bracketed material is optional. Error Message Format For the COBOL85 compiler, an error message has this format: ** Error ** message-number ** message-text For the NMCOBOL compiler, an error message has this format: *** Error: --> message-text [Error message-number] The brackets are part of the message, not indicators that the bracketed material is optional. Failure Message Format For the COBOL85 compiler, a failure message has this format: ** Failure ** message-number ** message-text For the NMCOBOL compiler, a failure message has this format: *** Failure: --> message-text [Failure message-number] The brackets are part of the message, not indicators that the bracketed material is optional. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47- 3 Compiler Diagnostic Messages Message List Message List Messages are listed in numeric order by message number, with message type (warning, error, or failure) noted. 0 (Failure) Compiler logic error Cause. The compiler’s internal consistency checks found a logic error. Please report this failure to your service provider. 1 (Failure) CREATE failure on work file (file-name): ddd Cause. The compiler cannot create one of its work files. file-name is the external form of the file name. ddd is the file management error code returned by the operating environment. 2 (Failure) OPEN failure on xxxx file (file-name): ddd Cause. One of: • • The compiler cannot open the file named file-name. The file name parameter of the CONSULT, SEARCH, LIBRARY, or ERRORFILE directive is either absent or does not have the form of a disk file name. The xxxx parameter is the type of compiler file (source, copy, list, or work). filename is the external form of the file name. ddd is the file management error code that the operating environment returned. 3 (Failure) Unable to use xxxx file (file-name) Cause. The compiler cannot use the file named file-name. xxxx is the type of compiler file (source, SEARCH, COPY, or list). file-name is the external form of the file name. Some causes of this failure are: • • The file file-name does not exist. The file file-name is not a disk file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47- 4 Compiler Diagnostic Messages • • • • • • Message List The file file-name is specified as the source file, but its attributes are inappropriate for a source file (usually because the device type does support read operations). The file file-name is specified as a SEARCH file, but it is not a code 700 object file. The file file-name is specified as a SEARCH file, but it was not created by a compilation with symbols specified. The file file-name is specified as a COPY library, but its attributes are inappropriate for a COPY file (file-name is not an EDIT file or has been modified since the start of the current compilation). The default COPY library named file-name in the command that called the compiler has improper punctuation or its content does not have the form of a disk file name. The file file-name is specified as the compiler listing, but it’s attributes ar inappropriate for a compiler listing (the device type does support write operations, the record length is too short, the file is an EDIT file or a keyed-access disk file, and so on). 4 (Failure) OPEN edit failure on xxxx file (file-name): ddd Cause. The compiler cannot initialize the indicated EDIT file for reading. xxxx is the type of compiler file (source or copy). file-name is the external form of the file name. ddd is the error code describing the problem. A negative ddd value indicates a format error in the file. A nonnegative value indicates a Guardian file management error. 5 (Failure) READ edit failure on xxxx file (file-name): ddd Cause. The compiler cannot read a record from the EDIT file indicated. xxxx is the type of compiler file (source or copy). file-name is the external form of the file name. ddd is the Guardian file management error code describing the problem. 6 (Failure) READ failure on xxxx file (file-name): ddd Cause. The compiler cannot read a record from the file named file-name. xxxx is the type of compiler file (source or work). file-name is the external form of the file name. ddd is the file management error code that the operating environment returned. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47- 5 Compiler Diagnostic Messages Message List 7 (Failure) WRITE failure on xxxx file (file-name): ddd Cause. The compiler cannot write a record to the file named file-name. xxxx is the type of compiler file (list or work). file-name is the external form of the file name. ddd is the file management error code that the operating environment returned. 8 (Failure) I/O failure on xxxx file (file-name): ddd Cause. The compiler cannot perform a miscellaneous input-output operation on the file named file-name. xxxx is the type of compiler file (list or work). file-name is the external form of the file name. ddd is the file management error code that the operating environment returned. 9 (Failure) Spooler failure on list file (file-name): ddd Cause. The compiler either cannot initiate or cannot terminate spooler processing for its list file. file-name is the external form of the file name. ddd is the error code describing the problem (explained in documentation of the SPOOLSTART and SPOOLEND procedures). 10 (Failure) Unable to allocate compiler data space: ddd Cause. The compiler cannot allocate its extended data segment. ddd is the error code describing the problem (explained in the documentation of the ALLOCATESEGMENT procedure). 11 (Failure) Source line exceeds 132 characters Cause. A source file or COPY library file contains more than 132 characters. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47- 6 Compiler Diagnostic Messages Message List 12 (Failure) Improper context for source text directive Cause. One of: • • The reserved word COPY appears where it is not expected (for example, within COPY library text). The reserved word REPLACE appears where it is not expected (for example, within source text produced by the editing activities of a REPLACE statement). 13 (Failure) Expected IDENTIFICATION Cause. The source program does not begin with an Identification Division header. 14 (Failure) End of file reached during error recovery Cause. The compiler reached the end of the source file during an attempt to recover from a syntax error. This usually occurs in one of these situations: • • A syntax error is near the end of the source file, so the remaining text does not provide enough context for the compiler to decide how to recover. A syntax error is such that the compiler fails to discover an acceptable method of recovery and flushes the remaining source text. 15 (Failure) Compiler internal resource failure Cause. The compiler cannot continue execution because it has exhausted some internal resource. The message can have one of these suffixes: - statement nesting too deep editing space overflow too much pseudo text too many editable lines too many edited lines If the message has the suffix - statement nesting too deep rewrite the statement, reducing the number of nested scopes. Use PARAM SYMBOL-BLOCKS to allocate more space. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47- 7 Compiler Diagnostic Messages Message List If PARAM SYMBOL-BLOCKS does not solve the problem, and the program uses COPY, REPLACE, or both COPY and REPLACE: • • • • Reduce the size of the pseudotext or literal in the REPLACE statement or REPLACING phrase. Use REPLACE OFF when replacement is no longer needed. Reduce the number of contiguous comment lines that can be read while COPY LIBRARY or REPLACE is active. Avoid having COPY and REPLACE active at the same time. 16 (Failure) Too many errors Cause. The number of error messages exceeds the specified limit (100 unless specified otherwise in an ERRORS directive). 17 (Failure) Dictionary overflow Cause. The compiler’s symbol dictionary has insufficient space to describe all entities defined in the current separately compiled program. Divide the program into two or more separately compiled programs. Use PARAM SYMBOL-BLOCKS to allocate more space. The NMCOBOL compiler needs more symbol table space than the COBOL85 compiler does, so you might need to allocate more while migrating to TNS/R native mode. See Step 6 of Migrating HP COBOL Programs. 18 (Failure) Format switch during editing Cause. A format switch directive (ANSI or TANDEM) appears in text edited under the control of a COPY or REPLACE statement. The compiler cannot process the source text correctly. 19 (Failure) Server failure Cause. The compiler cannot continue execution because one of its server processes reported a failure or terminated abnormally. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47- 8 Compiler Diagnostic Messages Message List 20 (Failure) Assigned CPU is not licensed for this compiler Cause. The processor in which the compiler is to run is not licensed for this compiler’s execution. 21 (Failure) SOURCE nesting too deep Cause. The compiler ran out of storage space because the nesting of SOURCE directives summoning text that includes other SOURCE directives is too deep. 25 (Warning) Blank continuation line Cause. A source line marked as a continuation line (having a hyphen in the indicator area) contains only spaces as its text. 26 (Warning) Improper indicator character Cause. One of: • • The character in the indicator area of a source line is not minus (-), asterisk (*), slash (/), question mark (?), d, D, or space. A continuation line is part of a comment-entry in a paragraph of the Identification Division. 27 (Error) Improper character Cause. The character indicated is not permitted in this context. Because the character might not be printable, its internal (octal) value is appended to the message. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47- 9 Compiler Diagnostic Messages Message List 28 (Error) Text not permitted here Cause. One of: • • • • A division header is followed by other text on the same source line. A section header is followed by other text on the same source line (other than a USE statement). The DECLARATIVES or END DECLARATIVES header is followed by other text on the same source line. A compiler directive that must be the last one on its line is followed by other text on the same directive line. 29 (Error) Missing quote character Cause. The terminating quotation-mark character (") is missing from a nonnumeric literal. 30 (Error) Null literal Cause. A nonnumeric literal contains no characters (has no textual value). 31 (Error) Literal exceeds 160 characters A nonnumeric literal contains more than 160 characters. 32 (Error) Token exceeds 160 characters Cause. A character-string appears (to the compiler) to contain more than 160 characters. If the indicated text is intended to represent several consecutive language elements, correct the problem by inserting space separators between them. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -10 Compiler Diagnostic Messages Message List 33 (Error) Numeric literal exceeds 18 digits Cause. A numeric literal contains more than 18 digits. 34 (Error) Word exceeds 30 characters Cause. A COBOL word contains more than 30 characters. 35 (Error) Word ends with '-' Cause. The last character of the indicated COBOL word is a hyphen. 36 (Warning or Error) Improper use of reserved word Cause. Warning: A COBOL reserved word is the text-name or library-name in a COPY statement. Error: A COBOL reserved word is in an improper context. Usually this message reports the use of a noncritical reserved word (one defined in an unsupported language module) as a user-defined word. 37 (Error) Do not quote PICTURE string Cause. A PICTURE character-string is specified as a nonnumeric literal. 38 (Warning) Missing separator Cause. One of: • • A comma, semicolon, or period character is not followed by the space needed to make it a separator. A character-string is not followed by an appropriate separator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -11 Compiler Diagnostic Messages Message List 39 (Warning, Error or Failure) Improper actual file name Cause. Warning: The run unit file name (object file name) field in the command that called the compiler has improper punctuation or its content does not have the form of a disk file name. The compiler supplies RUNUNIT (with appropriate default volume and subvolume components) as the run unit file name. Error: A system-name is in a context where it must identify an actual file (for example, in a File-Mnemonic clause), but it does not have the form of an actual file name. Failure: A COPY or SOURCE file does not have the form of a disk file name. 40 (Error) Improper syntax Cause. One of: • • The analysis of a COPY or REPLACE statement failed when it reached the indicated element because of a syntactic problem (for example, a required component is missing). The compiler found a syntactic problem in a Procedure Division statement after the general syntax analysis completed with apparent success. 41 (Error) Syntax error - replacing unexpected token with xxxx Cause. The compiler found a syntax error at the indicated point and recovered by replacing that token (a character-string or a separator) with the token xxxx (a different character-string or separator). This replacement is probably just one of several possible corrections. You must determine the proper correction through careful examination of the text. 42 (Error) Syntax error - inserting missing token xxxx Cause. The compiler found a syntax error at the indicated point and recovered by inserting the token xxxx (a character-string or a separator) just prior to that point. Inserting that token is probably just one of several possible corrections. You must determine the proper correction through careful examination of the text. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -12 Compiler Diagnostic Messages Message List 43 (Error) Syntax error - deleting unexpected token xxxx Cause. The compiler found a syntax error at the token xxxx (a character-string or a separator) and recovered by deleting that token. The problem could have been a misspelled optional reserved word or an extraneous separator. Deleting the token is probably just one of several possible corrections. You must determine the proper correction through careful examination of the text. 44 (Error) Syntax error detected at token xxxx Cause. The compiler’s syntax analyzer cannot accept the token xxxx (a characterstring or a separator) and the recovery mechanism cannot find a simple correction. The compiler tried to recover by discarding text following the token, along with as little text preceding the token as is necessary, until the remaining text was syntactically acceptable. 45 (Warning) Parsing resumed at token xxxx Cause. The compiler discarded all tokens from the one indicated in the message for error 44 up to, but not including, the token xxxx. Also, the compiler might have discarded some text prior to the point indicated in the preceding message. This error correction usually is not the preferred one. You must determine the proper correction through careful examination of the text at the point indicated by the preceding syntax error message. 46 (Error) Expected directive Cause. The compiler expected to find a directive and did not. Directives are expected in these places: • • At the beginning of a directive line After the punctuation following a completed directive 47 (Error) Unknown directive Cause. The indicated word must be a directive keyword, but it is not. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -13 Compiler Diagnostic Messages Message List 48 (Warning or Error) Improper context for this directive Cause. Warning: The SYMBOLS or NOSYMBOLS directive is within a separately compiled program. It is ignored in this context. Error: One of: • • • • The indicated directive (MAIN or NONSTOP) cannot appear at this point in the source text. It must precede the first source program’s Identification Division header. The indicated directive (SYNTAX or COMPILE) cannot appear at this point in the source text. It must appear before the first separately compiled program or between separately compiled programs. The SECTION directive cannot appear at this point in the directive line. It must be the first one on its directive line. The program contains the SQLMEM directive but not the SQL directive. 49 (Error) Expected directive parameter Cause. The compiler did not find the directive parameter keyword that it expected in one of these places: • • Following a directive keyword After the punctuation following a completed directive parameter 50 (Error) Unknown directive parameter Cause. The indicated word must be a parameter keyword of the current directive, but is not. 51 (Error) Expected quoted string Cause. The HEADING directive has a parameter that is not a string surrounded by quotation marks. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -14 Compiler Diagnostic Messages Message List 52 (Error) Expected program-name Cause. The MAIN directive has either no parameter or a parameter that is not a COBOL word. 53 (Error) Expected comma or other delimiter valid for context Cause. One of: • • • Multiple compiler directives appear on the same line but are not separated by semicolons. Multiple parameters of a compiler directive are not separated by commas. A compiler directive parameter list begun with a left parenthesis is not terminated by a right parenthesis. 54 (Warning) No symbol table generated Cause. One of: • • The compiler finds a SYMBOLS directive when a SYNTAX directive is active. The compiler ignores the SYMBOLS directive. The compiler finds a SYNTAX directive when the SYMBOLS directive is active. The compiler proceeds as if a NOSYMBOLS directive preceded the SYNTAX directive. 55 (Error) Parameters ignored Cause. A NOCROSSREF directive is followed by directive parameters, which it cannot have. 55 (Error) Parameters ignored Cause. A NOCROSSREF directive is followed by directive parameters, which it cannot have. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -15 Compiler Diagnostic Messages Message List 56 (Warning) This directive permitted only on the command line Cause. The SQL directive must be specified on the command line. An SQL directive in the source program will be ignored. 58 (Error) Unable to convert continuation to debugging line Cause. The compiler could not convert a source line processed under the control of a COPY or REPLACE statement to a debugging line (by putting D or d in the indicator area) because the line is also a continuation line. 59 (Warning) Logic may differ from COBOL 74 - tttt Cause. The compiler’s interpretation of the source program might differ from the HP COBOL 74 compiler’s interpretation. tttt indicates which aspect of the program is being reported. See DIAGNOSE-74 and NODIAGNOSE-74. You must determine what effects the compiler’s interpretation has on the program’s execution logic, decide if those effects are desired or not, and then revise the source program as needed. The compiler reports potential logic differences only when the DIAGNOSE-74 directive is specified. 60 (Warning or Error) Not supported Cause. The compiler found an optional element of the COBOL language that HP COBOL does not support. Warning: Examples of language elements that cause this warning are: • • More than one system-name in an ASSIGN clause (the compiler ignores all system-names after the first one) The VALUE clause of a file description entry (the compiler ignores the VALUE clause) Error: Use of an unsupported language element, for example: • • • The OPEN … REVERSED option Elements defined in the Communications module Elements defined in the Report Writer module HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -16 Compiler Diagnostic Messages Message List 61 (Warning) Logic may differ from COBOL85 - move alphanumeric to numeric with invalid data Cause. The NMCOBOL compiler’s interpretation of the source program might differ from the COBOL85 compiler’s interpretation. See DIAGNOSE-85 and NODIAGNOSE85. You must determine what effects the NMCOBOL interpretation has on the program’s execution logic, decide if those effects are desired, and then revise the source program if needed. The NMCOBOL compiler reports potential logic differences only when the DIAGNOSE-85 directive is specified. If you suspect that the data item that caused this warning contains trailing spaces, use the NUMVAL function; for example, change: MOVE a TO b To: MOVE FUNCTION NUMVAL (a) TO b 62 (Error) Name conflict Cause. One of: • • • The definition of a user-defined word conflicts with its prior definition as the name of an object in another class. The definition of a user-defined word conflicts with its prior definition as the name of an object in the same class, because all objects in that class must have unique names. The name of a special register is specified as the name of a user-defined object. 63 (Error) Ambiguous reference Cause. A reference has insufficient qualification to identify a unique entity. 64 (Error) Zero not permitted in this context Cause. The indicated integer numeric literal has the value 0, which is not permitted in this context. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -17 Compiler Diagnostic Messages Message List 65 (Error) Integer not within expected range Cause. One of: • • The value of an integer numeric literal is either too small or too large for its context. The expected range can be absolute (for example, many literals cannot exceed 32,767) or relative (for example, the FOOTING value in a LINAGE clause cannot exceed the number of lines in the page body). The value of an integer numeric literal used as a subscript is less than 1 or greater than the maximum occurrence number defined by the appropriate OCCURS clause. 66 (Error) Expected unsigned integer Cause. Only an unsigned integer numeric literal is permitted in this context, and the compiler found something else. 67 (Error) Expected single character Cause. The indicated nonnumeric literal contains more than one character, which is not allowed in this context. 69 (Error) Expected alphabet-name Cause. One of: • • The alphabet-name specified in the PROGRAM COLLATING SEQUENCE clause is not defined. A reference that must identify an alphabet-name does not. 70 (Error) Expected file name Cause. A reference that must identify a file name does not. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -18 Compiler Diagnostic Messages Message List 71 (Error) Expected symbolic character Cause. The indicated COBOL word appears in a context where a symbolic-character is expected, but it does not identify one. 72 (Error) Expected section-name Cause. One of: • • • The section-name parameter is missing from a SECTION directive. The text-name specified in a COPY statement is not a section-name in the COPY library. A section-name specified in a SOURCE directive is not in the source library. 73 (Error) Improper range Cause. One of: • • The first value in a numeric range exceeds the last value (or is equal to the last value in a context in which it must be less). The first value in a nonnumeric range is greater than the last value. 74 (Error) COBOL85 Compiler: Too many or too few parameters NMCOBOL Compiler: Too many actual parameters Cause. One of: • • A CALL statement specifies more parameters in its USING phrase than HP COBOL supports. An ENTER statement specifies more parameters in its USING phrase than the routine expects. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -19 Compiler Diagnostic Messages • Message List An ENTER statement specifies fewer parameters in its USING phrase than the routine expects, and the routine is not defined as EXTENSIBLE or VARIABLE (COBOL85 compiler only). 75 (Error) Out of order Cause. The indicated language element does not appear in the proper position within the source program. 76 (Error) Duplicate phrase Cause. The indicated phrase duplicates the function of a preceding one. 77 (Error) Duplicate clause Cause. The indicated clause duplicates the function of a preceding one. 78 (Error) Duplicate paragraph Cause. The indicated paragraph header duplicates a preceding one. 79 (Error) Duplicate section Cause. The indicated section header duplicates a preceding one. 80 (Error) Clause not permitted in this context Cause. The indicated clause cannot appear in the current entry. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -20 Compiler Diagnostic Messages Message List 81 (Error) Not permitted within contained program Cause. One of: • • • The Configuration Section is within a contained program. The RECEIVE-CONTROL paragraph is within a contained program. A program is not terminated by an END PROGRAM statement or an ENDUNIT directive. 82 (Error) Too many keys Cause. One of: • • • A file has more than 31 alternate record keys. An OCCURS clause has more than 31 key references. A SORT or MERGE statement has more than 31 keys. 83 (Error) Too many receiver items Cause. The number of receiver items in the statement exceeds the maximum number allowed. For the maximum number allowed, see Section 19, Using HP COBOL in the OSS Environment. 84 (Error) NMCOBOL Compiler: Too few actual parameters Cause. An ENTER statement specifies fewer parameters in its USING phrase than the routine expects. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -21 Compiler Diagnostic Messages Message List 85 (Warning) Arithmetic expression too complex - floating-point used Cause. An arithmetic expression was too complex to produce a correct answer, probably because the intermediate result exceeded the capacity of the intermediate data item (36 digits) or because there was more than one division operation. The expression uses a floating-point, intermediate, data item, which might cause the result to be slightly off in the rightmost positions. If you want exact results, break the expression into more than one statement, using temporary data items that have the precision you need. 86 (Error or Failure) Program nesting too deep Cause. Error: Programs are nested deeper than the limit of 7. Failure: Program nesting depth is too great. 87 (Error) Missing PROGRAM-ID paragraph Cause. The Identification Division has no PROGRAM-ID paragraph (the compiler generates a name for the source program). 88 (Error or Failure) Duplicate program-name Cause. Within a separately compiled program, the same name identifies more than one source program. 89 (Error) Program-name conflicts with routine-name Cause. The same name identifies both a separately compiled COBOL program and a routine in the same run unit. The conflict arises because the name is the subject of CALL or CANCEL statements in the current separately compiled program, and these references must be resolved to another separately compiled COBOL program not yet defined in the source text; however, the compiler has already found references to this name as the identifier of a routine. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -22 Compiler Diagnostic Messages Message List 90 (Error) Permitted only within contained program Cause. The COMMON phrase appears somewhere other than within a contained program. 91 (Error) System-name not defined in this context Cause. One of: • • • • The reference in the CHARACTER-SET clause is not one of the system-names defined for that clause. The system-name in the ALPHABET clause is not EBCDIC, the only value that HP COBOL supports. The standard system-name in the RECORD DELIMITER clause is not STANDARD-1, the only value that HP COBOL supports. A reference in the REPORT clause of the RECEIVE-CONTROL paragraph is not one of the system-names defined for that clause. 92 (Error) STATUS phrase permitted only for switch Cause. A STATUS phrase appears somewhere other than in a system-name clause whose subject is one of the supported external switch names. 93 (Warning) Missing ALPHABET keyword Cause. A clause defining an alphabet-name does not begin with the keyword ALPHABET. 94 (Error) Symbolic character not permitted Cause. A symbolic-character appears within the definition of an alphabet-name or class-name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -23 Compiler Diagnostic Messages Message List 95 (Error) Duplicates not permitted Cause. One of: • • • A character has more than one collating position in a character set. A character appears more than once in the first operand of the CONVERTING phrase in an INSPECT statement. A section-name appears more than once in a SOURCE directive. 96 (Error) Too many or too few values Cause. The number of values in the SYMBOLIC CHARACTER clause differs from the number of symbolic-characters being defined. 97 (Error) Improper currency symbol Cause. Either the alternative currency symbol specified is not a single character or the given character is not permitted in this context. 98 (Error) Missing ASSIGN clause Cause. A file-control entry does not have an ASSIGN clause. 99 (Error) Missing relative key Cause. The description of a file with relative organization and either random or dynamic access does not have a RELATIVE KEY clause. 100 (Error) Missing record key Cause. The description of a file with indexed organization does not have a RECORD KEY clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -24 Compiler Diagnostic Messages Message List 101 (Error) Relative key permitted only for relative organization Cause. A file that does not have relative organization has a RELATIVE KEY clause in its file-control entry. 102 (Error) Record key permitted only for indexed organization Cause. A file that does not have indexed organization has a RECORD KEY clause in its file-control entry. 103 (Error) Sequential organization requires sequential access Cause. The program tried to access a file that was described with sequential organization randomly or dynamically. 104 (Error) PADDING clause permitted only for sequential organization Cause. A file that does not have sequential organization has a PADDING clause in its file-control entry. 105 (Error) RECORD DELIMITER clause permitted only for sequential organization Cause. A file that does not have sequential organization has a RECORD DELIMITER clause in its file-control entry. 106 (Error) Expected local file name Cause. The indicated name is not defined in a file-control entry of the current source program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -25 Compiler Diagnostic Messages Message List 107 (Warning) Duplicate file-name in SAME clause Cause. A file name appears more than once in a single SAME AREA, SAME RECORD AREA, or SAME SORT AREA clause. 108 (Error) File name permitted in only one SAME clause Cause. One of: • • • A particular file name appears in more than one SAME AREA clause. A particular file name appears in more than one SAME RECORD AREA clause. A particular sort-merge file name appears in more than one SAME SORT AREA clause. 109 (Warning or Error) Expected two or more file names Cause. Warning: The SAME AREA, SAME RECORD AREA, or SAME SORT AREA clause contains fewer than two file names. Error: The USING phrase in a MERGE statement contains fewer than two file names. 110 (Error) Inconsistent with other SAME clause Cause. One of these rules was violated: • • When a file name that appears in a SAME AREA clause also appears in a SAME RECORD AREA clause, every other file name in that SAME AREA clause must also appear in the SAME RECORD AREA clause. When a file name that appears in a SAME AREA clause also appears in a SAME SORT AREA clause, every other file name in that SAME AREA clause must also appear in the SAME SORT AREA clause. 111 (Error) Too many MULTIPLE FILE TAPE clauses Cause. A source program has more than 8 MULTIPLE FILE TAPE clauses. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -26 Compiler Diagnostic Messages Message List 112 (Error) Too many file names Cause. A source program has too many CONSULT, LIBRARY, and SEARCH files for the available memory. 113 (Error) file name permitted only once in MULTIPLE FILE TAPE clauses Cause. The same file name appears more than once in a MULTIPLE FILE TAPE clause or in more than one MULTIPLE FILE TAPE clause. 114 (Error) File position required Cause. A file name in a MULTIPLE FILE TAPE clause follows one or more other file names that have explicit position numbers, but it does not have an explicit position number. 115 (Error) Duplicate file position Cause. Two or more file names in a MULTIPLE FILE TAPE clause have the same position number. 116 (Error) MULTIPLE FILE TAPE clause requires sequential organization Cause. A MULTIPLE FILE TAPE clause has a file name that is not described with sequential organization. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -27 Compiler Diagnostic Messages Message List 117 (Error) Receive control table too large Cause. The size of the receive control table as specified in the RECEIVE-CONTROL paragraph exceeds 62 KB (65,400 characters). Reduce table-length in the TABLE OCCURS phrase or reduce another factor in these formulas, which determine the size of the receive control table: • In the CRE: ((max_requesters + 1) * 26) + ((((max_reply + 1) / 2) + 4) * (max_requesters * sync)) +4 • In the non-CRE environment, when the receive control table is not in the ExtendedStorage Section: ((max_requesters + 1) * 11) + ((((max_reply + 1) / 2) + 4) * (max_requesters * sync)) +4 • In the non-CRE environment, when the receive control table is in the ExtendedStorage Section: ((max_requesters + 1) * 11) + (4 * (max_requesters * sync)) + 4 121 (Error) Improper level-number Cause. A level-number is not 66, 77, 88, or in the range 01 through 49. The compiler converts the improper level-number to 50. 122 (Error) Missing 01 level entry Cause. A data description entry with a level-number from 02 through 49 inclusive is not subordinate to a data description entry with level-number 01. 123 (Error) Not preceded by record Cause. A data description entry with level-number 66 is not preceded by a record description. (Any intervening data description entries must also have level-number 66.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -28 Compiler Diagnostic Messages Message List 124 (Error) Not permitted within this section Cause. One of: • • • • • A level-77 data item is defined in the File Section. A level-01 data item defined in the File Section is described with the REDEFINES clause. The EXTERNAL clause for a data description entry is not within the WorkingStorage Section or Extended-Storage Section. The GLOBAL clause appears in descriptions that are not within the File Section, Working-Storage Section, or Extended-Storage Section. The description of a data item defined within the File Section or Linkage Section includes a VALUE clause. 125 (Error) Not preceded by conditional variable Cause. The definition of a condition-name (a name whose data description entry has level-number 88) is not preceded by the entry for the data item whose value it tests. (Any intervening data description entries must also have level-number 88.) 126 (Error) Inconsistent level-number Cause. A level-number is neither greater than the level-number of the preceding data description entry nor equal to that of some preceding data description entry in the same record description. 127 (Error) Not permitted after variable occurrence table Cause. Within a record description, a data description entry that includes an OCCURS clause with the DEPENDING phrase is followed by a data description entry with a lesser level-number. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -29 Compiler Diagnostic Messages Message List 128 (Error) FILLER not permitted for 01 level external data item Cause. A record data item that has no name, or is a FILLER data name, is either described with the EXTERNAL clause or is subordinate to a file description entry that includes the EXTERNAL clause. 129 (Error) FILLER not permitted for 01 level global data-name Cause. A record data item that has no name, or is a FILLER data name, is either described with the GLOBAL clause or is subordinate to a file description entry that includes the GLOBAL clause. 130 (Error) FILLER not permitted for this level-number Cause. One of: • • A data description entry with level-number 66 or 77 does not include the dataname. A data description entry with level-number 88 does not include the condition-name. 131 (Error) Redefined data item not found Cause. The reference in a REDEFINES clause does not identify a data item. (When a REDEFINES clause appears in a record description, only that record is searched for the redefined item.) 132 (Error) Redefined data item has conflicting level-number Cause. The data item to be redefined does not have the same level-number as the redefinition data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -30 Compiler Diagnostic Messages Message List 133 (Error) Redefined and redefinition data items not subordinate to same levels Cause. A redefined data item is a subordinate of a file description entry and/or one or more data structure description entries, but the redefinition item is not a subordinate of these entries. 134 (Error) Redefined data item is a redefinition Cause. The program tried to redefine a data item that was described with a REDEFINES clause. (A subordinate of a redefinition can be redefined unless it is also described with a REDEFINES clause.) 135 (Error) Redefined data item not preceding item at this level Cause. The data description entry of a redefinition was separated from the data description entry of the redefined item by another data description entry with the same level-number, and the intervening entry did not redefine the same data item. 136 (Error) Redefined data item is table or has variable size Cause. The program tried to redefine a table or a data structure with a variable size. 137 (Error) Name conflict with other 01 level external data item Cause. Two different records in the same source program have the same recordname and both have the EXTERNAL attribute. Only one can have the EXTERNAL attribute. 138 (Error) Redefinition not permitted for 01 level external data item Cause. A record item described with a REDEFINES clause has the EXTERNAL clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -31 Compiler Diagnostic Messages Message List 139 (Error) Picture string exceeds 30 characters Cause. A PICTURE character-string has more than 30 characters. 140 (Error) Improper picture string Cause. The PICTURE character-string does not conform to the rules of the COBOL language, possibly for one of these reasons: • • • • The characters are undefined in this context. The characters are combined improperly. The character-string has unmatched parentheses. The character-string has no positions for data characters. 141 (Error) Too many digit positions Cause. The PICTURE character-string for a numeric or numeric-edited data item has more than 18 digit positions. 142 (Error) Too many character positions Cause. The PICTURE character-string has more than 134,217,726 character positions. 143 (Error) PICTURE clause not permitted for specified usage Cause. The PICTURE clause describes a data item with USAGE INDEX, NATIVE-2, NATIVE-4, or NATIVE-8. 144 (Error) Subordinate usage conflicts with group usage Cause. A data item that is subordinate to a data structure described with a USAGE clause is described with a USAGE clause specifying a different usage. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -32 Compiler Diagnostic Messages Message List 145 (Error) Specified usage permitted only for numeric data item Cause. Only a numeric data item can be described with the specified usage. 146 (Error) Display usage required in group with value or condition-names Cause. A data item that is either subordinate to a data structure described with a VALUE clause or associated with condition-names does not have USAGE DISPLAY, as it must. 147 (Error) Display usage required when SIGN clause applies Cause. One of these items does not have USAGE DISPLAY, as it must: • • A data item described with a SIGN clause A signed numeric data item that is subordinate to a data structure described with a SIGN clause 148 (Error) Only signed numeric picture permitted when SIGN clause specified Cause. A data item is described with a SIGN clause, but either its category is not numeric or its PICTURE character-string does not contain S. 149 (Error) SYNCHRONIZED clause not permitted in group with value or condition-names Cause. A data item is described with a SYNCHRONIZED clause, but either the data item is subordinate to a data structure described with a VALUE clause or the data item is associated with condition-names. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -33 Compiler Diagnostic Messages Message List 150 (Error) JUSTIFIED clause requires display usage Cause. A data item is described with a JUSTIFIED clause, but the data item does not have USAGE DISPLAY, as it must. 151 (Error) JUSTIFIED clause not permitted for numeric or edited data item Cause. A numeric, numeric-edited, or alphanumeric-edited data item is described with a JUSTIFIED clause. 152 (Error) JUSTIFIED clause not permitted in group with value or condition-names Cause. A data item is described with a JUSTIFIED clause, but either the data item is subordinate to a data structure described with a VALUE clause or the data item is associated with condition-names. 153 (Error) BLANK WHEN ZERO clause requires display usage Cause. A data item is described with a BLANK WHEN ZERO clause, but the data item does not have USAGE DISPLAY, as it must. 154 (Error) BLANK WHEN ZERO clause requires numeric or numeric-edited picture Cause. A data item is described with a BLANK WHEN ZERO clause, but the data item is not numeric or numeric-edited, as it must be. 155 (Error) BLANK WHEN ZERO clause not permitted for picture with '*' Cause. A data item is described with both the BLANK WHEN ZERO clause and a PICTURE character-string containing the asterisk symbol (*). HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -34 Compiler Diagnostic Messages Message List 156 (Error) Access mode conflict for redefinition or subordinate Cause. One of: • • A data item that is part or all of a redefinition is described with an ACCESS MODE clause specifying a different mode than the data item it redefines. A data item that is subordinate to a data structure described with an ACCESS MODE clause is described with an ACCESS MODE clause specifying a different mode. 157 (Error) VALUE clause not permitted for index data item Cause. A data item with USAGE INDEX is described with a VALUE clause. 158 (Error) VALUE clause not permitted for redefinition Cause. A data item that is part or all of a redefinition is described with a VALUE clause. 159 (Error) VALUE clause not permitted for external data item Cause. An external data item is described with a VALUE clause. 160 (Error) VALUE clause not permitted in group with initial value Cause. A data item that is subordinate to a data structure described with a VALUE clause is described with its own VALUE clause. 161 (Error) Numeric literal not compatible with nonnumeric literal Cause. The literals of a range in a VALUE clause are not both numeric or both nonnumeric, as they must be. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -35 Compiler Diagnostic Messages Message List 162 (Error) Value range not permitted for initial value Cause. The VALUE clause describing a data item contains a range of literals. 163 (Error) Only one initial value permitted Cause. The VALUE clause describing a data item contains more than one value. 164 (Error) Table nesting too deep Cause. A table has more than 7 OCCURS clauses. 165 (Error) Variable occurrences not permitted for subordinate table Cause. A data item subordinate to a table item is described with an OCCURS clause that includes the DEPENDING phrase. 166 (Error) Variable occurrences not permitted in redefinition Cause. A data item that is part or all of a redefinition is described with an OCCURS clause that includes the DEPENDING phrase. 167 (Error) Renamed object not data item Cause. The RENAMES clause does not refer to a data item. 168 (Error) Renamed data item not subordinate of preceding record Cause. The RENAMES clause references a data item that was not defined within the preceding record description. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -36 Compiler Diagnostic Messages Message List 169 (Error) Renaming not permitted for 66 level data item Cause. The RENAMES clause references a 66-level item. 170 (Error) Renamed data item in table or has variable size Cause. The RENAMES clause references a table item, a subordinate of a table item, or a data structure that has a variable size. 171 (Error) Improper range for renamed data items Cause. One of: • • The second data item in a RENAMES clause contains no character positions that are not contained in the first data item. The initial character position of the second data item in a RENAMES clause precedes the initial character position of the first data item within their record item. 172 (Error) Missing PICTURE clause Cause. An elementary data item that is described with neither USAGE INDEX nor a PICTURE clause. It must be described with at least one of these. 173 (Error) Missing RENAMES clause Cause. A data description entry with level-number 66 does not have a RENAMES clause, as it must. 174 (Error) Missing VALUE clause Cause. A data description entry with level-number 88 does not have a VALUE clause, as it must. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -37 Compiler Diagnostic Messages Message List 175 (Error) Elementary data item clause specified for group data item Cause. The description of a data structure includes a BLANK WHEN ZERO, JUSTIFIED, SYNCHRONIZED, or PICTURE clause. 176 (Warning) Group with SIGN clause has no signed numeric subordinate item Cause. A data structure described with a SIGN clause has no signed numeric subordinate data items. 177 (Error) Data item attributes not compatible with CODE-SET clause Cause. A file description that includes the CODE-SET clause violates one of these rules: • • All data items defined in the record descriptions must have USAGE DISPLAY. All signed numeric data items must be described as having the sign in a separate character position. 178 (Error) Redefinition not properly aligned Cause. The redefinition is aligned to the first character position of the area it redefines. HP COBOL does not permit a redefinition that requires allocation of an implicit FILLER item to properly align the first elementary item. 179 (Error) Redefinition too large Cause. The number of character positions occupied by a redefinition exceeds the number of character positions occupied by the redefined item, and the redefined item is not an internal record item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -38 Compiler Diagnostic Messages Message List 181 (Error) Key object not data item subordinate to its table Cause. A reference in the KEY phrase of an OCCURS clause identifies neither the table item nor a data item defined in the table item that the clause describes. 182 (Error) Key data item within subordinate table Cause. A table key data item is defined in, or as, a subordinate table item. 183 (Error) Table item permitted only as first key data item Cause. A reference in the KEY phrase of an OCCURS clause identifies the table item itself, and that reference is not the first reference in the KEY phrase. 184 (Error) Nonnumeric literal not permitted for numeric data item Cause. A literal in the VALUE clause describing a numeric data item or a conditionname associated with a numeric data item is neither ZERO (or one of its equivalents) nor a numeric literal, as it must be. 185 (Error) Nonnumeric literal exceeds item size Cause. A literal in the VALUE clause describing a nonnumeric data item or data structure, or a condition-name associated with either type of item, is larger than the data item itself. 186 (Error) Numeric literal not permitted for nonnumeric or group data item Cause. The VALUE clause describing a nonnumeric data item or data structure, or a condition-name associated with either type of item, contains a numeric literal. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -39 Compiler Diagnostic Messages Message List 187 (Error) Signed literal not permitted for unsigned numeric data item Cause. The VALUE clause describing an unsigned numeric data item or a conditionname associated with an unsigned numeric data item contains a signed numeric literal. 188 (Error) Numeric literal value inconsistent with numeric data item Cause. The VALUE clause describing a numeric data item, or a condition-name associated with a numeric data item, contains a literal that cannot be assigned to the data item without truncating nonzero digits. 189 (Error) 01 or 77 level data item too large for section Cause. The size of a data item exceeds the maximum size permitted for the Data Division section in which it is defined. 190 (Error) Described with clauses not permitted for sort-merge file Cause. The file-control entry for a sort-merge file includes clauses other than the SELECT and ASSIGN clauses. 191 (Error) EXTERNAL clause not compatible with SAME clause Cause. The file description entry of a file name that appears in a SAME AREA, SAME RECORD AREA, or SAME SORT clause includes the EXTERNAL clause. 192 (Error) GLOBAL clause not compatible with SAME RECORD AREA clause Cause. The file description entry or a subordinate record description entry of a file name that appears in a SAME RECORD AREA clause includes the GLOBAL clause. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -40 Compiler Diagnostic Messages Message List 193 (Error) LINAGE permitted only for sequential organization with no record keys Cause. One of: • • A file description entry includes the LINAGE clause, but the file organization is not sequential. A file description entry includes both the LINAGE clause and ALTERNATE RECORD KEY clauses. 194 (Error) Logical page too large Cause. The sum of the top margin, page body, and bottom margin of a logical page exceeds 9999 lines. 195 (Error) CODE-SET permitted only for sequential organization Cause. A file is described with the CODE-SET clause, but it does not have sequential organization, as it must. 196 (Error) Referenced alphabet-name not permitted in this context Cause. One of: • • The alphabet-name specified in the CODE-SET clause is defined by a sequence of literal phrases. The alphabet-name specified in the CODE-SET clause is defined by NATIVE, STANDARD-1, or STANDARD-2 when the file’s description includes ALTERNATE RECORD KEY clauses. 197 (Error) File description has no record descriptions Cause. A file description entry is not followed by any record description entries. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -41 Compiler Diagnostic Messages Message List 198 (Warning) Record-names inconsistent with file description entry Cause. At least one reference in the DATA RECORDS clause does not identify any record-name defined by the record description entries. 199 (Error) Record sizes inconsistent with file description entry Cause. A record description entry describes a record longer or shorter than the maximum or minimum specified in the RECORD clause. 200 (Error) Record size exceeds block size Cause. The maximum record size for the file exceeds the block size specified by the BLOCK CONTAINS clause. 201 (Error) Fixed-size records incompatible with RECORD DELIMITER clause Cause. A file described with the RECORD DELIMITER clause does not have variablesize records, as it must. 202 (Error) Block size too large Cause. A block exceeds 32,767 characters. 203 (Error) Record key not found within file record Cause. The reference in a RECORD KEY or ALTERNATE RECORD KEY clause does not identify a data item defined in the file’s record description entries. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -42 Compiler Diagnostic Messages Message List 204 (Error) Record key not simple fixed-size alphanumeric item Cause. The object referenced in a FILE STATUS clause either is not a fixed-size alphanumeric data item or is a table. 205 (Error) Record key aligned with another record key Cause. The first character position of one record key coincides with the first character position of another record key. 206 (Error) Missing file description entry for file name Cause. A file name introduced in a file-control entry is not defined in a file description entry. 207 (Error) Padding item not found Cause. The PADDING clause references an undefined name. 208 (Error) Padding item not simple one character alphanumeric Cause. The PADDING clause references either an object that is not a fixed-size onecharacter alphanumeric data item or an object that is a table or special register. 209 (Error) Padding item not external Cause. The PADDING clause for an external file references a data item that is not external. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -43 Compiler Diagnostic Messages Message List 210 (Error) Padding item in improper section Cause. The padding data item for a file is not defined in the Working-Storage, Extended-Storage, or Linkage Section. 211 (Error) Relative key item not found Cause. The RELATIVE KEY clause references an undefined name. 212 (Error) Relative key item not simple unscaled integer Cause. The RELATIVE KEY clause references an object about which one of these is true: • • • It is not an unsigned integer data item. It is described with P s in its PICTURE clause. It is a table or special register. 213 (Error) Relative key item not external Cause. The RELATIVE KEY clause for an external file references a data item that is not external. 214 (Error) Relative key item within its file record Cause. The relative key data item for a file is defined in the file’s record description entries. 215 (Error) File status item not found Cause. The FILE STATUS clause references an undefined name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -44 Compiler Diagnostic Messages Message List 216 (Error) File status item not simple two character alphanumeric Cause. The FILE STATUS clause references either an object that is not a fixed-size two-character alphanumeric data item or an object that is a table or special register. 218 (Error) File status in improper section Cause. The FILE STATUS clause references a data item that is defined in the File Section. 219 (Error) Linage control item not found Cause. The LINAGE clause references an undefined name. 220 (Error) Linage control item not simple unsigned integer Cause. The LINAGE clause references either an object that is not an unsigned integer data item or an object that is a table or special register. 221 (Error) Linage control item not external Cause. The LINAGE clause for an external file references a data item that is not external. 222 (Error) Depending item not found Cause. A name referenced in the DEPENDING phrase of an OCCURS or RECORD clause is not defined. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -45 Compiler Diagnostic Messages Message List 223 (Error) Depending item not simple unsigned integer Cause. The DEPENDING phrase of a RECORD clause references either an object that is not an unsigned integer data item or an object that is a table or special register. 224 (Error) Depending item not simple integer Cause. The DEPENDING phrase of a OCCURS clause references either an object that is not an integer data item or an object that is a table or special register. 225 (Error) Depending item in improper section Cause. The data item referenced in the DEPENDING phrase of a RECORD clause is not defined in the Working-Storage, Extended-Storage, or Linkage Section. 226 (Error) Depending item not external Cause. The DEPENDING phrase of an OCCURS or RECORD clause for an external data item or an external file references a data item that is not external. 227 (Error) Depending item not global Cause. The data item in the DEPENDING phrase of an OCCURS clause controls the number of occurrences of a table that has a global data-name, but the data item itself does not have a global data-name, as it must. 228 (Error) Depending item within its table Cause. The data item in the DEPENDING phrase of an OCCURS clause is defined within the space of the table whose number of occurrences it controls. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -46 Compiler Diagnostic Messages Message List 229 (Error) Message source item not found Cause. The MESSAGE SOURCE references an undefined name. 230 (Error) Message source item not simple alphanumeric, has improper size, or not word-aligned Cause. The MESSAGE SOURCE clause references an object about which one of these is true: • • • • It is not a fixed-size alphanumeric data item. It is a table item. It has fewer than 32 character positions. It begins on an odd-character boundary within a record. 231 (Error) Error code item not found Cause. The ERROR CODE references an undefined name. 232 (Error) Error code item not simple unsigned integer Cause. The ERROR CODE clause references either an object that is not an unsigned integer data item or an object that is a table or special register. 233 (Warning or Error) Permitted value exceeds data item size Cause. Warning: One of: • • The maximum value assignable to the data item referenced in the DEPENDING phrase of an OCCURS clause is less than the maximum occurrence number of the table. The maximum value assignable to the data item referenced in the DEPENDING phrase of a RECORD clause is less than the maximum record size. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -47 Compiler Diagnostic Messages Message List Error: One of: • • The maximum value assignable to the POINTER operand in a STRING statement is less than or equal to the size of the receiving operand. The maximum value assignable to the POINTER operand in an UNSTRING statement is less than or equal to the size of the sending operand. 234 (Error) No sort-merge file name in SAME SORT clause Cause. None of the file names in the SAME SORT AREA clause identifies a sortmerge file. 235 (Error) Too many external objects Cause. The program defines more external objects (files and records) than the compiler can allocate. 236 (Error) Too many internal files Cause. The program defines more internal files than the compiler can allocate. 237 (Error) Improper target for ADDRESS OF clause Cause. One of these is true about the identifier-1 parameter in an ADDRESS OF clause: • • It is not a level-01 or level-77 data item in the Linkage Section. It has an ACCESS MODE STANDARD clause in its data description entry. 240 (Error) USING operand not linkage section data-name Cause. The USING phrase specifies an operand that is not defined as a data-name in the Linkage Section of the current program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -48 Compiler Diagnostic Messages Message List 241 (Error) USING operand subordinate or redefinition data-name Cause. The USING phrase specifies an operand about which one of these is true: • • It is not described as a level 01 or level 77 data-name. It is described as a redefinition of another data-name. 242 (Error) Data-name permitted only once as USING operand Cause. An operand appears more than once in the USING phrase. 243 (Error) Too many USING operands Cause. The USING phrase has more than 126 operands. 244 (Warning or Error) Linkage section data item not found as USING operand Cause. Warning: A data item defined in the Linkage Section is not referenced as a USING operand. Any references to it, any subordinates, or any redefinitions will produce unpredictable effects. Error: The compiler found a data item in the Linkage Section but not in the USING phrase of any CALL statement in the Procedure Division. 245 (Error) Improper context for DECLARATIVES Cause. The DECLARATIVES header does not precede all procedures in the Procedure Division. 246 (Error) Declarative paragraph not within section Cause. A paragraph-name in the Declaratives Portion of the Procedure Division is not subordinate to any section-name, as it must be. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -49 Compiler Diagnostic Messages Message List 247 (Error) Improper context for USE sentence Cause. The USE sentence does not immediately follow a section header in the Declaratives Portion of the Procedure Division, as it must. 248 (Error) Debugging procedures must be first declaratives Cause. Not all debugging procedures precede all nondebugging procedures in the Declaratives Portion of the Procedure Division. 249 (Error) Undefined debugging reference Cause. The indicated USE DEBUGGING statement cannot be resolved to any defined entity. 250 (Error) Debugging not supported for this object Cause. HP COBOL does not support debugging for this type of object. 251 (Error) Debugging not permitted for this object Cause. The COBOL language does not define debugging for this type of object. 252 (Error) Debugging not permitted for debugging procedures Cause. A USE DEBUGGING statement references a paragraph- name or sectionname that belongs to a debugging procedure. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -50 Compiler Diagnostic Messages Message List 253 (Error) Conflicting debugging declarative assignments Cause. One of: • • • • A USE DEBUGGING statement specifies the same object more than once. More than one USE DEBUGGING statement in a source program specifies the same object. The program has more than one USE DEBUGGING ALL PROCEDURES statement. The program has a USE DEBUGGING ALL PROCEDURES statement and other USE DEBUGGING statements that reference paragraph-names or section-names. 254 (Error) Conflicting exception declarative assignments Cause. One of: • • • A USE AFTER EXCEPTION PROCEDURE statement specifies the same file name more than once. More than one USE AFTER EXCEPTION PROCEDURE statement in a source program specifies the same file name. More than one USE AFTER EXCEPTION PROCEDURE statement in a source program specifies the same open mode (INPUT, OUTPUT, I-O, or EXTEND). 255 (Error) Missing END DECLARATIVES Cause. The Procedure Division does not contain the END DECLARATIVES header needed to terminate its Declaratives Portion. 256 (Error) Improper context for END DECLARATIVES Cause. The Procedure Division contains an extraneous END DECLARATIVES header. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -51 Compiler Diagnostic Messages Message List 257 (Error) No declarative procedures Cause. The Declaratives Portion exists, but contains no procedures. 258 (Error) No nondeclarative procedures Cause. The current source program has an explicit Procedure Division, but its nondeclarative portion is empty. 259 (Error) Exception phrase not compatible with file description Cause. An exception phrase corresponds to a statement with which it cannot be associated. Possible reasons are: • • • The statement references a file whose description is incompatible with the phrase. A READ statement specifies the NEXT phrase and the exception phrase is INVALID KEY or NOT INVALID KEY. A READ statement does not specify the NEXT phrase and the exception phrase is AT END or NOT AT END. 260 (Error) Improper context for exception phrase Cause. There is no preceding statement with which the exception phrase can be associated. 261 (Error) Improper context for ELSE phrase Cause. There is no preceding statement with which the ELSE phrase can be associated. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -52 Compiler Diagnostic Messages Message List 262 (Error) Improper context for WHEN phrase Cause. There is no preceding statement with which the WHEN phrase can be associated. 263 (Error) Improper context for scope delimiter Cause. There is no preceding statement with which the explicit scope delimiter can be associated. 264 (Error) Missing AT END phrase Cause. A RETURN statement does not have an associated AT END phrase. 265 (Error) Missing WHEN phrase Cause. A preceding EVALUATE or SEARCH statement does not include a WHEN phrase. 266 (Error) Missing scope delimiter Cause. A statement appears in a context that requires an explicit scope delimiter, but the appropriate scope delimiter is not specified. 267 (Error) Improper context for EXIT or empty GO TO statement Cause. An EXIT or GO TO statement that does not specify a procedure-name is not the only statement in its sentence, as it must be. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -53 Compiler Diagnostic Messages Message List 268 (Error) Improper context for NEXT SENTENCE Cause. NEXT SENTENCE is neither in an IF or SEARCH statement nor a replacement for an imperative-statement. 269 (Error) Prior statement must be last in its sequence Cause. The prior statement appears in a sequence of statements, but is not the last one in the sequence, as it must be. 270 (Error) Expected integer numeric literal Cause. One of: • • Only an integer numeric literal can appear in this context. When a literal appears in this context, it must be an integer numeric literal. 271 (Error) Undefined object reference Cause. The reference cannot be resolved to any object that the current source program can access. (Check the spelling of the object name and verify that all qualifiers are correct and in the proper order.) 272 (Error) Improper context for special register Cause. Usually, a special register has been used as a receiving operand, which is not allowed. 273 (Error) Improper context for debugging special register Cause. References to the special register DEBUG-ITEM or any of its subordinates are not in a debugging procedure in the Declaratives Portion of the Procedure Division, as they must be. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -54 Compiler Diagnostic Messages Message List 274 (Error) Expected data item Cause. The specified operand cannot appear in this context. (A data item with appropriate attributes would be acceptable here. Other types of operands, such as literals, might also be acceptable.) 275 (Error) Expected display data item Cause. The data item does not have USAGE DISPLAY, as it must. 276 (Error) Expected display data item, no Ps if numeric Cause. Either the data item does not have USAGE DISPLAY (as it must), or it is a numeric item with P s in its PICTURE character-string (which it must not have). 277 (Error) Expected display data item, not edited nor justified Cause. One of is true about the data item: • • • It does not have USAGE DISPLAY. It is an alphanumeric-edited or numeric-edited item. It is described with a JUSTIFIED clause. 278 (Error) Expected alphanumeric data item Cause. The data item is not alphanumeric, as it must be. 279 (Error) Expected numeric or numeric-edited data item Cause. The data item is neither numeric nor numeric-edited, as it must be. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -55 Compiler Diagnostic Messages Message List 280 (Error) Expected numeric data item Cause. The data item is not numeric, as it must be. 281 (Error) Expected integer numeric data item Cause. The data item is not numeric without fraction digits, as it must be. 282 (Error) Expected unscaled numeric data item Cause. Either the data item is not numeric without fraction digits, or it has Ps in its PICTURE character-string. 283 (Error) Expected index data item or integer numeric data item Cause. The data item does not have USAGE INDEX and is not a numeric item without fraction digits. 284 (Error) Expected group data item Cause. The data item is not a data structure, as it must be. 285 (Error) Expected data file record data item Cause. The data item is not a level-01 item subordinate to a data file description entry (level indicator FD), as it must be. 286 (Error) Expected sort-merge file record data item Cause. The data item is not a level-01 item subordinate to a sort-merge file description entry (level indicator SD), as it must be. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -56 Compiler Diagnostic Messages Message List 287 (Error) Expected level 01 or level 77 or elementary data item Cause. One of: • • The FIPS directive specified NONSTANDARDEXT, but the data item is not a level01 item, a level-77 item, or an elementary item of a record. No FIPS directive specified NONSTANDARDEXT, but the data item is not elementary, level-01, level-77, or at a level other than 01 or 77 and aligned on a 2-byte boundary. If the data item is subscripted, its first occurrence must be on a 2-byte boundary and the number of occurrences must be even. 288 (Error) Extended storage data item not permitted Cause. The data item is either defined in the Extended-Storage Section or described with the ACCESS MODE EXTENDED-STORAGE clause. 289 (Error) Index data item not permitted Cause. A reference to an index data item cannot appear in this context. 290 (Error) Alphabetic data item not permitted Cause. The receiving data item is described as alphabetic when the data source for an ACCEPT statement is DATE, DAY, DAY-OF-WEEK, or TIME. 291 (Error) Numeric-edited data item not permitted Cause. A numeric-edited data item is specified as an arithmetic operand. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -57 Compiler Diagnostic Messages Message List 292 (Error) Improper context for subscripts Cause. A subscript is in the specification of either the table operand in a SEARCH statement or the key operand in a START statement. 293 (Error) Too many or too few subscripts Cause. The reference to a table item or condition-name associated with a table item does not have the correct number of subscripts. 294 (Error) Table item not permitted in subscript Cause. A reference to a table item appears as a subscript. 295 (Error) Index-name not associated with table level Cause. The index-name appears in a reference whose subject is not described by the OCCURS clause that defines the index-name. 296 (Error) Reference modifier permitted only for display data item Cause. A reference modifier is specified, but the subject of the reference is not a dataname described with USAGE DISPLAY. 297 (Error) Improper context for reference modifier Cause. A reference modifier cannot be specified for the data item indicated. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -58 Compiler Diagnostic Messages Message List 298 (Error) Expected arithmetic operand Cause. The operand of an arithmetic operator is not a numeric literal, a numeric data item, or an arithmetic expression, as it must be. 299 (Warning) Division by zero Cause. The value of a divisor is 0. 300 (Error) Expected relation operand Cause. The operand of a relational operator is not a literal, index-name, data item, or arithmetic expression, as it must be. 301 (Error) Have no implicit operand for relation Cause. There is no implicit left-hand operand to complete the relation. 302 (Error) Relation operands not compatible Cause. One of: • • • • An arithmetic expression was compared with something other than another arithmetic expression, a numeric data item, or a numeric literal. An index-name was compared with something other than another index-name, an index data item, a numeric data item, or a numeric literal. An index data item was compared with something other than another index data item or an index-name. A pointer (a data item with USAGE POINTER, or ADDRESS OF data-item, or NULL) can be compared only with another pointer. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -59 Compiler Diagnostic Messages Message List 303 (Error) No variable among relation operands Cause. A relation includes no references to data items; it is constructed solely from literal operands. 304 (Error) Expected class-name Cause. A name referenced in a context where it must identify a class-name does not. 305 (Error) Improper operand for class test Cause. The subject of a class test is not an identifier, as it must be. 306 (Error) Improper item for alphabetic or class-name test Cause. The subject of a class-name such as ALPHABETIC or NOT ALPHABETIC is numeric. 307 (Error) Improper item for numeric test Cause. The subject of a NUMERIC or NOT NUMERIC test is either alphabetic or is a data structure that has a subordinate described with an embedded operational sign. 308 (Error) Expected condition as operand Cause. The operand indicated appears in a context that requires a simple or complex condition, such as the operand of an AND, OR, or NOT operator or the operand of a WHEN phrase. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -60 Compiler Diagnostic Messages Message List 309 (Error) Expected data file Cause. Only a file name defined in a data file description entry (level indicator FD) is permitted in this context. 310 (Error) Expected sort-merge file Cause. Only a file name defined in a sort-merge file description entry (level indicator SD) is permitted in this context. 311 (Warning) No corresponding pairs Cause. The two data structures specified in a CORRESPONDING operation contain no corresponding subordinates. 312 (Error) Phrase permitted only for sequential organization Cause. One of these phrases is used on a file that does not have sequential organization: • • • • • ADVANCING NO REWIND PROMPT REEL UNIT 313 (Error) FROM or INTO data item overlaps file record Cause. The data item specified in the INTO or FROM phrase overlaps part of the file record area. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -61 Compiler Diagnostic Messages Message List 314 (Error) Expected mnemonic-name associated with a file name Cause. The referenced operand is not a mnemonic-name associated with an external file name in the SPECIAL-NAMES paragraph. 315 (Error) Permitted only when NONSTOP directive specified Cause. The program has a CHECKPOINT or STARTBACKUP statement, but was not compiled with the NONSTOP directive. 316 (Error) Improper context for ROUNDED Cause. ROUNDED appears in the REMAINDER phrase of a DIVIDE statement. 317 (Error) DELETE not permitted for sequential organization Cause. The file name specified in a DELETE statement identifies a file with sequential organization. 318 (Error) Improper context for ALSO phrase Cause. The ALSO phrase appears in a SEARCH statement. 319 (Error) Improper context for condition Cause. A condition appears in an object that includes the THROUGH phrase. 320 (Error) Range operands not compatible Cause. Operands in an object that includes the THROUGH phrase are not of the same class (alphabetic, alphanumeric, numeric). HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -62 Compiler Diagnostic Messages Message List 321 (Error) Too many subject operands Cause. An EVALUATE statement has more than 127 subjects. 322 (Error) Too many object operands Cause. The number of objects in the WHEN phrase is greater than the number of subjects in the EVALUATE statement. 323 (Error) Too few object operands Cause. The number of objects in the WHEN phrase is less than the number of subjects in the EVALUATE statement. 324 (Error) Corresponding operands not compatible Cause. The object in the WHEN phrase is incompatible with the corresponding subject in the EVALUATE statement. 325 (Error) No variable among corresponding operands Cause. Both the object in the WHEN phrase and the corresponding subject in the EVALUATE statement contain only literal operands. 326 (Error) Variable occurrences or 66 level data item not permitted Cause. One of: • • An OCCURS clause that includes the DEPENDING phrase appears in the description of a receiving operand in the INITIALIZE statement or in the description of any subordinate data item. A receiving operand of the INITIALIZE statement has level-number 66. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -63 Compiler Diagnostic Messages Message List 327 (Error) Receiving category not compatible with sending category Cause. The receiving operand cannot be assigned a value derived from the sending operand; for example: • • SPACE (or one of its equivalents), an alphabetic data item, or an alphanumericedited data item cannot be assigned to a numeric or numeric-edited data item. ZERO (or one of its equivalents), a numeric literal, a numeric data item, or a numeric-edited data item cannot be assigned to an alphabetic data item. This message usually results from a MOVE statement. It can also result from statements whose execution includes assignment operations that follow MOVE statement rules. 328 (Error) Receiving operand not compatible with sending operand Cause. The attributes of the receiving operand do not permit assigning it a value derived from the sending operand; for example: • • • • • A numeric data item is being set to the value of a nonnumeric literal, nonnumeric data item, or index data item. An index data item is being set to the value of a nonnumeric literal or nonnumeric data item. A data item other than an index-name is being set UP or DOWN. A data item other than a mnemonic-name associated with an external switch is being set ON or OFF. A data item other than a condition-name associated with a data item is being set to TRUE or FALSE. 329 (Error) INSPECT operand sizes not compatible Cause. One of: • • The replaced and replacing operands have incompatible sizes. When replacing CHARACTERS or a figurative constant, the size of the replacing operand must be one character. When replacing a numeric or nonnumeric literal or a data item, the size of the replacing operand must be the same as that of the replaced operand. The CONVERTING phrase operands are not the same size. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -64 Compiler Diagnostic Messages Message List 330 (Error) NO REWIND phrase not permitted for I-O or EXTEND mode Cause. The NO REWIND phrase appears when the open mode is I-O or EXTEND. 331 (Error) EXTEND mode permitted only for sequential access Cause. EXTEND mode is specified for a file access whose access is not sequential. 332 (Error) EXTEND mode not permitted for MULTIPLE FILE TAPE file Cause. EXTEND mode is specified for a file name that is specified in a MULTIPLE FILE TAPE clause. 333 (Error) EXTEND mode not permitted for LINAGE file Cause. EXTEND mode is specified for a file name that is described with a LINAGE clause. 334 (Error) Too many AFTER phrases Cause. A PERFORM statement has more than 6 AFTER phrases. 335 (Error) NEXT/REVERSED not compatible with random access Cause. The NEXT phrase is used with a READ statement that specifies a file name described with random access. 336 (Error) PROMPT data item overlaps file record Cause. The data item specified in the PROMPT phrase overlaps the file record area, but the data item and file record area do not begin at the same character position. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -65 Compiler Diagnostic Messages Message List 337 (Warning) PROMPT data item exceeds record size Cause. The size of the PROMPT phrase operand exceeds the maximum record size for the file. (The excess characters will not appear in the prompt.) 338 (Error) Operands not compatible for INTO assignment Cause. One of: • • The record descriptions of the file referenced in this statement require that the INTO phrase operand be alphanumeric, and it is not. The record descriptions of the file referenced in this statement prohibit specification of the INTO phrase. 339 (Warning) No editing occurs for INTO assignment Cause. The value of the INTO phrase operand is assigned according to the rules for a group move; thus, no editing operations occur. 340 (Error) Expected table item with index-names Cause. The description of the table operand in a SEARCH statement has an OCCURS clause that does not include the INDEXED phrase. 341 (Error) Expected table item with keys Cause. The description of the table operand in a SEARCH ALL statement has an OCCURS clause with no KEY phrases. 342 (Error) VARYING phrase not permitted with ALL Cause. The VARYING phrase is appears in a SEARCH ALL statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -66 Compiler Diagnostic Messages Message List 343 (Error) Not permitted in declaratives Cause. A SORT or a MERGE statement appears in the Declaratives Portion of the Procedure Division. 344 (Error) Key within table or has variable size Cause. A reference in an ASCENDING KEY or DESCENDING key phrase identifies a data item that has a variable size or is referenced by an OCCURS clause. 345 (Error) Key not found within sort-merge file record Cause. A reference in an ASCENDING KEY or DESCENDING key phrase identifies a data item defined in the record descriptions of the sort-merge file. 346 (Error) Key not contained within minimum sort-merge file record Cause. The key data item is not completely contained within the shortest possible record of the sort-merge file. 347 (Error) Prime record key inconsistent with major sort-merge key Cause. A GIVING phrase specifies an indexed file, but the major sort-merge key does not have the ASCENDING attribute or does not occupy the same character positions within the sort-merge file records as the prime key item occupies within the indexed file records. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -67 Compiler Diagnostic Messages Message List 348 (Error) Record size incompatible with sort-merge file description Cause. One of: • • The longest possible record of a USING file exceeds the record capacity of the sort-merge file. The longest possible record of the sort-merge file exceeds the record capacity of a GIVING file. 349 (Error) Random access not permitted Cause. A MERGE, SORT, or START statement specifies a file name described with random access. 350 (Error) File set conflict from xxxx Cause. A SORT or MERGE statement specifies conflicting files. xxxx is one of these phrases: Phrase Meaning duplicate file names The same file name appears more than once in a MERGE statement. SAME AREA clause Two or more file names specified in one SAME AREA clause appear in a MERGE statement or in the GIVING phrase of a SORT statement. SAME RECORD clause Two or more file names specified in one SAME RECORD clause appear in the USING phrase of a MERGE statement. MULTIPLE FILE TAPE clause Two or more file names specified in one MULTIPLE FILE TAPE clause appear in a MERGE statement or in the GIVING phrase of a SORT statement. 351 (Error) KEY phrase not permitted for sequential access Cause. The KEY phrase applies to a file whose access is not sequential. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -68 Compiler Diagnostic Messages Message List 352 (Error) KEY phrase not compatible with NEXT phrase Cause. The KEY phrase appears with a NEXT phrase. 353 (Error) KEY item not found within file record Cause. The reference in the KEY phrase does not identify a key of the specified file. 354 (Error) Length of combined keys exceeds 253 characters Cause. In a file-control entry with multiple keys, the sum of the lengths of the keys exceeds 253 characters. 355 (Error) File has no default prime key Cause. The KEY phrase appears in a statement other than a START statement, and the file is neither indexed nor described with a RELATIVE KEY phrase. 356 (Error) Improper relation for this context Cause. One of: • • The operator in the KEY phrase is not equal sign (=), greater-than sign (>), greater-than-or-equal sign (>=), or one of their equivalents. The POSITION or GENERIC phrase is present, and the operator in the KEY phrase is not the equal sign (=) or EQUAL. 357 (Error) Expected file key or equivalent Cause. The operand in the KEY phrase is neither a data item described as a file key, nor a data item whose leftmost character position coincides with the leftmost character position of a file key and whose length is less than or equal to the length of that file key. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -69 Compiler Diagnostic Messages Message List 358 (Error) Position data item must be prime key Cause. The operand in the POSITION phrase is not the file’s prime key. (The prime key of a relative file is defined by the RELATIVE KEY clause; the prime key of an indexed file is defined by the RECORD KEY clause.) 359 (Error) ADVANCING mnemonic-name not compatible with LINAGE Cause. The ADVANCING mnemonic-name phrase is used for a file described with the LINAGE clause. 360 (Error) Operand too large Cause. The size of the operand exceeds the maximum supported for its context. 361 (Error) Improper object file name Cause. A reference to a routine or COBOL program specifies the object file from which it must be selected, but the external file name associated with the specified mnemonic-name does not identify a disk-resident file. 362 (Error) Inconsistent object file reference Cause. One of: • • Not all of the CALL and CANCEL statements specifying a particular COBOL agree about the object file from which it must be selected. Not all of the ENTER statements specifying a particular routine agree about the object file from which it must be selected. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -70 Compiler Diagnostic Messages Message List 363 (Error) Improper language name Cause. For the COBOL85 compiler, the language in an ENTER statement must be C, FORTRAN, Pascal, or TAL. For the NMCOBOL compiler, it must be C or TAL. 364 (Error) Improper unit-name for language Cause. One of: • • The program-name does not conform to the spelling rules of COBOL. The routine-name does not conform to the spelling rules of its language. 365 (Error) Unit of proper language not found Cause. One of: • • Either the requested COBOL program does not exist in the specified object file, or an entity identified by the program-name exists but is not a COBOL program. Either the requested routine does not exist in the specified object file, or an entity identified by the routine-name exists but is not a routine of the proper language. If the called program is a system routine, the called program might not be in the COBOLEXT or NMCOBEXT file, and you must compile the program with the one of these directives: • • CONSULT $SYSTEM.SYSTEM.COBOLEX0 CONSULT $SYSTEM.SYSTEM.NMCOBEX0 366 (Error) Inconsistent language reference for unit-name Cause. Not all of the ENTER statements specifying a particular routine agree about its language. 367 (Error) Unit has invalid attribute Cause. An called routine has an invalid parameter. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -71 Compiler Diagnostic Messages Message List 368 (Error—COBOL85 compiler only) Compiler version attribute conflict Cause. One of: • • The requested program was compiled by an incompatible version of the compiler. (Recompile it with the current version of the compiler.) The requested program was compiled to run in a language-specific environment when it must run in the CRE. Recompile it to run in the CRE. 369 (Warning) NONSTOP attribute conflict Cause. One of: • • The source text from which the indicated COBOL program was compiled included the NONSTOP directive, but the current source text does not. The current source text includes a NONSTOP directive, but the source text from which the indicated COBOL program was compiled did not. Run-time problems might occur if proper operation of the program depends on the run unit’s executing as a process pair. 370 (Error) Inconsistent parameter attributes Cause. One of: • • • Different CALL statements referencing the same COBOL program specify a different number of parameters in their USING phrases. The number of parameters defined in the Procedure Division of a COBOL program differs from the number of parameters expected by the callers. For one or more parameters of a COBOL program, the access mode (STANDARD or EXTENDED-STORAGE) defined in the program differs from the access mode expected by the callers. 371 (Error) Formal parameter not a variable Cause. The formal parameter of the called routine is neither a data variable nor the word OMITTED. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -72 Compiler Diagnostic Messages Message List 372 (Error) COBOL85 Compiler: Formal parameter for file name must have word address NMCOBOL Compiler: Actual parameter is a file, so formal parameter must be a struct Cause. The actual parameter of an ENTER statement is a file name (FD or SD), but it does not correspond to a formal parameter that expects a 2-byte address (for the COBOL85 compiler) or a struct (for the NMCOBOL compiler). 373 (Warning) Potential odd byte address converted to even byte address Cause. The compiler cannot determine if a problem exists. Verify that the correct address is passed to the routine. Most COBOL data items are referenced internally by byte addresses. When one of these appears as the actual parameter corresponding to the formal parameter of a routine that expects a 2-byte address, the compiler must convert the item’s byte address to a 2-byte address. If the data item begins on an odd-byte boundary, that information is lost by the conversion operation (thus the value space of the item appears, to the called routine, to begin one byte before it actually does). If the data item begins on an even-byte boundary, there is no problem. 374 (Error) OMITTED permitted only for extensible or variable routine Cause. OMITTED appears as an actual parameter, but the called routine does not have the EXTENSIBLE or VARIABLE attribute. 375 (Error) GIVING phrase permitted only for function routine Cause. An ENTER statement includes the GIVING phrase, but the called routine is not a function (that is, it does not return a value). HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -73 Compiler Diagnostic Messages Message List 376 (Error) Routine type not supported Cause. The routine returns a value of a type that HP COBOL does not support; therefore, it cannot have a GIVING phrase. 377 (Warning) Reference with mnemonic-name resolved to contained program Cause. References to a COBOL program specify an object file from which it should be selected, but because the program-name identifies an accessible contained program, the compiler resolves the references to that program. Examine the program logic to verify that this result is acceptable. 378 (Warning) Expected digit string as sending operand Cause. A nonnumeric operand moved to a numeric operand has a value not composed entirely of digits. The result of the assignment is not defined. 379 (Error) Formal parameter type not supported Cause. One of: • • • • In the non-CRE environment, an ENTER statement passed a pointer to an HP C or HP C++ program. (In the CRE, this is allowed.) A formal parameter has a type that is not supported. A value parameter was passed, but the corresponding formal parameter’s type is not numeric or character. An actual parameter was omitted, but the corresponding formal parameter is not a type that can be omitted. 380 (Error) Too many procedure names Cause. The number of procedure names in the statement exceeds the maximum number allowed in the statement. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -74 Compiler Diagnostic Messages Message List 381 (Error) PROMPT/LOCK phrase cannot be specified with REVERSED Cause. A READ statement with a REVERSED phrase also has a PROMPT or LOCKED phrase. 382 (Error) Undefined procedure reference Cause. One of: • • The name indicated appears as a procedure reference, but does not identify a paragraph-name or section-name defined within the Procedure Division of the current source program. The name indicated appears in a procedure reference with a qualifier, but does not identify a paragraph-name defined both as a subordinate of the section identified by the qualifier and within the Procedure Division of the current source program. 383 (Error) Ambiguous procedure reference Cause. The name indicated appears in a procedure reference but does not identify a unique object within the current source program. 384 (Error) Improper ALTER subject Cause. A procedure reference that appears as an ALTER statement subject does not identify a paragraph or section containing only a single unconditional GO TO statement. 385 (Warning or Error) Improper ALTER context Cause. Warning: An ALTER statement modifies the GO TO statement of a paragraph or section in an independent segment. HP COBOL does not support the semantics for independent segments described in the ISO/ANSI COBOL standard (it does not restore the original specification of the GO TO statement if control leaves the independent segment and then returns to it later). HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -75 Compiler Diagnostic Messages Message List Error: An ALTER statement appearing in one independent segment modifies a GO TO statement of a paragraph or section in another independent segment. 386 (Warning or Error) Improper ALTER scope Cause. Warning: One of: • • • An ALTER statement in the nondeclarative portion of the Procedure Division references a paragraph-name or section-name defined in a declarative procedure. An ALTER statement in a declarative procedure references a paragraph-name or section-name defined in another declarative procedure. An ALTER statement modifies a GO TO statement so that its execution will transfer control from one declarative procedure to another declarative procedure. Error: One of: • • • • An ALTER statement in a declarative procedure references a paragraph-name or section-name defined in the nondeclarative portion of the Procedure Division. An ALTER statement in a nondebugging declarative procedure references a paragraph-name or section-name defined in a debugging declarative procedure. An ALTER statement modifies a GO TO statement so that its execution will transfer control into or out of the Declaratives Portion the Procedure Division. An ALTER statement modifies a GO TO statement so that its execution will transfer control between a debugging declarative procedure and a nondebugging declarative procedure. 387 (Warning or Error) Improper GO TO scope Cause. Warning: A GO TO statement transfers control from one declarative procedure to another declarative procedure. Error: One of: • • A GO TO statement transfers control between the declarative and nondeclarative portions of the Procedure Division. A GO TO statement transfers control between a debugging declarative procedure and a nondebugging declarative procedure. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -76 Compiler Diagnostic Messages Message List 388 (Warning or Error) Improper PERFORM scope Cause. Warning: A PERFORM statement specifies a range that includes two references. One identifies a paragraph-name or section-name defined in a declarative procedure. The other identifies a paragraph-name or section-name defined in another declarative procedure. It is recommended that both references identify items in the same declarative procedure. Error: One of: • • • • A PERFORM statement in an independent segment references a paragraph-name or section-name defined in another independent segment. A PERFORM statement in a declarative procedure references a paragraph-name or section-name defined in the nondeclarative portion of the Procedure Division. A PERFORM statement references a paragraph-name or section-name defined in a debugging declarative procedure, but the statement itself is not in a debugging declarative procedure. When the range specified in a PERFORM statement includes two references, they must identify compatible paragraph-names or section-names. If one is defined in the Declaratives Portion of the Procedure Division, the other must also be defined in the Declaratives Portion. If one is defined in an independent segment, the other must be defined in the same independent segment. 389 (Warning or Error) Improper SORT/MERGE scope Cause. Warning: An INPUT PROCEDURE or OUTPUT PROCEDURE phrase specifies a range that includes two references. One identifies a paragraph-name or section-name defined in a declarative procedure. The other identifies a paragraphname or section-name defined in a different declarative procedure. Error: One of: • • An INPUT PROCEDURE or OUTPUT PROCEDURE phrase of a SORT or MERGE statement in an independent segment references a paragraph-name or section-name defined in a different independent segment. An INPUT PROCEDURE or OUTPUT PROCEDURE phrase of a SORT or MERGE statement specifies a range that includes two references, and they identify incompatible paragraph-names or section-names. Either one reference is defined in the Declaratives Portion of the Procedure Division and the other is not, or one is defined in one independent segment and the other is defined in another independent segment. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -77 Compiler Diagnostic Messages Message List 390 (Warning) Referenced program not found by compiler Cause. A CALL or CANCEL statement referenced a program that the compiler could not find in the source text or in any file on any search list. These programs must be bound into the run unit before it is executed. The COBOL85 compiler issues this warning only once: at the end of the compiler listing, followed by the names of all the program units that it could not find. The NMCOBOL compiler issues this warning at the point of reference to the program unit (that is, at a CALL or CANCEL statement); however, for any given missing program, the compiler issues the warning only at the first point of reference to that program. 391 (Error) Improper program-name specified Cause. One of: • • A CALL or CANCEL statement specifies the program-name of the separately compiled program within which it appears. The END PROGRAM statement identifies a program that has already been terminated. 392 (Error) Expected current program-name Cause. The END PROGRAM statement specifies a name that does not match any program-name within the separately compiled program. 393 (Error) Missing END PROGRAM: xxxx Cause. No END PROGRAM statement appeared for the contained program whose program-name is xxxx. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -78 Compiler Diagnostic Messages Message List 395 (Error) More than one implicit MAIN program Cause. Both the current COBOL program and a preceding one qualify for the MAIN attribute. Because the compiler cannot determine which one should be the main program, it does not produce an object file. 396 (Warning) Condition-name has too many values to be referenced by INSPECT Cause. A condition-name has more values than the compiler can send to theInspect debugger. The compiler sends only the first value. To make all of the values available to theInspect debugger, replace the condition-name with several condition names, each with a less demanding VALUE clause, and reference all of them wherever the original condition-name is currently referenced. 397 (Error) Program data space overflow Cause. The data items defined in the File and Working-Storage Sections of a source program need more program data space than is available for the entire run unit. 398 (Error) Program extended data space overflow Cause. The data items defined in the Extended-Storage Section of a source program need more program extended data space than is available for the entire run unit. 399 (Error) Program control space overflow Cause. The objects defined in a source program need more run-time program control space than is available for the entire run unit. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -79 Compiler Diagnostic Messages Message List 400 (Error) Program code exceeds 65500 words Cause. The object code generated for a separately compiled program exceeds 131 KB, which is the maximum size supported. Recovery. Recompile the program without the CHECK directive and with the NOBLANK and LESS-CODE 1 directives. If error 400 still occurs, change the source program: • • • • Remove unused code. Break the program into two or more compilation units (see Compilation Units). Find sequences of code that occur several times and make each of them a procedure (see Procedures and Procedure Execution). To transfer control to a paragraph or procedure, use the statement PERFORM. Change level-77 data items and elementary level-01 data items that are numeric from USAGE DISPLAY to USAGE COMP (see USAGE Clause). 401 (Error) Embedded program code exceeds 32767 words Cause. The object code generated for a contained program exceeds 65,534 bytes, which is the maximum size supported. 402 (Error) Reference modifier first character out of range Cause. In a reference modifier, the value of the first character position exceeds the size of the subject data item. 403 (Error) Reference modifier length out of range Cause. In a reference modifier, the value of the last character position firstcharacter-position + length - 1 exceeds the size of the subject data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -80 Compiler Diagnostic Messages Message List 404 (Warning) Size error on literal expression Cause. The compiler has determined that this expression, composed solely of literal operands, will always generate the size error condition during execution. If the associated statement includes the SIZE ERROR clause, the program takes the size error branch; otherwise, an arithmetic overflow can result, or (if the receiving item is of USAGE COMPUTATIONAL) the program can store a number larger than the maximum value allowed for the item, leading to an arithmetic overflow later in the execution. 405 (Warning) Relation truth value is constant Cause. The compiler has determined that the value of this relation condition will be always TRUE or always FALSE. (Example: a literal is compared to a shorter data item.) This message might point only to the statement in error, not to the erroneous line of the statement. 406 (Warning) SET statement literal not in subscript range Cause. A value of a numeric literal specified as the sending operand in a SET statement is greater than the maximum occurrence number defined for assignment to an index-name specified as a receiving operand. Execution of the statement will assign an improper value to the index-name. 407 (Warning) Improper SEARCH ALL condition - serial search used Cause. A SEARCH ALL statement specifies a condition that does not conform to the rules of the COBOL language. HP COBOL employs a serial rather than a binary search technique in this situation. 408 (Error) Program buffer space exceeds 31000 words Cause. The sum of the buffer space needed for files exceeds 62 KB. (Reduce the size of blocks specified in the BLOCK CONTAINS clause in one or more File Description entries or reduce the number of files.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -81 Compiler Diagnostic Messages Message List 425 (Error) Usage clause not permitted with specified picture Cause. A national data item contains a USAGE clause. 426 (Error) Synchronized clause not permitted with specified picture Cause. A national data item contains a SYNCHRONIZED clause. 427 (Error) Multi-byte not permitted in this context Cause. A national data item or national literal appears where it is not permitted. 428 (Error) Literal and data item must both be multi-byte Cause. A literal or data item that is not in the national class appears where all the literals and data items must be in the national class. 429 (Error) Can only compare multi-byte type to multi-byte type Cause. In a conditional statement, a national data item or national literal is compared to something other than another national data item or national literal. 430 (Error) Expecting multi-byte data item or literal Cause. A literal or data item that is not in the national class appears where all the literals and data items must be in the national class. 440 (Error) External file not allowed in library object Cause. A program in a user library references an external file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -82 Compiler Diagnostic Messages Message List 441 (Error) External data item not allowed in library object Cause. A program in a user library references an external data item. 442 (Error) Library object cannot contain a main program Cause. A main program is in a user library. 443 (Error) Library object can only contain initial programs Effect. A program that is not an initial program is in a user library. 444 (Error) Embedded programs are not allowed in library object Cause. An embedded program is in a user library. 445 (Error) Global data item not allowed in library object Cause. A data item with the GLOBAL attribute is in a user library. 446 (Error) COLLATING SEQUENCE clause not allowed in library Cause. A program in a COPY library or user library has a PROGRAM COLLATING SEQUENCE clause in its Environment Division. 447 (Error) Global file not allowed in library object Cause. A file whose COBOL file name has the GLOBAL attribute is in a user library. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -83 Compiler Diagnostic Messages Message List 448 (Error) EXTENDED-STORAGE not allowed in library object Cause. A program with an EXTENDED-STORAGE section is in a user library. 449 (Error) Parameter not allowed in old environment object Cause. An object file that was produced for the non-CRE environment (that is, the corresponding source program was compiled with the directive ENV OLD) contains a parameter that is not allowed in the non-CRE environment. 450 (Error) COBOLSPOOLOPEN allowed only in old environment Cause. An object file that was produced for the CRE environment (that is, the corresponding source program was compiled with the directive ENV COMMON or ENV LIBRARY) contains a call to the COBOLSPOOLOPEN routine. 461 (Error) Internal SQL error Cause. The compiler’s internal consistency checker discovered a logic error. Please report this failure to your service provider. 462 (Error) Improper usage clause for host variable Cause. An SQL/MP or SQL/MX host variable has an improper USAGE clause. 463 (Error) Host variable picture string cannot contain 'P' Cause. An SQL/MP or SQL/MX host variable’s PICTURE string contains P. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -84 Compiler Diagnostic Messages Message List 464 (Error) Improper category for host variable Cause. An SQL/MP or SQL/MX host variable is in the wrong category. 465 (Error) Host variable's picture string cannot contain '*' Cause. An SQL/MP or SQL/MX host variable’s PICTURE string contains an asterisk (*). 466 (Error) JUSTIFIED clause not allowed for host variables Cause. An SQL/MP or SQL/MX host variable contains a JUSTIFIED clause. 467 (Error) OCCURS clause not allowed for host variables Cause. An SQL/MP or SQL/MX host variable contains a OCCURS clause. 468 (Error) The RENAMES is ignored Cause. An SQL/MP or SQL/MX host variable contains a RENAMES clause. 470 (Error) Missing END-EXEC Cause. The compiler processed the maximum number of SQL/MP or SQL/MX statement lines without encountering the SQL/MP or SQL/MX statement terminator END-EXEC. 471 (Error) Ambiguous reference to SQLCA Cause. More than one SQLCA is declared in the program, and the SQLCA in this statement is ambiguous in this context. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -85 Compiler Diagnostic Messages Message List 472 (Error) SQLCA is declared incorrectly Cause. SQLCA is declared incorrectly (it must be a data structure). 473 (Error) Ambiguous reference to SQLCODEX Cause. More than one SQLCODEX is declared in the program, and the SQLCODEX in this statement is ambiguous in this context. 474 (Error) SQLCODEX is declared incorrectly Cause. SQLCODEX is declared incorrectly (it must be a COMPUTATIONAL data item with no editing characters). 475 (Error) Ambiguous reference to SQLCODE Cause. More than one SQLCODE is declared in the program, and the SQLCODE in this statement is ambiguous in this context. 476 (Error) SQLCODE is declared incorrectly Cause. SQLCODE is declared incorrectly (it must be a COMPUTATIONAL data item with no editing characters). 477 (Error) Program is missing SQLCODE Cause. SQLCODE is required in the program, but is missing. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -86 Compiler Diagnostic Messages Message List 478 (Error) Ambiguous reference to SQLSA Cause. More than one SQLSA is declared in the program, and the SQLSA in this statement is ambiguous in this context. 479 (Error) SQLSA is declared incorrectly Cause. SQLSA is declared incorrectly (it must be a COMPUTATIONAL data item with no editing characters). 480 (Error) Improper context for INCLUDE Cause. An SQL/MP or SQL/MX INCLUDE statement is outside of the Data Division. (It must be inside.) 481 (Error) Improper context for CHARACTER SET clause Cause. A CHARACTER-SET clause appears somewhere other than the final clause in an OBJECT-COMPUTER paragraph. 482 (Error) Expecting elementary data item Cause. A data structure appears where an elementary data item is expected. 490 (Error) Improper context for ALL subscript Cause. The ALL subscript applied to an argument to an intrinsic function is either not allowed in this context or not allowed on any argument to this function. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -87 Compiler Diagnostic Messages Message List 491 (Error) Function nesting too deep Cause. Functions are nested so deeply within a single statement that the compiler cannot process them. 492 (Error) Subscripting not allowed on a function Cause. A subscript appears on a function. (A subscript can only appear on a table.) 493 (Error) Improper context for function Cause. An intrinsic function appears where it is not allowed (as a receiving item in a statement, for example). 494 (Error) Unknown function Cause. The compiler does not recognize the function name. 495 (Error) Expression is too complex Cause. An expression is so complex that the compiler cannot process it. 496 (Error) Improper argument Cause. The argument has at least one wrong characteristic (such as type, class, category, or length). 497 (Error) Too many arguments Cause. More arguments have been supplied to the function than the function takes. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -88 Compiler Diagnostic Messages Message List 498 (Error) Argument not within expected range Cause. The literal being used as an argument to the function is outside the range allowed for that argument. 499 (Error) Too few arguments Cause. The function requires more arguments than have been supplied. 500 (Error) Expecting nonnumeric item Cause. A nonnumeric argument was supplied where a numeric argument is required. 501 (Error) This function is not allowed in old environment Cause. Functions appear in a program that does not run in the CRE. (To use functions, a program must run in the CRE.) 502 (Error) Expected alphabetic or alphanumeric data item Cause. A nonalphabetic, nonalphanumeric argument was supplied where an alphabetic or alphanumeric argument is required. 503 (Error) Expected alphabetic data item Cause. A nonalphabetic argument was supplied where an alphabetic argument is required. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -89 Compiler Diagnostic Messages Message List 504 (Error) Reference modifier permitted only for alphanumeric functions Cause. A reference modifier was applied to a function whose return type is not alphanumeric. 510 (Error) EXIT PERFORM [CYCLE] must be within an in-line perform Cause. An EXIT PERFORM or EXIT PERFORM CYCLE statement appears in a context other than within an inline PERFORM statement. 511 (Error) Expected key-word CYCLE or other verb Cause. The keyword PERFORM is followed by something other than the keyword CYCLE or another verb. 512 (Error) Expected key-word PARAGRAPH Cause. The keyword EXIT is followed by something other than the keyword PARAGRAPH. 513 (Error) An EXIT PARAGRAPH must be contained in a paragraph Cause. An EXIT PARAGRAPH statement is not inside a paragraph. (You must be within a paragraph to exit from one.) 514 (Error) An EXIT SECTION must be contained in a section Cause. An EXIT SECTION statement is not inside a section. (You must be within a section to exit from one.) HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -90 Compiler Diagnostic Messages Message List 515 (Error) Expected YYYYMMDD after DATE or YYYYDDD after DAY Cause. In the ACCEPT statement, either DATE appears followed by something other than YYYYMMDD or DAY appears followed by something other than YYYYDDD. 520 (Error) Possible odd byte address for parameter Cause. A data structure that could start on an odd byte was passed as a parameter to a CALL statement. If the data structure actually does start on an odd byte, the wrong address will be passed to the CALL statement. Certain subscript combinations cause this problem. 521 (Error) Parameter must be passed BY REFERENCE to a FORTRAN routine Cause. An ENTER statement tried to pass a parameter by value to a FORTRAN routine. This parameter must be passed by reference. 522 (Error) Parameter must be passed BY REFERENCE to a C function Cause. An ENTER statement tried to pass a parameter by value to an HP C function. This parameter must be passed by reference. 525 (Error) This directive is not permitted in the OSS environment Cause. The program was compiled in the OSS environment with one of these compiler directives: • • • • ENV NONSTOP SAVE SUBTYPE HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -91 Compiler Diagnostic Messages Message List 526 (Error) This phrase is not permitted for LINE SEQUENTIAL files Cause. The source program applies one of these phrases to a LINE SEQUENTIAL file: • • • • • • In a SELECT clause: ° ° ° ° ° ACCESS MODE IS DYNAMIC ACCESS MODE IS RANDOM ALTERNATE RECORD KEY PADDING CHARACTER RECORD DELIMITER In the I-O-CONTROL paragraph: ° MULTIPLE FILE In a file description entry: ° ° ° BLOCK CONTAINS CODE-SET LINAGE In an OPEN statement: ° ° ° ° I-O REVERSED SYNCDEPTH TIME LIMITS In a READ statement: ° ° ° PROMPT REVERSED TIME LIMITS ADVANCING in a WRITE statement 527 (Error) LINE SEQUENTIAL files may not be opened in I-O mode Cause. The program contains a statement of the form OPEN I-O i-o-file-description where i-o-file-description is a LINE SEQUENTIAL file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -92 Compiler Diagnostic Messages Message List 600 (Warning) Defunct directive ignored Cause. The NMCOBOL compiler ignores this directive. 601 (Warning) Feature not yet available -- directive ignored Cause. The NMCOBOL compiler ignores this directive. 602 (Error) No symbols for external name Cause. A CALL or ENTER statement calls a program for which the object file contains a name but not a symbol. (If a native HP COBOL program references an object in a CALL or ENTER statement, the object must have been compiled with symbols.) 603 (Error) External name not found Cause. The program called by a CALL or ENTER statement is not in the specified object file (if an object file is specified) or is not in any object file on the search list(s). 604 (Error) Error reading object file Cause. One of: • • A CALL or ENTER statement calls a program, specifying the object file that contains the program, but that object file cannot be read. A CALL or ENTER statement calls a program without specifying the object file that contains it, and one of the object files on the search list(s) cannot be read. 605 (Error) The NO prefix is not allowed on this directive Cause. The NMCOBOL compiler does not accept this directive, although it does accept its opposite (for example, the NMCOBOL compiler accepts CONSULT, SEARCH, and SQL, but not NOCONSULT, NOSEARCH, or NOSQL). HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -93 Compiler Diagnostic Messages Message List 606 (Warning) ACCESS MODE STANDARD is ignored for a non-parameter data item in the linkage section Cause. ACCESS MODE STANDARD is specified for a data item described in the Linkage Section, and the data item is not referenced in the USING phrase of the PROCEDURE DIVISION header. Delete the ACCESS MODE phrase. 607 (Error) Numeric hexadecimal literal exceeds 16 hex digits Cause. A hexadecimal literal has more than 64 bits (16 hexadecimal digits). 608 (Error) More than 255 corresponding pairs Cause. A statement with a CORRESPONDING phrase has more than 255 matching pairs. Simplify the data structures. 610 (Error) Pointer data item not permitted Cause. A data item described as USAGE POINTER is specified where it is not allowed. 611 (Error) Expected index or pointer data item Cause. A statement (for example, SET) expects either an index data item or a pointer data item as a sending or receiving operand. 612 (Error) Expected pointer data item Cause. A statement expects a pointer data item as a sending or receiving operand. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -94 Compiler Diagnostic Messages Other Products’ Error Messages 613 (Warning) Directives: directive-1;directive-2 Duplicate setting, previous setting ignored Cause. The compilation unit contains incompatible directives; for example, CALLSHARED and NON-SHARED. Other Products’ Error Messages Products that are merged with the compiler sometimes cause compile-time error messages when you run the compiled program. Examples of such products are: • • NMCGEN, the “back end” of the NMCOBOL compiler SCI, the SQL/MP compiler interface NMCGEN Example 47-3. NMCGEN Run-Time Error Message *** Error detected by as1 phase gp-relative segments together exceed 64k bytes in source program file 'file-name' at source line n Cause. The small data area is too large. The small data area is for relatively small items that are referenced frequently. Access to items in the small data area is twice as fast as access to other data items. Recovery. Compile your program with the LARGEDATA directive, specifying a number smaller than 64 (the default). SCI Example 47-4. SCI Run-Time Error Message *** Embedded SQL Fatal Error *** *** ERROR 11998 - Embedded SQL memory exceeded during parsing -report to HP. Problem on line nnn ** Failure 19 ** Server failure Cause. Too few pages of memory were allocated to the SQL compiler interface (SCI) for processing SQL/MP statements. Recovery. Compile your program with the directive SQL PAGES n, where n is between 385 and 1000. If this error still occurs, recompile the program with a larger value of n. HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -95 Compiler Diagnostic Messages HP COBOL Manual for TNS and TNS/R Programs —522555-006 47 -96 SCI 48 Run-Time Diagnostic Messages This section explains the run-time diagnostic messages that can be reported if an HP COBOL process encounters an error condition. Topics: • • • • • • • • • Sources of Run-Time Diagnostic Messages Where Messages Are Reported Standard Message Format—Non-CRE Environment Standard Message Format—CRE Input-Output Error Messages SORT Error Messages Guardian Abnormal Termination Messages How to Use the Message List Message List Sources of Run-Time Diagnostic Messages For TNS HP COBOL programs, the sources of run-time diagnostic messages are: • • The COBOL85 run-time library (if the COBOL85 process is running in the non-CRE environment) The CRE (if the COBOL85 process is running in the CRE) For TNS/R HP COBOL programs, run-time diagnostic messages are from the CRE. Where Messages Are Reported If an EXECUTION-LOG parameter is currently defined, run-time diagnostic messages are reported to the destination that the EXECUTION-LOG parameter specifies (see PARAM Command); otherwise, they are delivered to the home terminal of the process. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48- 1 Run-Time Diagnostic Messages Standard Message Format—Non-CRE Environment Standard Message Format—Non-CRE Environment In the non-CRE environment, the standard format of a run-time diagnostic message is: pn pn [ pn pn [ pn [ pn - *** COBOL85 Library Error nnn *** From prog-id + %pppppp prog-id + %pppppp ] ... message additional-message ] ... File COBOL-file-name, assigned-file-name: open-status ] [ ] surrounds optional material. pn is the process name or process ID of the process that caused the error report. nnn is the message number from the COBOL85 run-time library. prog-id + %pppppp is the specification of the code location of the error. prog-id is the name of the program (from the PROGRAM-ID paragraph) in which the error occurred. %pppppp is the octal offset within the code block. If a series of similar lines (without the word From ) follows, it is a traceback of one or more lines to show the CALL history, starting with the program in which the error occurred, then its caller, and so on back to the main program. message is the error message text. additional-message is any additional information about the problem, such as the name of the file that caused the error. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48- 2 Run-Time Diagnostic Messages Standard Message Format—Non-CRE Environment COBOL-file-name applies only to I-O errors and is the name of the file in error (the file-name in the SELECT clause). assigned-file-name is the file system name of the file assigned to COBOL-file-name. open-status is an open mode (INPUT, OUTPUT, I-O, EXTEND or CLOSED). Example 48-1. Standard Run-Time Diagnostic Message (Non-CRE Environment) \HQSYS4.02,038 \HQSYS4.02,038 \HQSYS4.02,038 \HQSYS4.02,038 \HQSYS4.02,038 \HQSYS4.02,038 \HQSYS4.02,038 ABENDED: 2,38 - *** COBOL85 Library Error 009 *** From BUDG3A.SUB2.SUB2A + %166 BUDG3A.SUB2 + %200 BUDG3A.SUB1 + %264 BUDG3A + %123 Subscript out of range $AUTRY.BUDGET87.BUD3A - 30 Sep 86 Element Value pn \HQSYS4.02,038 nnn 009 prog-id BUDG3A.SUB2.SUB2A offset %166 message Subscript out of range program-file-name $AUTRY.BUDGET87.BUD3A date-and-time 30 Sep 86 13:42 additional-message None 13:42 In Example 48-1, The process running on system \HQSYS4, on processor 2, as process 38, is not named. The second through fifth lines are a traceback. The second line reports that the error occurred at an offset of octal 166 in SUB2A, which is contained in SUB2, which is contained in BUDG3A. The call to SUB2A occurred in SUB2, at an offset of octal 200. The call to SUB2 occurred in SUB1, at an offset of octal 264. The call to SUB1 occurred in BUDG3A, at an offset of octal 123. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48- 3 Run-Time Diagnostic Messages Standard Message Format—Non-CRE Environment The last line (from the operating environment, not from COBOL85) reports that the process terminated abnormally. Note. In the non-CRE environment, if the executing program delivers a message of this form, the file containing the run-time diagnostic message texts is not available. Report this to the appropriate system support personnel. \SHEM.13,012 \SHEM.13,012 \SHEM.13,012 \SHEM.13,012 - *** COBOL85 Library Error 009 *** From TESTT + %75 $NOAH.ZARK.TWO - 29 Feb 88 14:19 *** ERROR [770] Message table $SYSTEM.SYSTEM.C8LIMEO cannot be used. File system error 11. ABENDED: 13,12 When the text “File does not contain messages for this product” appears instead of “Message table ...”, the file C8LIMEO does not contain the message text for the object. Usually, the reason is that the object has an old version of the run-time library bound into it, which resulted from the file C8LIB being in the same subvolume as the compiler. Either remove C8LIB and recompile the program or use the BIND utility to delete all of the code that starts with C8LIB^. Otherwise, contact support about getting a version of C8LIMEO that contains the messages for the object. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48- 4 Run-Time Diagnostic Messages Standard Message Format—CRE Standard Message Format—CRE In the CRE, the standard format of a run-time diagnostic message is: pn pn [ pn pn [ pn [ pn - *** Run-time Error nnn *** message File COBOL-file-name = assigned-file-name, open-status ] From prog-id + %pppppp, UC.00 prog-id + %pppppp ] ... additional-message ] ... [ ] surrounds optional material. pn is the process name or process ID of the process that caused the error report. nnn is the message number from the CRE. prog-id + %pppppp is the specification of the code location of the error. prog-id is the name of the program (from the PROGRAM-ID paragraph) in which the error occurred. %pppppp is the octal offset within the code block. If a series of similar lines (without the word From ) follows, it is a traceback of one or more lines to show the CALL history, starting with the program in which the error occurred, then its caller, and so on back to the main program. message is the error message text. additionalmessage is any additional information about the problem, such as the name of the file that caused the error. COBOL-filename applies only to I-O errors and is the name of the file in error (the file-name in the SELECT clause). assigned-filename is the file system name of the file assigned to COBOL-filename. open-status is an open mode (INPUT, OUTPUT, I-O, EXTEND or CLOSED). HP COBOL Manual for TNS and TNS/R Programs —522555-006 48- 5 Run-Time Diagnostic Messages Input-Output Error Messages Input-Output Error Messages An input-output error message refers to a COBOL file or to a device specified in an ACCEPT or DISPLAY statement. An input-output error message has additional messages that report: • • A Guardian error number A line identifying the file that caused the error Example 48-2. Input-Output Error Message (Non-CRE Environment) \BEANS.11,047 \BEANS.11,047 \BEANS.11,047 \BEANS.11,047 \BEANS.11,047 \BEANS.11,047 \BEANS.11,047 ABENDED: 11,47 *** COBOL85 Library Error 057 *** From MANE.BBB + %422 MANE.AAA + %254 MANE + %1234 $MURPHY.AUDITX3.PRIVATE - 30 Sep 86 15:48 OPEN operation failed with error 48 File BWORK=$WILLIS.AUDITX3.GRIP: CLOSED In Example 48-2, the line \BEANS.11,047 - OPEN operation failed with error 48 reports that the file could not be opened due to a Guardian error 48 (security violation). The next line, \BEANS.11,047 - File BWORK=$WILLIS.AUDITX3.GRIP: CLOSED identifies the file that caused the error. Its COBOL file name is BWORK, and its Guardian file name is $WILLIS.AUDITX3.GRIP. Example 48-3. Input-Output Error Message (CRE) \DRP12.$:0:622:163577460 \DRP12.$:0:622:163577460 \DRP12.$:0:622:163577460 \DRP12.$:0:622:163577460 \DRP12.$:0:622:163577460 \DRP12.$:0:622:163577460 \DRP12.$:0:622:163577460 \DRP12.$:0:622:163577460 - *** Run-time Error 181 *** OPEN operation failed with error 48 File BWORK = \DRP12.$DATA4.PTR.GRIP, closed From COBLIB_IO_ERROR_ + 0x660 (DLL zcobdll) COBLIB_OPEN_ + 0x5120 (DLL zcobdll) .BBB + 0x1C0 (UCr) .AAA + 0x90 (UCr) MANE + 0x130 (UCr) SORT Error Messages A SORT error message arises from a SORT, RELEASE, or RETURN statement. A SORT error message is followed by a SORT diagnostic line. For explanation of the SORT diagnostic line, see the FastSort Manual. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48- 6 Run-Time Diagnostic Messages Guardian Abnormal Termination Messages Guardian Abnormal Termination Messages A Guardian abnormal termination message results from circumstances that cause the Guardian environment to terminate the execution of a run unit. The operating environment delivers its own message—the Guardian abnormal termination message—after (or instead of) delivering a COBOL run-time diagnostic message. A Guardian abnormal termination message is more cryptic than a COBOL run-time diagnostic message. Here is a typical Guardian abnormal termination message in the non-CRE environment: INSPECT - SYMBOLIC DEBUGGER - T9673C00 - (10JUL89) COPYRIGHT TANDEM COMPUTERS INCORPORATED 1983, 1985-1989 INSPECT P=000102, E=000350 -TRAP 2- ( arithmetic overflow ) *175,09,028* PRODXXX #X + %77I _PRODXXX_ Here is a typical Guardian abnormal termination message in the CRE: ABENDED: 10,355 CPU time: 0:00:00.005 3: Premature process termination with fatal errors or diagnostics The run unit was operating in an environment with traps armed, and an arithmetic overflow occurred. The Guardian environment placed the job into the selected debugger. You can use the “#X + 77I” information to find out where in the source program the problem arose. The three most common causes of Guardian abnormal termination messages are: • • • Abend (abnormal termination) Arithmetic Overflow Stack Overflow These topics explain abnormal termination messages and describe what to do if they occur. Abend Abend is short for “abnormal end.” It follows any fatal error message that the run-time routines generate. If it appears without a run-time diagnostic message, you might want to execute the run unit again with the SAVEABEND attribute set so that the selected debugger makes a save file. You might also want to recompile with SYMBOLS and INSPECT directives, and then execute with SAVEABEND so that you can make easier use of the save file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48- 7 Run-Time Diagnostic Messages Arithmetic Overflow Arithmetic Overflow Arithmetic overflow means that an arithmetic operation resulted in an arithmetic overflow. Typical causes include: • • • • • Invalid data is associated with an item, such as an uninitialized USAGE COMPUTATIONAL or index item. A receiving item in an arithmetic statement is too small. An intermediate result in a COMPUTE statement exceeds the 36-digit maximum. A USAGE COMPUTATIONAL operand in an arithmetic statement contains a number larger than the number of digits specified in the PICTURE clause for that item. A subscript or a reference modifier is too big. You can determine the cause of arithmetic overflow in any of these ways: • Without the Debugger This method is recommended for production runs. If the program calls the COBOL85^ARMTRAP routine (in the non-CRE environment) or the PARAM INSPECT OFF command is active (in the CRE), the process stops executing with a trace-back to the highest-level program. The first item in the trace-back is the offset within the program of the statement that caused the problem. To find the statement itself, compile the program with the ICODE directive (for the COBOL85 compiler) or the INNERLIST directive (for the NMCOBOL compiler). Except for adding the ICODE or INNERLIST directive, compile the program with exactly the same directives as you did before the problem occurred. (Some directives, such as SYMBOLS, can slightly change the generated code.) • With the Debugger If the program does not call the COBOL85^ARMTRAP routine (in the non-CRE environment) or the PARAM INSPECT ON command is active (in the CRE), the process stops and enters the selected debugger (see Debugger Selection). You can use the debugger to find the problem. If the selected debugger is symbolic, using it is easier if you compiled the program with the SYMBOLS directive. If you did not, you might have to recompile the program with SYMBOLS to find the problem with the debugger. • With a Saveabend File If the program is compiled with the SAVEABEND directive, the process generates a saveabend file if it terminates abnormally. You can determine the cause of the problem by examining the saveabend file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48- 8 Run-Time Diagnostic Messages Stack Overflow Stack Overflow Stack overflow means that the control and data stack has overflowed. TNS Programs In a TNS program, the most common cause is a shortage of data space in the user data area. To determine whether this is the case, you need a data map of the run unit. For a TNS program, you can use the BIND command LIST LOC FROM fname to create a data map for file fname. Examine the data block map to find the last address less than 100000 octal. If this address is greater than 70000 octal, you might not have enough room to execute. There are several ways to fix the problem: • • • • Move one or more large data items (such as large tables) from the WorkingStorage Section to the Extended-Storage Section. Reduce arrays to fewer elements. Eliminate unused data items (a cross-reference listing might help you find them). Make seldom-called programs initial programs (specify INITIAL in the PROGRAMID paragraph). If there appears to be enough room, but your program still terminates abnormally, your run unit might have a loop in it. To determine the cause, compile the program with the SYMBOLS and INSPECT directives, and run it in debug mode (with the RUND command) by using the selected debugger to examine the contents of the variables when the program terminates abnormally. One likely cause of abnormal termination is a PERFORM loop that lacks proper termination. If, during the execution of a procedure, control passes out of the procedure and then control passes back through the PERFORM statement again, the stack space dedicated to maintenance of the procedure is never freed. Native Programs For native programs, the most likely cause of stack overflow is calling one or more initial programs that have large amounts of data declared in the Working-Storage Section or Extended-Storage Section. Data in initial programs is allocated on the stack, and the area of memory reserved for the stack is much smaller than the area reserved for static data. There are several ways to fix this problem: • • • Move one or more large data items (such as large tables) from the initial program to a noninitial program that calls it, and pass the data items as parameters. Reduce arrays to fewer elements. Eliminate unused data items. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48- 9 Run-Time Diagnostic Messages • How to Use the Message List Remove the INITIAL phrase from the program header and explicitly cancel the program after every call to it (see CANCEL). How to Use the Message List This topic lists and explains all the run-time diagnostic messages that can be reported for an HP COBOL program that either runs in the non-CRE environment or runs in the CRE but does not call any non-COBOL routines. If your HP COBOL program runs in the CRE and calls non-COBOL routines, errors in those routines can cause additional messages to be reported. For a complete list of CRE run-time diagnostic messages, see the CRE Programmer’s Guide. The messages in Message List are in numeric order by CRE message number. The corresponding COBOL message number is beneath the CRE message number, in parentheses. If you know only the COBOL message number, use Table 48-1 to find its corresponding CRE message number. If a COBOL message number has no corresponding CRE message, Table 48-1 shows “none.” Such messages are in numeric order by COBOL message number at the end of “Message List.” Some CRE error numbers correspond to multiple COBOL85 error message numbers (for example, CRE error 26 corresponds to COBOL85 errors 015 and 106). The reverse is true also (CRE errors 2 through 9 correspond to COBOL85 error 121). When corresponding CRE and COBOL messages have identical message texts, they are listed this way: CRE Number (COBOL85 Number) Message text Cause. Cause of the error. Effect. What the run-time routines did. For errors that do not involve input-output operations, the run-time routines usually just report the message and terminate the process. For input-output errors, the run-time routines: • • • • Report the message. Set the status code and the GUARDIAN-ERR special register. If the program contains a corresponding declarative section, perform the declarative. Either terminate execution or continue, depending upon the value of the status code. Recovery. Suggestions for recovering from the error or preventing its recurrence. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -10 Run-Time Diagnostic Messages How to Use the Message List When corresponding CRE and COBOL messages have different texts, they are listed this way: CRE Number CRE message text (COBOL85 Number) COBOL message text Cause. Cause of the error. Effect. What the run-time routines did. Recovery. Suggestions for recovering from the error or preventing its recurrence. Table 48-1. COBOL Message Mapping (page 1 of 5) Msg. No. Original CRE Original Message Text 001 125 OCCURS DEPENDING ON data item out of range 002 126 Extended address parameter passed where byte or 2-byte address expected 003 127 CALL references an active program 004 128 Reference modifier out of range 005 129 Improper context for RELEASE statement 006 130 Improper context for RETURN statement 007 131 S location at end of paragraph not equal to that at beginning 008 132 SORT or MERGE statement executed while SORT or MERGE active 009 133 Subscript out of range 010 134 GO TO statement not initialized 011 135 ACCEPT or DISPLAY requested for an unsupported device 012 17 Space allocation for ACCEPT or DISPLAY failed 013 136 Input-output error nnn on ACCEPT or DISPLAY device 014 25 File not uniquely identified in ASSIGN command 015 26 PARAM argument not recognized or not permitted 016 137 Called program not found 017 138 CANCEL references an active program 018 139 Cancelled program not found * Original COBOL message 121 maps into CRE messages numbers one through nine. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -11 Run-Time Diagnostic Messages How to Use the Message List Table 48-1. COBOL Message Mapping (page 2 of 5) Msg. No. Original CRE Original Message Text 019 142 RELEASE operation failed - SORTMERGE message follows 020 143 RETURN operation failed - SORTMERGE message follows 021 144 SORT or MERGE operation failed before end - SORTMERGE message follows 022 145 SORT or MERGE operation failed at start - SORTMERGE 023 29 Run unit not compatible with COBOL85 library 024 150 Alternate key not present in file 025 151 DUPLICATES specification in SELECT does not match file 026 152 OPEN on a non-disk file that is specified with alternate 027 153 Create of new file failed with error nnn 028 154 Sequential DELETE must follow successful READ 029 155 DELETE positioning failed with error nnn 030 156 DELETE repositioning failed with error nnn 031 157 Wrong open mode for DELETE 032 158 DELETE operation failed with error nnn 033 77 OPEN on an EDIT file and EDITREADINIT failed with code -n 034 159 OPEN on an EDIT file and wrong open mode 035 160 OPEN on an EDIT file described with a record size that is too big 036 161 OPEN EXTEND positioning failed with error nnn 037 162 OPEN on a nonexistent file that is not OPTIONAL 038 163 OPEN page eject failed with error nnn 039 164 OPEN rewind failed with error nnn 040 165 OPEN requested for an unsupported device other illegal device 041 166 OPEN requested for a locked file 042 167 OPEN requested for an open file 043 168 LINAGE file not on printer or process 044 169 LOCK or UNLOCK operation failed with error nnn 045 170 MULTIPLE FILE TAPE file not on tape 046 171 OPEN positioning for MULTIPLE FILE TAPE failed 047 172 OPEN on a nonexistent file and alternate keys specified 048 75 Buffer space allocation failed 049 173 Indexed file not defined as ORGANIZATION INDEXED 050 174 OPEN INPUT when file not on input device * Original COBOL message 121 maps into CRE messages numbers one through nine. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -12 Run-Time Diagnostic Messages How to Use the Message List Table 48-1. COBOL Message Mapping (page 3 of 5) Msg. No. Original CRE Original Message Text 051 175 Operation other than OPEN on file that is not open 052 176 File is not opened for timed I/O 053 177 OPEN OUTPUT when file not on output device 054 178 Relative file not defined as ORGANIZATION RELATIVE 055 179 Sequential file not defined as ORGANIZATION SEQUENTIAL 056 180 Non-disk or unstructured file and not sequential organization 057 181 OPEN operation failed with error nnn 058 182 Prime key offset in program does not match file 059 183 Prime key size in program does not match file 060 184 Purge of file during OPEN failed with error nnn 061 185 Purge data from file during OPEN failed with error nnn 062 78 EDITREAD failed with code -n 063 186 READ operation failed with error nnn 064 187 READ WITH LOCK on file with read ahead or an OSS file 065 188 READ positioning failed with error nnn 066 189 Sequential READ requested when current position is undefined 067 190 Wrong open mode for READ 068 191 Reel swap failed with error nnn 069 192 Sequential REWRITE must follow successful READ 070 193 REWRITE positioning failed with error nnn 071 194 REWRITE repositioning failed with error nnn 072 195 Wrong open mode for REWRITE 073 196 Sequential REWRITE permitted only with same record size 074 197 REWRITE operation failed with error nnn 075 none CLOSE LOCK while same file open elsewhere in run unit 076 198 START operation failed with error nnn 077 199 START positioning failed with error nnn 078 200 Wrong open mode for START 079 201 System node not available or does not exist 080 202 LOCKFILE, UNLOCKFILE or UNLOCKRECORD on file that is not open 081 203 OPEN on unstructured file described without fixed length records 082 204 Writing end of file failed with error nnn * Original COBOL message 121 maps into CRE messages numbers one through nine. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -13 Run-Time Diagnostic Messages How to Use the Message List Table 48-1. COBOL Message Mapping (page 4 of 5) Msg. No. Original CRE Original Message Text 083 205 Writing end of reel failed with error nnn 084 206 WRITE operation failed with error nnn 085 207 WRITE failed because file full 086 208 WRITE positioning failed with error nnn 087 209 WRITE repositioning failed with error nnn 088 210 Line skipping failed with error nnn 089 211 Wrong open mode for WRITE 090 212 Wrong length record specified for WRITE or REWRITE 091 none Descriptions for the same external file differ 092 213 OPEN EXTEND for file not on extend device 093 214 OPEN I-O for file not on input-output device 094 215 Wrong or missing LABELS attribute 095 216 Wrong or missing USE attribute 096 217 Wrong or missing RECFORM attribute 097 218 Wrong or missing RECLEN attribute 098 219 Wrong or missing BLOCKLEN attribute 099 220 Wrong or missing FILESEQ attribute 100 221 Wrong or missing DEVICE attribute 101 222 A DEFINE procedure failed with error nnn 102 223 DEFINE required for LABEL RECORDS STANDARD 103 none Blocking not permitted for odd length records 104 80 Spooler initialization failed with error nnn 105 none No space for PARAM EXECUTION-LOG file block 106 26 External file name in PARAM EXECUTION-LOG is invalid 107 none File referenced in PARAM EXECUTION-LOG is on an invalid device 108 140 Record referenced in RELEASE statement not in SD in SORT or MERGE statement 109 141 File referenced in RETURN statement not in SD in SORT or MERGE statement 110 79 OpenEdit failed with error nnn 111 224 PositionEdit failed with error nnn 112 225 Size of unstructured file opened EXTEND not multiple of record size * Original COBOL message 121 maps into CRE messages numbers one through nine. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -14 Run-Time Diagnostic Messages Message List Table 48-1. COBOL Message Mapping (page 5 of 5) Msg. No. Original CRE Original Message Text 113 226 File attributes don’t match and file not opened OUTPUT or has alternate keys 114 227 Loadclose failed with internal error mmm, GUARDIAN error nnn 115 228 Allocatesegment for fast i/o failed with error return nnn 116 229 Loadopen failed with internal error mmm, GUARDIAN error nnn 117 230 Loadwrite failed with internal error mmm, GUARDIAN error nnn 118 231 Initnewdatablock (Fast i-o) failed 119 232 An illegal operation was attempted on a fast i/o file 120 none The file name in PARAM PRINTER-CONTROL is not a legal COBOL file name 121 * A hardware/software trap occurred—the type follows 122 233 OPEN OUTPUT SHARED and other process has disk open 123 75 Buffer allocation failed on SORT or MERGE 124 234 The CLOSE operation failed with Guardian error nnn 125 none A CRE routine was called from a non-CRE program 126 235 REVERSED not allowed for this file 127 146 Parameter mismatch for CALL identifier 128 none PARAM WAITED-IO ON specified and illegal OPEN attempted 129 83 Operation incompatible with file type or status (GE) 130 40 Invalid function parameter 131 11 or 13 Corrupted environment * Original COBOL message 121 maps into CRE messages numbers one through nine. Message List The run-time diagnostic messages associated with COBOL85, in numeric order by CRE message number, are: 1 (none) Unknown trap Cause. The CRE trap processing function was called with an unknown trap number. Effect. The run unit terminates abnormally. Recovery. Check the program’s logic. Use the selected debugger to help isolate the problem or consult your system administrator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -15 Run-Time Diagnostic Messages Message List 2 Illegal address reference (121) A hardware/software trap occurred - the type follows Illegal address reference Cause. An address was specified that was not within either the virtual code area or the virtual data area allocated to the process. In most cases, a subscript or reference modifier was out of bounds. Effect. The run unit terminates abnormally. Recovery. Try recompiling with the CHECK 3 directive. 3 Instruction failure (121) A hardware/software trap occurred - the type follows Instruction failure Cause. An attempt was made to: • • • Execute a code word that is not an instruction Execute a privileged instruction by a nonprivileged process Reference an illegal extended address In most cases, a compiler error or a subscript or reference modifier was out of bounds. Effect. The run unit terminates abnormally. Recovery. Try recompiling with the CHECK 3 directive. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -16 Run-Time Diagnostic Messages Message List 4 Arithmetic fault (121) A hardware/software trap occurred - the type follows Arithmetic fault Cause. For a TNS program, the overflow bit in the environment-register, ENV.<10>, was set to 1; for a native program, an arithmetic overflow occurred. This occurred for one of these reasons: • • The result of a signed arithmetic operation could not be represented with the number of bits available for the particular data type. A division operation was attempted with a zero divisor. In most cases, a receiving item in an arithmetic statement is too small. Effect. The run unit terminates abnormally. Recovery. Check the statement in your program at the address given by offset and correct it. Also, see Arithmetic Overflow for alternative ways to handle this problem. 5 Stack overflow (121) A hardware/software trap occurred - the type follows Stack overflow Cause. A stack overflow fault occurs if: • • An attempt was made to execute a program whose dynamically allocated data did not fit within the remaining area available for the stack. There was not enough remaining virtual data space for an operating environment procedure to execute. For a TNS program, the amount of virtual data space available is G[0] through G[32767]. Operating environment procedures require approximately 700 bytes of user-data stack space to execute. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -17 Run-Time Diagnostic Messages Message List Effect. The run unit terminates abnormally. Recovery. See Stack Overflow for an explanation of this condition and recovery information. 6 Process loop-timer timeout (121) A hardware/software trap occurred - the type follows Process loop-timer timeout Cause. The new time limit specified in the latest call to SETLOOPTIMER has expired. Effect. The run unit terminates abnormally. Recovery. Report this error to your service provider. 7 Memory manager read error (121) A hardware/software trap occurred - the type follows Memory manager read error Cause. An unrecoverable, read error occurred while the program was trying to bring in a page from virtual memory. Effect. The run unit terminates abnormally. Recovery. Report this error to your service provider. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -18 Run-Time Diagnostic Messages Message List 8 Not enough physical memory (121) A hardware/software trap occurred - the type follows Not enough physical memory Cause. This fault occurs for one of these reasons: • • A page fault occurred, but there were no physical memory pages available for overlay. Disk space could not be allocated while the program is using extensible segments. Effect. The run unit terminates abnormally. Recovery. Report this error to your service provider. 9 Uncorrectable memory error (121) A hardware/software trap occurred - the type follows Uncorrectable memory error Cause. An uncorrectable memory error occurred. Effect. The run unit terminates abnormally. Recovery. Report this error to your service provider. 11 (131) Corrupted environment Cause. CRE or COBOL85 run-time library data is invalid. Effect. The CRE or non-CRE environment calls PROCESS_STOP_, specifying the ABEND variant and the text “Corrupted environment.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -19 Run-Time Diagnostic Messages Message List Recovery. • COBOL85 compiler In the CRE, the program might have written data in the upper 64 KB of the user data segment. The upper 64 KB are reserved for CRE and run-time library data. Check the program’s logic. Use the selected debugger to help isolate the problem or consult your system administrator. In the non-CRE environment, one of these things might have happened: ° ° ° The pointer at location G[0] is not %100000. The value of the 2 bytes at %100000 is not %76. The value of the 2 bytes at %100027 is not zero. To correct the problem, initialize uninitialized pointers. • NMCOBOL compiler The MCB is not at a fixed location. To find it, use the noft command EXTSYMTBL. Then use the selected debugger to help isolate the problem. See Example 48-4. 12 (none) Logic error Cause. The CRE or run-time library detected a logic error within its own domain. For example, although each data item it is using is valid, the values of the data items are mutually inconsistent. Effect. The CRE calls PROCESS_STOP_, specifying the ABEND variant and the text “Logic error.” Recovery. The program might have written data in the upper 64 KB of the user data segment. The upper 64 KB are reserved for CRE and run-time library data. Check the program’s logic. Use the selected debugger to help isolate the problem or consult your system administrator. 13 (131) MCB pointer corrupt Cause. The pointer at location G[0] of the program’s user data segment (for TNS programs) or symbolic location _MCB (for native programs) to its primary data structure—the Master Control Block (MCB)—does not point to the MCB. Both the CRE and run-time libraries can report this error. Effect. The CRE attempts to restore the MCB pointer and to write a message to the standard log file; however, because its environment might be corrupted, the CRE might not be able to log a message. In that case, it calls PROCESS_STOP_, specifying the ABEND variant and the text “Corrupted Environment.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -20 Run-Time Diagnostic Messages Message List Recovery. If the program was compiled with the COBOL85 compiler, check the program’s logic to see if it overwrote the MCB pointer at G[0]. Use the selected debugger to help isolate the problem. If the program was compiled with the NMCOBOL compiler: In a native object, the MCB is not at a fixed location. To find it, use the noft command EXTSYMTBL. Then use the selected debugger to help isolate the problem. The noft output can be very lengthy. Example 48-4 shows the location of the MCB for the native object file DOMS1400 is 0x0800e3e0. Example 48-4. Using noft to Find the MCB Pointer in a Native Object File noft> FILE DOMS1400noft> EXTSYMTBL .... 4 0 _MCB 0x0800e3e0 Glob ....noft> 14 (none) Premature takeover Cause. The backup process received a Guardian message that it had become the primary process, but it had not yet received all of its initial checkpoint information from its predecessor primary process. Effect. The CRE calls PROCESS_STOP_, specifying the ABEND variant and the text “Premature takeover.” Recovery. If the takeover occurred because of faulty program logic, correct the program’s logic. If the takeover occurred for other reasons, such as a hardware failure, you might want to rerun the program, provided that doing so will not duplicate operations already performed, such as updating a database a second time. 15 (none) Checkpoint list inconsistent Cause. A list of checkpoint item descriptors that a run-time library or CRE maintains for fault-tolerant processes was invalid. Effect. The run unit terminates abnormally. Recovery. The list of items to checkpoint is maintained in the program’s address space. Check the program’s logic. The program might have overwritten the checkpoint list. Use the selected debugger to help isolate the problem. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -21 Run-Time Diagnostic Messages Message List 16 (none) Checkpoint list exhausted Cause. The CRE did not have enough room to store all of the checkpoint information required by the program. Effect. The run unit terminates abnormally unless the error occurred in an SMU routine. Recovery. If the error occurred in an SMU routine, increase the size of the checkpoint list. 17 Cannot obtain control space (012) Space allocation for ACCEPT or DISPLAY failed Cause. The CRE or a run-time library could not obtain space for all of its data. If the offending statement is an ACCEPT or DISPLAY statement, its buffer could not be allocated due to a lack of allocatable space. Effect. The run unit terminates abnormally. Recovery. Increase the available space. The program should close files as soon as it is done using them. If a TNS program does not close files as soon as it is done using them, you can rebind or relink the object file and use the DATA PAGES option in the BUILD command to get more space, or use the MEM parameter of the RUN command to increase the available space. 20 (none) Cannot utilize file name Cause. A string, expected to be a valid file name, could not be interpreted as a Guardian external file name. Effect. The run unit terminates abnormally. Recovery. Check that the file names in the program are valid Guardian file names. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -22 Run-Time Diagnostic Messages Message List 21 (none) Cannot read initialization messages ( error ) Cause. During program initialization, the CRE could not read all of the messages (start-up message, PARAM message, ASSIGN messages, and so forth) it expected from the file system. error is the file system error number the CRE received when it could not read an initialization message. Effect. The run unit terminates abnormally. Recovery. Consult your system administrator. 22 (none) Cannot obtain executable file name Cause. The CRE could not obtain the name of the loadfile from the Guardian environment. Effect. The run unit terminates abnormally. Recovery. Consult your system administrator. 23 (none) Cannot determine file name ( error ) program_name.logical_name Cause. The CRE could not determine the physical file name associated with program_name.logical_name. Effect. The run unit terminates abnormally. Recovery. Correct the program_name.logical_name and rerun your program. For information on ASSIGN commands, see ASSIGN Command and the TACL Reference Manual. 24 (none) Conflict in application of ASSIGN program_name.logical_name Cause. ASSIGN values in your TACL environment conflict with each other. For example: ASSIGN A, $B1.C.D ASSIGN *.A, $B2.C.D HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -23 Run-Time Diagnostic Messages Message List The first ASSIGN specifies that the logical name A can appear in no more than one loadfile. The second assign specifies that the name A can appear in an arbitrary number of loadfiles. The CRE cannot determine whether to use the file C.D on volume $B1 or on volume $B2. Effect. The run unit terminates abnormally. Recovery. Correct the ASSIGNs in your TACL environment. For information on ASSIGN commands, see ASSIGN Command and the TACL Reference Manual. 25 Ambiguity in application of ASSIGN logical_name (014) File not uniquely identified in ASSIGN command Cause. An unqualified file name (one without the program-name or the asterisk (*) prefix) specified by an active ASSIGN command corresponds to more than one COBOL file in the run unit. Effect. The run unit terminates abnormally. Recovery. Either qualify the file name or change the program to prevent duplicated names. 26 Invalid PARAM value text ( error ) PARAM name 'value' (015) PARAM argument not recognized or not permitted (106) External file name in PARAM EXECUTION-LOG is invalid Cause. A PARAM specifies a value that is not defined by the CRE. For example, the value for a DEBUG PARAM must be either ON or OFF. The CRE reports this error if a DEBUG PARAM has a value other than ON or OFF. error, if present, is a Guardian file system error. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -24 Run-Time Diagnostic Messages Message List Effect. The run unit terminates abnormally. Recovery. Modify the PARAM text and rerun your program. For more information on using PARAMs, see PARAM Command and the TACL Reference Manual. 27 (none) Ambiguity in application of PARAM PARAM name 'value' Cause. A PARAM specifies a value that is ambiguous in the current context. For example, the PARAM specification: PARAM PRINTER-CONTROL A is ambiguous if the program contains more than one logical file named A. Effect. The run unit terminates abnormally. Recovery. Correct the PARAM in your TACL environment. See the TACL Reference Manual for more information on using PARAMs. 28 (none) Missing language run-time library -- language Cause. The run-time library for a module that is written in language is not available to the program. Effect. The run unit terminates abnormally. Recovery. Consult your system administrator. 29 Program incompatible with run-time library -- COBOL85 (023) Run unit not compatible with COBOL85 library Cause. The run unit was compiled by a version of HP COBOL that is not compatible with this version of the COBOL85 run-time library. Effect. The run unit terminates abnormally. Recovery. Recompile the main program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -25 Run-Time Diagnostic Messages Message List 40 (130) Invalid function parameter Cause. A function detected a problem with its parameters. Effect. Program behavior depends on the function that was called. Recovery. Correct the parameter you are passing. 41 (none) Range fault Cause. An arithmetic overflow or underflow occurred while evaluating an arithmetic function. Effect. Program behavior is language and application dependent. An HP COBOL program cannot cause this error, so the problem must be in a non-COBOL program in the same run unit. Recovery. Modify the program to pass values to the arithmetic functions that do not cause overflow. 42 (none) Arccos domain fault Cause. The parameter passed to the ACOS function was not in the range -1 to +1. Effect. Program behavior is language and application dependent. Recovery. Modify the program to pass a valid value to the ACOS function. 43 (none) Arcsin domain fault Cause. The parameter passed to the ASIN function was not in the range -1 to +1. Effect. Program behavior is language and application dependent. Recovery. Modify the program to pass a valid value to the ASIN function. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -26 Run-Time Diagnostic Messages Message List 44 (none) Arctan domain fault Cause. Both of the parameters to an ATAN function were zero. At least one of the parameters must be nonzero. Effect. Program behavior is language and application dependent. Recovery. Modify the program to pass the correct value to the ATAN function. 46 (none) Logarithm function domain fault Cause. The parameter passed to a logarithm function (LOG or LOG10) was less than or equal to zero. The parameter to a logarithm function must be greater than zero. Effect. Program behavior is language and application dependent. Recovery. Modify the program to pass a valid value to the logarithm function. 47 (none) Modulo function domain fault Cause. The value of the second parameter to the MOD function was zero. The second parameter to the MOD function must be nonzero. Effect. Program behavior is language and application dependent. Recovery. Modify the program to pass a nonzero value to the MOD function. 48 (none) Exponentiation domain fault Cause. Parameters to the exponentiation operator were not acceptable. Given the expression x ** y these parameter combinations produce this message: x = 0 and y is not 0 x < 0 and y is not an integral value Effect. Program behavior is language and application dependent. Recovery. Modify the program to pass values that do not violate the above combinations. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -27 Run-Time Diagnostic Messages Message List 49 (none) Square root domain fault Cause. The parameter to the SQRT function was a negative number. The parameter must be greater than or equal to zero. Effect. Program behavior is language and application dependent. Recovery. Modify the program to pass a nonnegative value to the SQRT function. 55 (none) Missing or invalid parameter Cause. A required parameter is missing or too many parameters were passed. Effect. Program behavior depends on the function that was called. Recovery. Correct the program to pass a valid parameter. 56 (none) Invalid parameter value Cause. The value passed as a procedure parameter was invalid. Effect. Program behavior depends on the function that was called. Recovery. Correct the program to pass a valid parameter value. 57 (none) Parameter value not accepted Cause. The value passed as a procedure parameter is not acceptable in the context in which it is passed. For example, the number of bytes in a write request is greater than the number of bytes per record in the file. Effect. Program behavior depends on the function that was called. Recovery. Correct the program to pass a valid parameter. 59 (none) Standard input file error ( error ) Cause. The Guardian file system reported an error when a routine tried to access the standard input file. error is a Guardian file system error code. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -28 Run-Time Diagnostic Messages Message List Effect. The CRE can report this error when it closes your input file. All other instances are language and application dependent. An HP COBOL program terminates abnormally. Recovery. If the error was caused by a read request from your program, correct your program. You might need to verify that your program handles conditions that are beyond your control, such as losing a path to the device. Also refer to error handling in this manual and in the language manual for the routine in your program that detected the error. If the error was caused by a read request from the CRE, consult your system administrator. 60 (none) Standard output file error ( error ) Cause. The Guardian file system reported an error when the CRE called a file system procedure to access standard output. error is the Guardian file system error. Effect. The CRE can report this error when it closes your output file. All other instances are language and application dependent. An HP COBOL program terminates abnormally. Recovery. If the error was caused by a write request from your program, correct your program. You might need to verify that your program handles conditions that are beyond your control such as losing a path to the device. Also refer to error handling in this manual and in the language manual for the routine in your program that detected the error. If the error was caused by a write request from the CRE, consult your system administrator. 61 (none) Standard log file error ( error ) Cause. The Guardian file system reported an error when the CRE called a file system procedure to access the standard log file. error is the Guardian file system error. Effect. The CRE terminates your program. Recovery. Consult your system administrator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -29 Run-Time Diagnostic Messages Message List 62 (none) Invalid GUARDIAN file number Cause. A value that is expected to be a Guardian file number is not the number of an open file. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Consult your system administrator. 63 (none) Undefined shared file Cause. A parameter was not the number of a shared file where one was expected. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Consult your system administrator. 64 (none) File not open Cause. A request to open a file failed because the file device is not supported. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Consult your system administrator. 65 (none) Invalid attribute value Cause. A parameter to an open operation was not a meaningful value. For example, the CRE_File_Open sync_receive_depth parameter must be a nonnegative number. This message might be reported if the sync_receive_depth parameter is negative. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Consult your system administrator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -30 Run-Time Diagnostic Messages Message List 66 (none) Unsupported file device Cause. The CRE received a request to access a device that it does not support. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Consult your system administrator. 67 (none) Access mode not accepted Cause. The value of access to an open operation was not valid in the context in which it was used. For example, it is invalid to open a spool file for input. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Consult your system administrator. 68 (none) Nowait value not accepted Cause. The value of no_wait to an open operation was not valid in the context in which it was used. For example, it is invalid to specify a nonzero value for no_wait for a device that does not support nowait operations. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Consult your system administrator. 69 (none) Syncdepth not accepted Cause. The value of the sync_receive_depth parameter to an open operation was not valid in the context in which it was used. For example, it is not valid to specify a sync_receive_depth greater than one for a shared file. Effect. Program behavior is language and application dependent. An HP COBOL5 program terminates abnormally. Recovery. Consult your system administrator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -31 Run-Time Diagnostic Messages Message List 70 (none) Options not accepted Cause. The value of an open operation options parameter was not valid in the context in which it was used. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Consult your system administrator. 71 (none) Inconsistent attribute value Cause. A routine requested a connection to a shared file that was already open, and the attributes of the new open request conflict with the attributes specified when the file was first opened. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. If your program supplied the attribute values, correct and rerun your program; otherwise, consult your system administrator. 75 Cannot obtain buffer space (048) Buffer space allocation failed Cause. An attempt to allocate buffer space failed. The possible reasons are: • • • • COBOL_SPECIAL_OPEN_, COBOL85^SPECIAL^OPEN, or COBOLSPOOLOPEN attempted to get space for level 3 spooling or for at least one record. An OPEN of a file assigned to $RECEIVE attempted to get space for various tables. An OPEN of an EDIT file attempted to get space to process the file. An OPEN of other files attempted to get space for ADVANCING processing. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -32 Run-Time Diagnostic Messages Message List Effect. The OPEN statement is unsuccessful with I-O status code “91.” The COBOL_SPECIAL_OPEN_, COBOL85^SPECIAL^OPEN, or COBOLSPOOLOPEN call is unsuccessful with I-O status code “30.” Recovery. The program should close files as soon as it is done using them. If a TNS program does not close files as soon as it is done using them, you can rebind or relink the object file and use the DATA PAGES option in the BUILD command to get more space, or use the MEM parameter of the RUN command to increase the available space. (123) Buffer n allocation failed on SORT or MERGE Cause. There was not enough buffer space to allocate buffer n for a SORT or MERGE statement that was sending records to FastSort or getting records from FastSort (as when an input or output procedure is specified). If n is 1, it was the normal buffer that could not be allocated; if n is 2, it was the second buffer. The second buffer is specified by the SECOND-BUFFER parameter of the COBOL85^SET^SORT^PARAM^VALUE or COBOL85_SET_SORT_PARAM_VALUE_ routine. Effect. The SORT or MERGE continues, but probably at a much slower pace. Recovery. Specify the MEM parameter on the RUN (or RUND) command; for example: RUN RUNUNIT/MEM 64/ 76 (none) Invalid external file name ( error ) Cause. A value that was expected to be a Guardian external file name is not in the correct format. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. If you supplied an invalid file name, correct the file name and rerun your program. Otherwise, consult your system administrator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -33 Run-Time Diagnostic Messages Message List 77 EDITREADINIT failed ( error ) (033) OPEN on an EDIT file and EDITREADINIT failed with code -n Cause. A call to EDITREADINIT failed. In CRE message 77, error, if present, gives the reason for the failure. Possible values of error are: Error Code Error Name -1 End-of-file marker encountered -2 I-O error -3 Text file format error -6 Invalid buffer address In COBOL message 033, the program attempted to open an EDIT file, and the call to EDITREADINIT failed. The returned code is -n. Effect. The OPEN statement is unsuccessful with I-O status code “91.” Recovery. If the code is -2, there was an input-output error; try the statement again. If the code is -3, the file is not an EDIT file. Assign the correct file. If the code is -4 there is a sequence number error. Use EDIT, TEDIT, or Codewright to correct the file. 78 EDITREAD failed ( error ) (062) EDITREAD failed with code -n Cause. A call to EDITREAD failed. In CRE message 78, error, if present, gives the reason for the failure. Possible values of error are: Error Code Error Name -1 End-of-file marker encountered -2 I-O error -3 Text file format error -4 Sequence number error -5 Checksum error -6 Invalid buffer address HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -34 Run-Time Diagnostic Messages Message List In COBOL message 062, the program attempted to read an EDIT file, and the call to EDITREAD failed. The returned code is -n. Effect. The OPEN statement is unsuccessful with I-O status code “91.” Recovery. If the code is -2, there was an input-output error; try the statement again. If the code is -3, there is a text file format error. Re-create the file. If the code is -4, there is a sequence number error. Use EDIT, TEDIT, or Codewright to correct the file. If the code is -5, there is a checksum error. Re-create the file. 79 OpenEdit failed ( error ) (110) OpenEdit failed with error nnn Cause. The call to OpenEdit made during the OPEN processing for an EDIT file failed with Guardian error or nnn. A negative number is a format error. A positive number is a Guardian file system error. Effect. The OPEN statement is unsuccessful with I-O status code “30”. Recovery. Use the command interpreter ERROR command to discover the meaning of the Guardian error number. The message might suggest a corrective action. 80 Spooler initialization failed ( error ) (104) Spooler initialization failed with error nnn Cause. A Guardian error or nnn was returned during the initialization of a spooler file during a special OPEN operation. Effect. The ENTER “COBOL85^SPECIAL^OPEN” or ENTER "COBOL85_SPECIAL_OPEN_" is unsuccessful with I-O status code “30.” Recovery. You can use the command interpreter ERROR command to discover the meaning of the Guardian error number. The message might suggest a corrective action. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -35 Run-Time Diagnostic Messages Message List 81 (none) End of file Cause. A routine detected an end-of-file condition. Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Correct your program to allow for an end-of-file condition or verify that your program can determine when all of the data has been read. 82 (none) Guardian I/O error nnn Cause. A Guardian operating system routine returned error nnn. This error is usually reported as a result of an event that is beyond program control (when a path or system is not available, for example). Effect. Program behavior is language and application dependent. An HP COBOL program terminates abnormally. Recovery. Consult your system administrator. 83 (129) Operation incompatible with file type or status (GE) Cause. One of: 1. COBOL_CONTROL_ or COBOL_SETMODE_ was called, and one of these was true: a. The associated file was assigned to $RECEIVE. b. HP COBOL Fast I-O was selected for the associated file. c. The CONTROL or SETMODE call was rejected by the file system (“(GE)” shows the error code). 2. An OSS file (probably described with ORGANIZATION IS LINE SEQUENTIAL) was opened in a Guardian process. Effect. The run unit terminates abnormally. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -36 Run-Time Diagnostic Messages Message List Recovery. One of these, depending on the cause number: 1. Either delete the call to COBOL_CONTROL_ or COBOL_SETMODE_ or correct it (depending on the cause): a. Change the file to a file other than $RECEIVE. b. Change the RESERVE clause so that it does not use HP COBOL Fast I-O. c. Take the action indicated by the Guardian error code “(GE).” 2. Correct the ASSIGN in the select clause or change LINE SEQUENTIAL to SEQUENTIAL. 124 (none) System not licensed for COBOL programs Cause. An NMCOBOL object is being run on a system that does not contain the runtime library. Instead, a “stub” is installed and it produces the diagnostic. Effect. The run unit terminates abnormally. Recovery. Ensure that either T8107 or T8108 is licensed to the system and installed correctly. 125 (001) OCCURS DEPENDING ON data item out of range Cause. The data item referenced in an OCCURS DEPENDING clause is either less than the minimum or greater than the maximum number of occurrences. Effect. The run unit terminates abnormally. Recovery. Either change the maximum or minimum number of occurrences in the OCCURS clause or correct the program so that the DEPENDING data item has a legal value. 126 (002) Extended address parameter passed where byte or word address expected Cause. A parameter is being passed in an ENTER statement to a routine that expects a byte-addressed or 2-byte-addressed reference parameter; however, the parameter is located in extended storage and cannot be passed this way. A parameter specified in the Linkage Section is always referred to through an extended address, even if it is described with the ACCESS MODE STANDARD clause (the compiler ignores this clause). Effect. The run unit terminates abnormally. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -37 Run-Time Diagnostic Messages Message List Recovery. Copy the value from the Linkage Section data item to a data item in the Working-Storage Section, and use the new data-name as the parameter in the ENTER statement. 127 (003) CALL references an active program Cause. A CALL statement is recursive—it references a program that has been called but has not executed an EXIT PROGRAM statement. Effect. The run unit terminates abnormally. Recovery. Correct the program. 128 (004) Reference modifier out of range Cause. Either the leftmost character position is out of range (negative, zero, or greater than the number of characters in the data item), or the length is improper (negative, zero, or greater than the sum of leftmost character position minus the original item size plus 1). Effect. The run unit is terminated abnormally. Recovery. Correct the program. 129 (005) Improper context for RELEASE statement Cause. A RELEASE statement was executed when a SORT input procedure was not executing. Effect. The run unit is terminated abnormally. Recovery. Correct the program. 130 (006) Improper context for RETURN statement Cause. A RETURN statement was executed when a SORT or MERGE output procedure was not executing. Effect. The run unit is terminated abnormally. Recovery. Correct the program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -38 Run-Time Diagnostic Messages Message List 131 (007) S location at end of paragraph not equal to that at beginning Cause. This message should never occur, because it indicates a compiler problem. It signals that some code generated in the preceding paragraph changed the S register setting and did not reset it. Effect. The run unit terminates abnormally. Recovery. Report it to your service provider. 132 (008) SORT or MERGE statement executed while SORT or MERGE active Cause. A SORT or MERGE statement was executed while a SORT or MERGE input or output procedure was being executed. Effect. The run unit terminates abnormally. Recovery. Correct the program. 133 (009) Subscript out of range Cause. A subscript is zero, negative, or exceeds the maximum number of occurrences allowed for the data item. Effect. The run unit terminates abnormally. Recovery. Correct the program. 134 (010) GO TO statement not initialized Cause. The program attempted to execute a paragraph consisting solely of a GO TO statement that does not specify a procedure name, but no ALTER statement had as yet been executed to establish the procedure name. Effect. The run unit terminates abnormally. Recovery. Correct the program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -39 Run-Time Diagnostic Messages Message List 135 (011) ACCEPT or DISPLAY requested for an unsupported device Cause. The device associated with the mnemonic-name specified in an ACCEPT statement is not a process or a terminal; or the device associated with the mnemonicname specified in a DISPLAY statement is not a process, terminal, operator console, printer, or existing disk file. Effect. The home terminal or the device specified as the EXECUTION-LOG is used instead. If the home terminal or the device specified as the EXECUTION-LOG cannot be used, the run unit terminates abnormally. Recovery. Change the program to assign a proper device. Use low-level debugging to trap changes to zero (see the Inspect Manual). 136 (013) Input-output error nnn on ACCEPT or DISPLAY device Cause. A file system error with a Guardian error code of nnn occurred while the process was accepting or displaying data. Effect. For an ACCEPT statement, the run-time library returns spaces for a nonnumeric destination or zeros for a numeric destination, and execution continues. For a DISPLAY statement, the requested data is not displayed, and execution continues. Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 137 (016) Called program not found Cause. The program referenced in a CALL statement with identifier specified could not be located. It must be present in the run unit or in the TNS or user library, and must be within the scope of the CALL statement. Effect. If the OVERFLOW or EXCEPTION clause is specified in the CALL statement, that path is taken. If not, the run unit is terminated abnormally. Recovery. If the program is not bound or linked into the run unit, and it should be, use BIND or a linker to be bind or link it in with the other programs. If the value of the data item is incorrect or the program being called is not within the scope of the called program, correct the program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -40 Run-Time Diagnostic Messages Message List 138 (017) CANCEL references an active program Cause. The program referenced in a CANCEL statement has been called but has not executed an EXIT PROGRAM (it is still active). Effect. The run unit terminates abnormally. Recovery. Correct the program. Reduce the number of files that are open simultaneously. 139 (018) Cancelled program not found Cause. The program referenced in a CANCEL statement with identifier specified could not be located. It must be present in the run unit or in the TNS or user library, and must be within the scope of the CANCEL statement. Effect. The run unit continues. Recovery. Correct the program. Reduce the number of files that are open simultaneously. 140 (108) Record referenced in RELEASE statement not in SD of SORT or MERGE statement Cause. The record-name referenced in a RELEASE statement is not associated with the file name that was referenced in the currently active SORT or MERGE statement. Effect. The run unit terminates abnormally. Recovery. Correct the source program logic. 141 (109) File referenced in RETURN statement not in SD of SORT or MERGE statement Cause. The file name referenced in a RETURN statement is not the file name that was referenced in the currently active SORT or MERGE statement. Effect. The run unit terminates abnormally. Recovery. Correct the source program logic. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -41 Run-Time Diagnostic Messages Message List 142 (019) RELEASE operation failed - SORTMERGE message follows Cause. During the execution of a RELEASE statement in a SORT input procedure, the FastSort utility returned an error. The message from FastSort follows on the next line. Effect. The run unit terminates abnormally. Recovery. Action depends on the message FastSort returns. See the FastSort Manual for the meaning of these messages. 143 (020) RETURN operation failed - SORTMERGE message follows Cause. During the execution of a RETURN statement in a SORT or MERGE output procedure, the FastSort utility returned an error. The message from FastSort follows on the next line. Effect. The run unit terminates abnormally. Recovery. Action depends on the message FastSort returns. See the FastSort Manual for the meaning of these messages. 144 (021) SORT or MERGE operation failed before end - SORTMERGE message follows Cause. At the end of the execution of a SORT or MERGE operation, the FastSort utility returned an error. The message from FastSort follows on the next line. Effect. The run unit terminates abnormally. Recovery. Action depends on the message FastSort returns. See the FastSort Manual for the meaning of these messages. 145 (022) SORT or MERGE operation failed at start - SORTMERGE message follows Cause. At the start of the execution of a SORT or MERGE operation, the FastSort utility returned an error. The second line of the message is the text of the SORT error message returned by the FASTSORT procedure SORTERRORSUM. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -42 Run-Time Diagnostic Messages Message List The third line is Sort error code = mm - System error code = nn where mm is the SORT error code defined in the FastSort Manual, and.nn is the highorder 2 bytes of the error code return defined for SORTERRORSUM. If the sort was a subsort, this text is appended to the message: - Subsort index = oo, CPU,id = pp,qq where oo is the subsort-index defined in the FastSort Manual under SORTERRORSUM, and pp,qq is the subsort-id defined in the FastSort Manual under SORTERRORSUM. For some errors, one or more of these lines appear: Error Error Error Error Error Error on on on on on in following USING file file-name following GIVING file file-name following scratch file file-name the internal scratch file the internal free list file interprocess communication where file-name is the name of the file where the error occurred. For “Error on following scratch file,” file-name is the one in the SELECT for the sort-merge file description. Effect. The run unit terminates abnormally. Recovery. Action depends on the message FastSort returns. See the FastSort Manual for the meaning of these messages. 147 (126) Parameter mismatch for CALL identifier Cause. The number of parameters in the USING list of a CALL identifier statement does not match the number of parameters specified in the called program’s USING list in the Procedure Division. Effect. The run unit terminates abnormally. Recovery. Correct the USING list in either the CALL statement or Procedure Division. 148 PERFORM nesting too deep Cause. The NMCOBOL PERFORM stack overflowed. The maximum nesting depth is 50. Effect. The run unit terminates abnormally. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -43 Run-Time Diagnostic Messages Message List Recovery. Check PERFORM statements for proper termination or reduce the complexity of the program. It might be helpful to recompile the program with the directive PERFORM-TRACE. 150 (024) Alternate key not present in file Cause. During the execution of an OPEN statement, the description of an alternate key in the COBOL program does not correspond to any alternate key in the physical file that is assigned. That is, no key in the physical file matches the COBOL description in length and offset. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Correct either the program or the FUP CREATE or other process that created the file. 151 (025) DUPLICATES specification in SELECT does not match file Cause. During the execution of an OPEN statement, the description of an alternate key in the COBOL program includes the DUPLICATES phrase, and the key in the physical file that is assigned does not allow duplicates, or the program does not include DUPLICATES and the file allows duplicates. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Correct either the program or the FUP CREATE or other process that created the file. 152 (026) OPEN on a non-disk file that is specified with alternate keys Cause. The physical file assigned by the OPEN statement is not a structured disk file, but the COBOL program described it with alternate keys. Alternate keys are allowed only on structured disk files. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Either correct the program or assign the proper file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -44 Run-Time Diagnostic Messages Message List 153 (027) Create of new file failed with error nnn Cause. During the attempt to create a new file during the execution of an OPEN statement, Guardian error nnn was returned by the operating environment. Effect. The OPEN statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 154 (028) Sequential DELETE must follow successful READ Cause. A DELETE statement was executed on a file with ACCESS MODE SEQUENTIAL, and the preceding statement was not a successful READ statement. Effect. The DELETE statement is unsuccessful with I-O status code “43.” Recovery. Correct the program. 155 (029) DELETE positioning failed with error nnn Cause. The file positioning request issued during the processing of a DELETE statement was rejected with Guardian error nnn. Effect. The DELETE statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 156 (030) DELETE repositioning failed with error nnn Cause. The file positioning request issued after deleting a record during the processing of a DELETE statement was rejected with Guardian error nnn. Effect. The DELETE statement is unsuccessful with I-O status code “30”. Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -45 Run-Time Diagnostic Messages Message List 157 (031) Wrong open mode for DELETE Cause. A DELETE statement was executed, but the file was not open for I-O. Effect. The DELETE statement is unsuccessful with I-O status code “49.” Recovery. Correct the program. 158 (032) DELETE operation failed with error nnn Cause. The attempt to delete a record during the processing of a DELETE statement was rejected with Guardian error nnn. Effect. The DELETE statement is unsuccessful with I-O status code “30”. Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 159 (034) OPEN on an EDIT file and wrong open mode Cause. An EDIT file is opened for other than INPUT. HP COBOL cannot write to an EDIT file. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Correct the program, or assign other than an EDIT file. You can write to an unstructured file or an entry sequenced file, then use the GET PUT operation of EDIT to produce an EDIT file. 160 (035) OPEN on an EDIT file described with a record size that is too big Cause. The maximum record size for an EDIT file is 4095 bytes. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Correct the program, or assign other than an EDIT file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -46 Run-Time Diagnostic Messages Message List 161 (036) OPEN EXTEND positioning failed with error nnn Cause. The attempt to position the file at the end during the processing of an OPEN … EXTEND statement failed with Guardian error nnn. Effect. The OPEN statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 162 (037) OPEN on a nonexistent file that is not OPTIONAL Cause. The file referenced in an OPEN … EXTEND, I-O, or INPUT statement does not exist, and OPTIONAL is not specified in the SELECT clause for the file. Effect. The OPEN statement is unsuccessful with I-O status code “35.” Recovery. If you want the file to be created for EXTEND or I-O, put OPTIONAL in the SELECT clause; otherwise, verify that the file exists when the program is run. 163 (038) OPEN page eject failed with error nnn Cause. The attempt to eject the first page during the processing of an OPEN statement referencing a LINAGE file or during the process of COBOL_SPECIAL_OPEN_, COBOL85^SPECIAL^OPEN, or COBOLSPOOLOPEN failed with Guardian error nnn. Effect. The OPEN statement or call to COBOL_SPECIAL_OPEN_, COBOL85^SPECIAL^OPEN, or COBOLSPOOLOPEN is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 164 (039) OPEN rewind failed with error nnn Cause. The attempt to rewind the file during the processing of an OPEN statement failed with Guardian error nnn. Effect. The OPEN statement is unsuccessful with I-O status code “30.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -47 Run-Time Diagnostic Messages Message List Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 165 (040) OPEN requested for an unsupported device Cause. The device assigned to the COBOL file is not a legal device for COBOL input or output. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Assign a file on a legal device. 166 (041) OPEN requested for a locked file Cause. The file referenced in an OPEN statement is locked (CLOSE LOCK was executed). CLOSE LOCK is unrelated to LOCKFILE and UNLOCKFILE. A COBOL file name associated with a disk file can become locked even if it is never opened. This message appears when the disk file is also assigned to some other COBOL file name with the same ASSIGN name in the same run unit, and a CLOSE LOCK is executed on that file name. Effect. The OPEN statement is unsuccessful with I-O status code “38.” Recovery. Either do not close the file with lock or correct the program. 167 (042) OPEN requested for an open file Cause. The file referenced in an OPEN statement is already open. Effect. The OPEN statement is unsuccessful with I-O status code “41.” Recovery. Correct the program. 168 (043) LINAGE file not on printer or process Cause. The file referenced in an OPEN statement for a file with LINAGE specified is not assigned to a printer or a process (a spooler, for example). Effect. The OPEN statement is unsuccessful with I-O status code “39.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -48 Run-Time Diagnostic Messages Message List Recovery. Either assign the correct device or remove the LINAGE clause from the file description (FD). 169 (044) LOCK or UNLOCK operation failed with error nnn Cause. The attempt to lock or unlock a file or record with a LOCK or UNLOCK statement failed with Guardian error nnn. Effect. The statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 170 (045) MULTIPLE FILE TAPE file not on tape Cause. The device assigned to a file name associated with a MULTIPLE FILE TAPE clause in the I-O CONTROL paragraph is not a magnetic tape device. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Either remove the MULTIPLE FILE TAPE clause or assign a magnetic tape to the file. 171 (046) OPEN positioning for MULTIPLE FILE TAPE failed with error nnn Cause. The attempt to position to a file on a multiple file tape during the processing of an OPEN statement failed with Guardian error nnn. Effect. The OPEN statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 172 (047) OPEN on a nonexistent file and alternate keys specified Cause. A file with alternate keys specified does not exist when the attempt is made to open it. The file must have been created with a FUP CREATE or other means before it can be opened. Effect. The OPEN statement is unsuccessful with I-O status code “30.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -49 Run-Time Diagnostic Messages Message List Recovery. Create the file correctly before running the program, assign the correct file, or remove the alternate key specifications. 173 (049) Indexed file not defined as ORGANIZATION INDEXED Cause. The file assigned is an indexed (key sequenced) file, but the COBOL loadfile description does not specify ORGANIZATION INDEXED. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Assign the correct file or correct the file description in the program. 174 (050) OPEN INPUT when file not on input device Cause. A file is being opened for INPUT, but the device assigned is an illegal device or an output-only device (such as a printer). Effect. The OPEN statement is unsuccessful with I-O status code “37.” Recovery. Assign the correct device or file. 175 (051) Operation other than OPEN on file that is not open Effect. The program attempted an operation other than OPEN (such as READ or WRITE) on a file that is not open. Effect. The statement is unsuccessful with I-O status code “4x ” where x is appropriate for the statement. Recovery. Correct the program. 176 (052) File is not opened for timed I/O Cause. A TIME LIMIT operation (such READ … TIME LIMIT nn ) was attempted on a file that was not opened with TIME LIMITS specified. Effect. The operation is unsuccessful with I-O status code “90.” Recovery. Correct the program to do an OPEN … TIME LIMITS. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -50 Run-Time Diagnostic Messages Message List 177 (053) OPEN OUTPUT for file not on output device Cause. A file is being opened for OUTPUT, but the device assigned is an illegal device or an input-only device (such as a card reader). Effect. The OPEN statement is unsuccessful with I-O status code “37.” Recovery. Assign the proper device or file. 178 (054) Relative file not defined as ORGANIZATION RELATIVE Cause. The file assigned is a relative file, but the COBOL loadfile description does not specify ORGANIZATION RELATIVE. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Assign the correct file or correct the file description in the program. 179 (055) Sequential file not defined as ORGANIZATION SEQUENTIAL Cause. The file assigned is a sequential file (entry sequenced or unstructured), but the COBOL loadfile description specifies an organization other than sequential. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Assign the correct file or correct the file description in the program. 180 (056) Non-disk or unstructured file and not sequential organization Cause. The COBOL program describes the file as ORGANIZATION RELATIVE or INDEXED, but the assigned file is not a structured disk file. Only structured disk files can be assigned to RELATIVE or INDEXED COBOL files. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Assign the correct file or correct the file description in the program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -51 Run-Time Diagnostic Messages Message List 181 (057) OPEN operation failed with error nnn Cause. A Guardian error nnn was returned during OPEN, COBOL_SPECIAL_OPEN_, COBOL85^SPECIAL^OPEN, or COBOLSPOOLOPEN processing. Effect. The OPEN statement or the call to COBOL_SPECIAL_OPEN_, COBOL85^SPECIAL^OPEN, or COBOLSPOOLOPEN is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 182 (058) Primary key offset in program does not match file Cause. During the execution of an OPEN statement, the prime key offset in the COBOL program does not correspond to the prime key in the physical file that is assigned. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Correct either the program or the FUP CREATE or other process that created the file. 183 (059) Primary key size in program does not match file Cause. During the execution of an OPEN statement, the prime key size in the COBOL program does not correspond to the prime key in the physical file that is assigned. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Correct either the program or the FUP CREATE or other process that created the file. 184 (060) Purge of file during OPEN failed with error nnn Cause. During the execution of an OPEN statement, the attempt to purge a file (the purge is due to some attribute conflicts) failed with Guardian error nnn. Effect. The OPEN statement is unsuccessful with I-O status code “30”. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -52 Run-Time Diagnostic Messages Message List Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. A value of “48,” for example, means that the program does not have permission to purge an existing file that has an improper record size and create a new one. 185 (061) Purge data from file during OPEN failed with error nnn Cause. During the execution of an OPEN statement, the attempt to purge the data from the file (the purge is due to an OPEN OUTPUT on a file that contains data) failed with Guardian error nnn. Effect. The OPEN statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 186 (063) READ operation failed with error nnn Cause. During the execution of a READ statement, the system read routine failed with Guardian error nnn. Effect. The READ statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 187 (064) READ WITH LOCK on file with read ahead or an OSS file Cause. A READ … LOCK statement was attempted on an OSS file or a file that is reading ahead. This can happen if the file is opened for INPUT and the organization is sequential. A READ operation that is executed as part of a transaction (delimited by ENTER “BEGINTRANSACTION” and ENTER “ENDTRANSACTION” statements) requires such locking. For the exact set of conditions under which the run-time routines try to preread records, see OPEN. Effect. The READ statement is unsuccessful with I-O status code “91.” Recovery. For a Guardian file, either remove the LOCK or open the file for I-O. For an OSS file, remove the LOCK. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -53 Run-Time Diagnostic Messages Message List 188 (065) READ positioning failed with error nnn Cause. An attempt to position the file for a READ statement failed with Guardian error nnn. Effect. The READ statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 189 (066) Sequential READ requested when current position is undefined Cause. The program attempted to execute a sequential READ statement when the last operation was not a successful READ, OPEN, or START. One common cause is attempting to do a READ after an at-end condition occurs. Effect. The READ statement is unsuccessful with I-O status code “46.” Recovery. Correct the program. 190 (067) Wrong open mode for READ Cause. The program attempted to execute a READ statement, but the open mode for the file is not INPUT or I-O. Effect. The READ statement is unsuccessful with I-O status code “47.” Recovery. Correct the program. 191 (068) Reel swap failed with error nnn Cause. An attempt to do a tape reel swap failed. If the failure was due to a system error, nnn is the Guardian error code. If the failure was due to the operator responding incorrectly to the swap requests, nnn is 0. Effect. The READ statement is unsuccessful with I-O status code “30.” Recovery. Correct the cause of the problem. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -54 Run-Time Diagnostic Messages Message List 192 (069) Sequential REWRITE must follow successful READ Cause. The program attempted to execute a REWRITE statement to a file for which ACCESS MODE SEQUENTIAL is specified, and the last operation on the file was not a successful READ statement (for example, an at-end condition resulted). Effect. The REWRITE statement is unsuccessful with I-O status code “43.” Recovery. Correct the program. 193 (070) REWRITE positioning failed with error nnn Cause. An attempt to position the file for a REWRITE statement failed with Guardian error nnn. Effect. The REWRITE statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 194 (071) REWRITE repositioning failed with error nnn Cause. An attempt to reposition the file after the rewrite operation during execution of a REWRITE statement failed with Guardian error nnn. Effect. The REWRITE statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 195 (072) Wrong open mode for REWRITE Cause. The file referenced in a REWRITE statement is not opened in the I-O mode. Effect. The REWRITE statement is unsuccessful with I-O status code “49.” Recovery. Correct the program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -55 Run-Time Diagnostic Messages Message List 196 (073) Sequential REWRITE permitted only with same record size Cause. At attempt to REWRITE a record on a file with sequential organization failed because the new record is not the same size as the old one. Effect. The REWRITE statement is unsuccessful with I-O status code “44.” Recovery. Correct the program. 197 (074) REWRITE operation failed with error nnn Cause. The attempt to rewrite the record during execution of a REWRITE statement failed with Guardian error nnn. Effect. The REWRITE statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 198 (076) START operation failed with error nnn Cause. The attempt to read the selected record during execution of a START statement failed with Guardian error nnn. Effect. The START statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 199 (077) START positioning failed with error nnn Cause. The attempt to position the file during execution of a START statement failed with Guardian error nnn. Effect. The START statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -56 Run-Time Diagnostic Messages Message List 200 (078) Wrong open mode for START Cause. The file referenced in a START statement is not open for INPUT or I-O. Effect. The START statement is unsuccessful with I-O status code “47.” Recovery. Correct the program. 201 (079) System node not available or does not exist Cause. During the processing of an OPEN statement referencing a file that is assigned to a system node (the ASSIGN phrase includes “\xxx ” in the file name), Guardian indicated that the system is not up or does not exist. Effect. The OPEN statement is unsuccessful with I-O status code “30.” Recovery. Either assign to the correct system node or determine why the node is not responding. 202 (080) LOCKFILE, UNLOCKFILE or UNLOCKRECORD on a file that is not open Cause. The file referenced in a LOCKFILE, UNLOCKFILE, or UNLOCKRECORD statement is not open. Effect. The statement is unsuccessful with I-O status code “42.” Recovery. Correct the program. 203 (081) OPEN on unstructured file described without fixed length records Cause. An unstructured file is assigned to a COBOL file name whose RECORD CONTAINS clause in the file description indicates that the records are variable. Effect. The OPEN statement is unsuccessful with I-O status code “39.” Recovery. Either correct the RECORD CONTAINS clause or assign the correct file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -57 Run-Time Diagnostic Messages Message List 204 (082) Writing end of file failed with error nnn Cause. The attempt to write an end of file on a tape during the execution of a CLOSE statement failed with Guardian error nnn. Effect. The CLOSE statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 205 (083) Writing end of reel failed with error nnn Cause. The attempt to write an end of reel on a tape during the execution of a CLOSE REEL or WRITE statement failed with Guardian error nnn. Effect. The statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 206 (084) WRITE operation failed with error nnn Cause. The attempt to write the record during the execution of a WRITE statement or the attempt to write a saved record during the execution of a CLOSE statement failed with Guardian error nnn. Effect. The statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. For example, a Guardian error value of 21 is a File System error that indicates “illegal count specified,” which could arise from a block size error in the file description. 207 (085) WRITE failed because file is full Cause. The attempt to write the record during the execution of a WRITE statement or the attempt to write a saved record during the execution of a CLOSE statement failed because the file is full. Effect. The statement is unsuccessful with I-O status code “34.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -58 Run-Time Diagnostic Messages Message List Recovery. Correct the program if it is in a loop, or increase the number of extents allocated for the file. You can use a FUP CREATE command for this purpose. 208 (086) WRITE positioning failed with error nnn Cause. The attempt to position the file during the execution of a random WRITE statement failed with Guardian error nnn. Effect. The statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 209 (087) WRITE repositioning failed with error nnn Cause. The attempt to reposition the file after writing a record during the execution of a random WRITE statement failed with Guardian error nnn. Effect. The statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 210 (088) Line skipping failed with error nnn Cause. The attempt to skip lines on a file during the execution of a random WRITE statement with ADVANCING specified failed with Guardian error nnn. Effect. The statement is unsuccessful with I-O status code “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it might indicate corrective action. 211 (089) Wrong open mode for WRITE Cause. A WRITE statement was attempted on a relative or indexed on a file that does not meet any one of these criteria: • • • Its open mode is OUTPUT. Its open mode is EXTEND and its access mode is sequential. Its open mode is I-O and its access mode is not sequential. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -59 Run-Time Diagnostic Messages Message List A WRITE statement was attempted on a sequential file that does not meet any of these criteria: 1. Its open mode is EXTEND or OUTPUT. 2. Its open mode is I-O and the device assigned is a process, a terminal or $RECEIVE. Effect. The statement is unsuccessful with I-O status code “48” except for Item 2 for sequential, in which the I-O status code is “90.” Recovery. Correct the program or assign the correct device. 212 (090) Wrong length record specified for WRITE or REWRITE Cause. The record length specified in the program (either by an OCCURS DEPENDING clause in the record description of the record being written or by the DEPENDING identifier in the RECORD VARYING clause in the file description entry) is shorter than the minimum or larger than the maximum length specified in the RECORD clause. Effect. The WRITE or REWRITE statement is unsuccessful with I-O status code “44.” Recovery. Correct the program—in either the record length calculation or the RECORD clause. 213 (092) OPEN EXTEND for file not on extend device Cause. A file is being opened for EXTEND, but the device assigned is an illegal device or an input-only device (such as a card reader). Effect. The OPEN statement is unsuccessful with I-O status code “37.” Recovery. Assign the proper device or file. 214 (093) OPEN I-O for file not on input-output device Cause. A file is being opened for I-O, but the device assigned is an illegal device or an input- or output-only device (such as a magnetic tape). Effect. The OPEN statement is unsuccessful with I-O status code “37.” Recovery. Assign the proper device or file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -60 Run-Time Diagnostic Messages Message List 215 (094) Wrong or missing LABELS attribute Cause. A LABELS attribute in a DEFINE command that refers to the file contains other than OMITTED, BYPASS, ANSI, or IBM. Effect. The OPEN statement is unsuccessful with I-O status code “90.” Recovery. Before running this program again, verify that the DEFINE in the environment is correct. 216 (095) Wrong or missing USE attribute Cause. A USE attribute in a DEFINE command that refers to a file contains other than OPEN, IN, OUT, or EXTEND. Effect. The OPEN statement is unsuccessful with I-O status code “90.” Recovery. Before running this program again, verify that the DEFINE in the environment is correct. 217 (096) Wrong or missing RECFORM attribute Cause. A RECFORM attribute in a DEFINE command that refers to a file contains other than F or U, or F is specified and variable length records are specified in the File Description for the file, or U is specified and fixed length records are specified for the file. Effect. The OPEN statement is unsuccessful with I-O status code “90.” Recovery. Before running this program again, verify that the DEFINE in the environment is correct or correct the file description. 218 (097) Wrong or missing RECLEN attribute Cause. A RECLEN attribute in a DEFINE command that refers to a file contains more than 6 digits, is not correctly formed, is negative, or is not the record size for fixed length records. Effect. The OPEN statement is unsuccessful with I-O status code “90.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -61 Run-Time Diagnostic Messages Message List Recovery. Before running this program again, verify that the DEFINE in the environment is correct or correct the file’s record description. 219 (098) Wrong or missing BLOCKLEN attribute Cause. A BLOCKLEN attribute in a DEFINE command that refers to a file contains more than 6 digits, is not correctly formed, is negative, is omitted for tapes specified with LABEL RECORDS STANDARD, is greater than the record length when BLOCK CONTAINS is not specified, or does not match file File Definition. Effect. The OPEN statement is unsuccessful with I-O status code “90.” Recovery. Before running this program again, verify that the DEFINE in the environment is correct or correct the file description. 220 (099) Wrong or missing FILESEQ attribute Cause. A FILESEQ attribute in a DEFINE command that refers to a file contains more than 4 digits, is not correctly formed, is negative, or does not match that specified in the MULTIPLE FILE TAPE clause. Effect. The OPEN statement is unsuccessful with I-O status code “90.” Recovery. Before running this program again, verify that the DEFINE in the environment is correct or correct the file’s MULTIPLE FILE TAPE clause. 221 (100) Wrong or missing DEVICE attribute Cause. A DEVICE attribute in a DEFINE command that refers to a file does not start with a dollar sign ($) or backslash (\) or is not alphabetic. Effect. The OPEN statement is unsuccessful with I-O status code “90.” Recovery. Before running this program again, verify that the DEFINE in the environment is correct. 222 (101) A DEFINE procedure failed with error nnn Cause. A request to get DEFINE information failed with Guardian error nnn. Effect. The OPEN statement is unsuccessful with I-O status code “90.” HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -62 Run-Time Diagnostic Messages Message List Recovery. You can use the command interpreter ERROR command to discover the meaning of the Guardian error number. The message might suggest a corrective action. 223 (102) DEFINE required for LABEL RECORDS STANDARD Cause. A DEFINE command is required if LABEL RECORDS STANDARD is specified in the File Definition. Effect. The OPEN statement is unsuccessful with I-O status code “90.” Recovery. Before running this program again, verify that the DEFINE in the environment is correct or correct the file description. 224 (111) PositionEdit failed with error nnn Cause. The call to PositionEdit made during the OPEN processing for an EDIT file failed with Guardian error nnn. Effect. The OPEN statement is unsuccessful with I-O status code “30.” Recovery. You can use the command interpreter ERROR command to discover the meaning of the Guardian error number. The message might suggest a corrective action. 225 (112) Size of unstructured file opened EXTEND not multiple of record size Cause. The end of file on an unstructured file being opened for EXTEND is not a multiple of the record size. Effect. The OPEN statement is unsuccessful with an I-O status code “30.” Recovery. If an incorrect file was assigned, assign the correct one. Otherwise, you must take some action to repair the file. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -63 Run-Time Diagnostic Messages Message List 226 (113) File attributes don't match and file not opened OUTPUT or has alt keys Cause. The file attributes of the existing file conflict with the file description in the program and the file is not being opened for output, or (if it is being opened for output) the file description specifies alternate record keys (COBOL cannot create a file with alternate keys). The conflict is that the record sizes differ (the file description specifies a larger maximum record than the existing file’s attributes), and the COBOL program indicates that the records are fixed length. Effect. The OPEN statement is unsuccessful with I-O status code “30.” Recovery. Either correct the program descriptions or assign the correct file. 227 (114) Loadclose failed with internal error mmm, GUARDIAN error nnn Cause. The HP COBOL Fast I-O routine loadclose returned the indicated error codes. Effect. The CLOSE statement is unsuccessful. If the Guardian error is 43, the I-O status code is "34"; otherwise it is "30". Recovery. If you can resolve the Guardian error, do so; otherwise report the error to your service provider. 228 SEGMENT_ALLOCATE_ for fast i/o failed with error return nnn (115) Allocatesegment for fast i/o failed with error return nnn Cause. An attempt to allocate an extended segment for use with HP COBOL Fast I-O failed with the indicated error. Effect. Instead of using HP COBOL Fast I-O (local buffering provided by HP COBOL), the program uses standard I-O processing. Recovery. The Guardian Procedure Calls Reference Manual documents the errors that ALLOCATESEGMENT returns. Take the appropriate action. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -64 Run-Time Diagnostic Messages Message List 229 (116) Loadopen failed with internal error mmm, GUARDIAN error nnn Cause. The HP COBOL Fast I-O routine loadopen returned the indicated error codes. Effect. The OPEN statement is unsuccessful with I-O status code “30.” Recovery. If you can resolve the Guardian error, do so; otherwise report the error to your service provider. 230 (117) Loadwrite failed with internal error mmm, GUARDIAN error nnn Cause. The HP COBOL Fast I-O routine loadwrite returned the indicated error codes. Effect. The WRITE statement is unsuccessful with I-O status code “30.” Recovery. If you can resolve the Guardian error, do so; otherwise report the error to your service provider. 231 (118) Initnewdatablock (Fast i-o) failed Cause. The HP COBOL Fast I-O routine initnewdatablock failed. Effect. The READ statement is unsuccessful with I-O status code “30.” Recovery. Report the error to your service provider. 232 (119) An illegal operation was attempted on a fast i/o file Cause. The program attempted to execute a READ REVERSED, REWRITE, or START statement to a file that is using HP COBOL Fast I-O. Effect. The REWRITE statement is unsuccessful with I-O status code “40.” Recovery. Change the program so that it does not attempt to use HP COBOL Fast I-O. A program attempts to use HP COBOL Fast I-O on a sequential file that meets these criteria: • • You are not creating an audited file (you can read an audited file, however). The file description includes a RESERVE clause with a number specifying the number of blocks to buffer. In the non-CRE environment, number must be greater than 1; in the CRE, it must be greater than 2. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -65 Run-Time Diagnostic Messages • • • • Message List The file description does not include a LINAGE clause or a CODE-SET clause. The file was not opened with time limits (as with the TIME LIMITS phrase in the OPEN statement). The program is not compiled with the NONSTOP directive. The specifications in the OPEN statement, or the attributes derived during the open operation by some other means (such as from an applicable command interpreter ASSIGN command), conform to: ° ° ° The open mode is INPUT or OUTPUT. The exclusion mode is EXCLUSIVE if OPEN OUTPUT is specified. The exclusion mode is PROTECTED if OPEN INPUT is specified. 233 (122) OPEN OUTPUT SHARED specified for open disk file Cause. OPEN OUTPUT file name SHARED was specified, and another process had the file open (in any exclusion mode). Effect. The OPEN statement is unsuccessful with I-O status error 30 and GUARDIAN-ERR 12. Recovery. If you do not want to delete all of the information in the file, change the OPEN statement to OPEN I-O file-name SHARED and if necessary, specify OPTIONAL in the SELECT clause for the file. If you do want to delete all of the information in the file, add a null Declarative Portion for this file to the program, recompile it (to allow the run unit to continue), and change the code to something like this: PERFORM WITH TEST AFTER UNTIL file-status (1: 1) = "0" OPEN OUTPUT the-file SHARED IF file-status (1: 1) NOT = "0" IF file-status = "30" AND GUARDIAN-ERR = 12 (count these, send a message, or take other appropriate action) ENTER TAL "DELAY" USING some-time ELSE (issue some other error and terminate program) END-IF END-IF END-PERFORM where file-status appears in the FILE STATUS clause in the SELECT clause, and some-time is the number of 0.01-second intervals to delay. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -66 Run-Time Diagnostic Messages Message List Each occurrence of this error produces a message on the home terminal or in the execution log. 234 CLOSE operation failed with error nnn (124) The CLOSE operation failed with Guardian error nnn Cause. The Guardian file system reported error nnn during execution of a close operation. Effect. The CLOSE statement is unsuccessful with I-O status “30.” Recovery. Type ERROR nnn to see the meaning of the Guardian error; it may indicate corrective action. 235 (126) REVERSED not allowed for this file Cause. The file name specified in a READ REVERSED statement is assigned to a physical file that cannot be read in reverse; that is, one of: • • • • • A nondisk file A disk file for which preread was selected A disk file that is an edit file for ENV OLD A disk file that is an edit file for ENV COMMON or for native HP COBOL with the NONSTOP directive active An unstructured disk file that is blocked Effect. The READ statement is unsuccessful with I-O status “30.” Recovery. One of: • • • • If the physical file is not a disk file, use a disk file instead. If preread is selected, cancel it (for example, add SHARED to the OPEN statement that opens the file, or open the file in I-O mode rather than INPUT mode). Use something other than an edit file. Remove BLOCK CONTAINS from the unstructured file FD. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -67 Run-Time Diagnostic Messages Message List none (075) CLOSE LOCK while same file open elsewhere in run unit Cause. The program has two files open that are assigned to the same physical file and is attempting to close one with the LOCK phrase. Effect. The CLOSE statement is successful. The open file is not locked. Recovery. Correct the program. none (091) Descriptions for the same external file differ Cause. The file-control entry for an external file in one program differs from that in another. These entries must be the same. Effect. The run unit terminates abnormally. Recovery. Correct the file-control entry. none (103) Blocking not permitted for odd length records Cause. Blocking is specified for a file (either through BLOCKLEN in a DEFINE for the file or in the File Description for the file), and the records are not an even number of characters in length. Effect. The OPEN statement is unsuccessful with I-O status code “90.” Recovery. Before running this program again, verify that the DEFINE in the environment is correct or correct the file description. none (105) No space for PARAM EXECUTION-LOG file block Cause. The initial processing of the PARAM EXECUTION-LOG was unable to obtain space for its file block. Effect. The run unit terminates abnormally. Recovery. Rebind or relink the program using the DATA PAGES option in the BUILD command to get more space. You can also use the MEM parameter of the RUN command to increase the available space. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -68 Run-Time Diagnostic Messages Message List none (107) File referenced in PARAM EXECUTION-LOG is an invalid device Cause. The device assigned to the file specified in PARAM EXECUTION-LOG is not a disk, terminal, or process. Effect. The run unit terminates abnormally. Recovery. Specify a file on the proper device. none (120) The file name in PARAM PRINTER-CONTROL is not a legal COBOL file name Cause. The file name specified in the PARAM PRINTER-CONTROL does not conform to the rules for a COBOL file name. Effect. The run unit terminates abnormally. Recovery. Change the file name in PARAM PRINTER-CONTROL to a legal COBOL file name (for the syntax of a legal COBOL file name, see the Guardian Procedure Calls Reference Manual). none (125) An ENV COMMON routine called from an ENV OLD program Cause. A program that was compiled without the directive ENV COMMON or ENV LIBRARY (a non-CRE program) called a routine that must run in the CRE. An example of a routine that must run in the CRE is COBOL_ASSIGN_ (or any other COBOL utility library routine with underscores in its name). Effect. The run unit terminates abnormally. Recovery. Either compile the calling program with ENV COMMON or change the name of the called routine to its COBOL-environment equivalent (for example, change COBOL_ASSIGN_ to COBOLASSIGN). For COBOL-environment equivalents of other CRE routines, see Table 13-6, Table 13-16, Table 13-18, and Table 13-11. HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -69 Run-Time Diagnostic Messages Message List none (128) PARAM WAITED-IO ON specified and illegal OPEN attempted Cause. PARAM WAITED-IO ON was specified, and one of these OPEN operations was attempted: • • OPEN … TIME LIMITS OPEN file-name where file-name references $RECEIVE Effect. The run unit terminates abnormally. Recovery. Either correct the program or rerun it without the PARAM WAITED-IO command COBOL_SETMODE_ HP COBOL Manual for TNS and TNS/R Programs —522555-006 48 -70 Part V. Appendixes Title Appendix A, ASCII Character Set Appendix B, Data Type Correspondence HP COBOL Manual for TNS and TNS/R Programs —522555-006 Part V. Appendixes HP COBOL Manual for TNS and TNS/R Programs —522555-006 A ASCII Character Set This appendix contains two tables of the ASCII character set, both of which use these column headings: Column Heading Meaning Ord. Character’s ordinal number in the ASCII character set Octal Character’s octal representation (with left and right bytes) Hex. Character’s hexadecimal representation Dec. Character’s decimal representation Char Character code or character itself (such as NULL or A ) Meaning Meaning of character code (such as “Null” or “Uppercase A ”) Table A-1 is in numeric order and Table A-2 is in alphabetic order. ASCII Character Set in Numeric Order Table A-1 presents the ASCII character set in numeric order; that is, these columns are in numeric order: • • • • Ord. (the character’s ordinal number in the ASCII character set) Octal (the character’s octal representation) Hex. (the character’s hexadecimal representation) Dec. (the character’s decimal representation) If you know one of the preceding values for the character you want to look up, use Table A-1; if you know only the character code or the character itself (such as “NUL” or “A”), use Table A-2 instead. Table A-1. ASCII Character Set in Numeric Order (page 1 of 5) Octal Ord. Left Right Hex. Dec. Char. Meaning 1 000000 000000 00 0 NUL Null 2 000400 000001 01 1 SOH Start of heading 3 001000 000002 02 2 STX Start of text 4 001400 000003 03 3 ETX End of text 5 002000 000004 04 4 EOT End of transmission 6 002400 000005 05 5 ENQ Enquiry 7 003000 000006 06 6 ACK Acknowledge 8 003400 000007 07 7 BEL Bell 9 004000 000010 08 8 BS Backspace 10 004400 000011 09 9 HT Horizontal tabulation HP COBOL Manual for TNS and TNS/R Programs —522555-006 A- 1 ASCII Character Set ASCII Character Set in Numeric Order Table A-1. ASCII Character Set in Numeric Order (page 2 of 5) Octal Ord. Left Right Hex. Dec. Char. Meaning 11 005000 000012 0A 10 LF Line feed 12 005400 000013 0B 11 VT Vertical tabulation 13 006000 000014 0C 12 FF Form feed 14 006400 000015 0D 13 CR Carriage return 15 007000 000016 0E 14 SO Shift out 16 007400 000017 0F 15 SI Shift in 17 010000 000020 10 16 DLE Data link escape 18 010400 000021 11 17 DC1 Device control 1 19 011000 000022 12 18 DC2 Device control 2 20 011400 000023 13 19 DC3 Device control 3 21 012000 000024 14 20 DC4 Device control 4 22 012400 000025 15 21 NAK Negative acknowledge 23 013000 000026 16 22 SYN Synchronous idle 24 013400 000027 17 23 ETB End of transmission block 25 014000 000030 18 24 CAN Cancel 26 014400 000031 19 25 EM End of medium 27 015000 000032 1A 26 SUB Substitute 28 015400 000033 1B 27 ESC Escape 29 016000 016000 1C 28 FS File separator 30 016400 000035 1D 29 GS Group separator 31 017000 000036 1E 30 RS Record separator 32 017400 000037 1F 31 US Unit separator 33 020000 000040 20 32 SP Space 34 020400 000041 21 33 ! Exclamation point 35 021000 000042 22 34 " Quotation mark 36 021400 000043 23 35 # Number sign 37 022000 000044 24 36 $ Dollar sign 38 022400 000045 25 37 % Percent sign 39 023000 000046 26 38 & Ampersand 40 023400 000047 27 39 ' Apostrophe 41 024000 000050 28 40 ( Opening parenthesis 42 024400 000051 29 41 ) Closing parenthesis 43 025000 000052 2A 42 * Asterisk HP COBOL Manual for TNS and TNS/R Programs —522555-006 A- 2 ASCII Character Set ASCII Character Set in Numeric Order Table A-1. ASCII Character Set in Numeric Order (page 3 of 5) Octal Ord. Left Right Hex. Dec. Char. Meaning 44 025400 000053 2B 43 + Plus 45 026000 000054 2C 44 , Comma 46 026400 000055 2D 45 - Hyphen (minus) 47 027000 000056 2E 46 . Period (decimal point) 48 027400 000057 2F 47 / Slash 49 030000 000060 30 48 0 Zero 50 030400 000061 31 49 1 One 51 031000 000062 32 50 2 Two 52 031400 000063 33 51 3 Three 53 032000 000064 34 52 4 Four 54 032400 000065 35 53 5 Five 55 033000 000066 36 54 6 Six 56 033400 000067 37 55 7 Seven 57 034000 000070 38 56 8 Eight 58 034400 000071 39 57 9 Nine 59 035000 000072 3A 58 : Colon 60 035400 000073 3B 59 ; Semicolon 61 036000 000074 3C 60 < Less than 62 036400 000075 3D 61 = Equals 63 037000 000076 3E 62 > Greater than 64 037400 000077 3F 63 ? Question mark 65 040000 000100 40 64 @ Commercial at sign 66 040400 000101 41 65 A Uppercase A 67 041000 000102 42 66 B Uppercase B 68 041400 000103 43 67 C Uppercase C 69 042000 000104 44 68 D Uppercase D 70 042400 000105 45 69 E Uppercase E 71 043000 000106 46 70 F Uppercase F 72 043400 000107 47 71 G Uppercase G 73 044000 000110 48 72 H Uppercase H 74 044400 000111 49 73 I Uppercase I 75 045000 000112 4A 74 J Uppercase J 76 045400 000113 4B 75 K Uppercase K HP COBOL Manual for TNS and TNS/R Programs —522555-006 A- 3 ASCII Character Set ASCII Character Set in Numeric Order Table A-1. ASCII Character Set in Numeric Order (page 4 of 5) Octal Ord. Left Right Hex. Dec. Char. Meaning 77 046000 000114 4C 76 L Uppercase L 78 046400 000115 4D 77 M Uppercase M 79 047000 000116 4E 78 N Uppercase N 80 047400 000117 4F 79 O Uppercase O 81 050000 000120 50 80 P Uppercase P 82 050400 000121 51 81 Q Uppercase Q 83 051000 000122 52 82 R Uppercase R 84 051400 000123 53 83 S Uppercase S 85 052000 000124 54 84 T Uppercase T 86 052400 000125 55 85 U Uppercase U 87 053000 000126 56 86 V Uppercase V 88 053400 000127 57 87 W Uppercase W 89 054000 000130 58 88 X Uppercase X 90 054400 000131 59 89 Y Uppercase Y 91 055000 000132 5A 90 Z Uppercase Z 92 055400 000133 5B 91 [ Opening bracket 93 056000 000134 5C 92 \ Backslash 94 056400 000135 5D 93 ] Closing bracket 95 057000 000136 5E 94 ^ Circumflex 96 057400 000137 5F 95 _ Underscore 97 060000 000140 60 96 ` Grave accent 98 060400 000141 61 97 a Lowercase a 99 061000 000142 62 98 b Lowercase b 100 061400 000143 63 99 c Lowercase c 101 062000 000144 64 100 d Lowercase d 102 062400 000145 65 101 e Lowercase e 103 063000 000146 66 102 f Lowercase f 104 063400 000147 67 103 g Lowercase g 105 064000 000150 68 104 h Lowercase h 106 064400 000151 69 105 i Lowercase i 107 065000 000152 6A 106 j Lowercase j 108 065400 000153 6B 107 k Lowercase k 109 066000 000154 6C 108 l Lowercase l HP COBOL Manual for TNS and TNS/R Programs —522555-006 A- 4 ASCII Character Set ASCII Character Set in Numeric Order Table A-1. ASCII Character Set in Numeric Order (page 5 of 5) Octal Ord. Left Right Hex. Dec. Char. Meaning 110 066400 000155 6D 109 m Lowercase m 111 067000 000156 6E 110 n Lowercase n 112 067400 000157 6F 111 o Lowercase o 113 070000 000160 70 112 p Lowercase p 114 070400 000161 71 113 q Lowercase q 115 071000 000162 72 114 r Lowercase r 116 071400 000163 73 115 s Lowercase s 117 072000 000164 74 116 t Lowercase t 118 072400 000165 75 117 u Lowercase u 119 073000 000166 76 118 v Lowercase v 120 073400 000167 77 119 w Lowercase w 121 074000 000170 78 120 x Lowercase x 122 074400 000171 79 121 y Lowercase y 123 075000 000172 7A 122 z Lowercase z 124 075400 000173 7B 123 { Opening brace 125 076000 000174 7C 124 | Vertical line 126 076400 000175 7D 125 } Closing brace 127 077000 000176 7E 126 ~ Tilde 128 077400 000177 7F 127 DEL Delete HP COBOL Manual for TNS and TNS/R Programs —522555-006 A- 5 ASCII Character Set ASCII Character Set in Alphabetic Order ASCII Character Set in Alphabetic Order Table A-2 presents the ASCII character set in alphabetic order—that is, alphabetic character codes (in the column labelled “Char.”) are in alphabetic order. Table A-2. ASCII Character Set in Alphabetic Order (page 1 of 4) Octal Char. Meaning Ord. Left Right Hex. Dec. ^ Circumflex 95 057000 000136 5E 94 ~ Tilde 127 077000 000176 7E 126 ! Exclamation point 34 020400 000041 21 33 " Quotation mark 35 021000 000042 22 34 # Number sign 36 021400 000043 23 35 $ Dollar sign 37 022000 000044 24 36 % Percent sign 38 022400 000045 25 37 & Ampersand 39 023000 000046 26 38 ' Apostrophe 40 023400 000047 27 39 ( Opening parenthesis 41 024000 000050 28 40 ) Closing parenthesis 42 024400 000051 29 41 * Asterisk 43 025000 000052 2A 42 + Plus 44 025400 000053 2B 43 , Comma 45 026000 000054 2C 44 - Hyphen (minus) 46 026400 000055 2D 45 . Period (decimal point) 47 027000 000056 2E 46 / Slash 48 027400 000057 2F 47 0 Zero 49 030000 000060 30 48 1 One 50 030400 000061 31 49 2 Two 51 031000 000062 32 50 3 Three 52 031400 000063 33 51 4 Four 53 032000 000064 34 52 5 Five 54 032400 000065 35 53 6 Six 55 033000 000066 36 54 7 Seven 56 033400 000067 37 55 8 Eight 57 034000 000070 38 56 9 Nine 58 034400 000071 39 57 : Colon 59 035000 000072 3A 58 ; Semicolon 60 035400 000073 3B 59 HP COBOL Manual for TNS and TNS/R Programs —522555-006 A- 6 ASCII Character Set ASCII Character Set in Alphabetic Order Table A-2. ASCII Character Set in Alphabetic Order (page 2 of 4) Octal Char. Meaning Ord. Left Right Hex. Dec. < Less than 61 036000 000074 3C 60 = Equals 62 036400 000075 3D 61 > Greater than 63 037000 000076 3E 62 ? Question mark 64 037400 000077 3F 63 @ Commercial at sign 65 040000 000100 40 64 [ Opening bracket 92 055400 000133 5B 91 \ Backslash 93 056000 000134 5C 92 ] Closing bracket 94 056400 000135 5D 93 _ Underscore 96 057400 000137 5F 95 ` Grave accent 97 060000 000140 60 96 A Uppercase A 66 040400 000101 41 65 a Lowercase a 98 060400 000141 61 97 ACK Acknowledge 7 003000 000006 06 6 B Uppercase B 67 041000 000102 42 66 b Lowercase b 99 061000 000142 62 98 BEL Bell 8 003400 000007 07 7 BS Backspace 9 004000 000010 08 8 C Uppercase C 68 041400 000103 43 67 c Lowercase c 100 061400 000143 63 99 CAN Cancel 25 014000 000030 18 24 CR Carriage return 14 006400 000015 0D 13 D Uppercase D 69 042000 000104 44 68 d Lowercase d 101 062000 000144 64 100 DC1 Device control 1 18 010400 000021 11 17 DC2 Device control 2 19 011000 000022 12 18 DC3 Device control 3 20 011400 000023 13 19 DC4 Device control 4 21 012000 000024 14 20 DEL Delete 128 077400 000177 7F 127 DLE Data link escape 17 010000 000020 10 16 E Uppercase E 70 042400 000105 45 69 e Lowercase e 102 062400 000145 65 101 EM End of medium 26 014400 000031 19 25 ENQ Enquiry 6 002400 000005 05 5 HP COBOL Manual for TNS and TNS/R Programs —522555-006 A- 7 ASCII Character Set ASCII Character Set in Alphabetic Order Table A-2. ASCII Character Set in Alphabetic Order (page 3 of 4) Octal Char. Meaning Ord. Left Right Hex. Dec. EOT End of transmission 5 002000 000004 04 4 ESC Escape 28 015400 000033 1B 27 ETB End of transmission block 24 013400 000027 17 23 ETX End of text 4 001400 000003 03 3 F Uppercase F 71 043000 000106 46 70 f Lowercase f 103 063000 000146 66 102 FF Form feed 13 006000 000014 0C 12 FS File separator 29 016000 016000 1C 28 G Uppercase G 72 043400 000107 47 71 g Lowercase g 104 063400 000147 67 103 GS Group separator 30 016400 000035 1D 29 H Uppercase H 73 044000 000110 48 72 h Lowercase h 105 064000 000150 68 104 HT Horizontal tabulation 10 004400 000011 09 9 I Uppercase I 74 044400 000111 49 73 i Lowercase i 106 064400 000151 69 105 J Uppercase J 75 045000 000112 4A 74 j Lowercase j 107 065000 000152 6A 106 K Uppercase K 76 045400 000113 4B 75 k Lowercase k 108 065400 000153 6B 107 L Uppercase L 77 046000 000114 4C 76 l Lowercase l 109 066000 000154 6C 108 LF Line feed 11 005000 000012 0A 10 M Uppercase M 78 046400 000115 4D 77 m Lowercase m 110 066400 000155 6D 109 N Uppercase N 79 047000 000116 4E 78 n Lowercase n 111 067000 000156 6E 110 NAK Negative acknowledge 22 012400 000025 15 21 NUL Null 1 000000 000000 00 0 O Uppercase O 80 047400 000117 4F 79 o Lowercase o 112 067400 000157 6F 111 P Uppercase P 81 050000 000120 50 80 p Lowercase p 113 070000 000160 70 112 HP COBOL Manual for TNS and TNS/R Programs —522555-006 A- 8 ASCII Character Set ASCII Character Set in Alphabetic Order Table A-2. ASCII Character Set in Alphabetic Order (page 4 of 4) Octal Char. Meaning Ord. Left Right Hex. Dec. Q Uppercase Q 82 050400 000121 51 81 q Lowercase q 114 070400 000161 71 113 R Uppercase R 83 051000 000122 52 82 r Lowercase r 115 071000 000162 72 114 RS Record separator 31 017000 000036 1E 30 S Uppercase S 84 051400 000123 53 83 s Lowercase s 116 071400 000163 73 115 SI Shift in 16 007400 000017 0F 15 SO Shift out 15 007000 000016 0E 14 SOH Start of heading 2 000400 000001 01 1 SP Space 33 020000 000040 20 32 STX Start of text 3 001000 000002 02 2 SUB Substitute 27 015000 000032 1A 26 SYN Synchronous idle 23 013000 000026 16 22 T Uppercase T 85 052000 000124 54 84 t Lowercase t 117 072000 000164 74 116 U Uppercase U 86 052400 000125 55 85 u Lowercase u 118 072400 000165 75 117 US Unit separator 32 017400 000037 1F 31 V Uppercase V 87 053000 000126 56 86 v Lowercase v 119 073000 000166 76 118 VT Vertical tabulation 12 005400 000013 0B 11 W Uppercase W 88 053400 000127 57 87 w Lowercase w 120 073400 000167 77 119 X Uppercase X 89 054000 000130 58 88 x Lowercase x 121 074000 000170 78 120 Y Uppercase Y 90 054400 000131 59 89 y Lowercase y 122 074400 000171 79 121 Z Uppercase Z 91 055000 000132 5A 90 z Lowercase z 123 075000 000172 7A 122 { Opening brace 124 075400 000173 7B 123 | Vertical line 125 076000 000174 7C 124 } Closing brace 126 076400 000175 7D 125 HP COBOL Manual for TNS and TNS/R Programs —522555-006 A- 9 ASCII Character Set ASCII Character Set in Alphabetic Order HP COBOL Manual for TNS and TNS/R Programs —522555-006 A -10 B Data Type Correspondence These tables contain the return value size generated by HP language compilers for each data type. Use this information when you need to specify values with the Accelerator ReturnValSize option. These tables are also useful if your programs use data from files created by programs in another language, or your programs pass parameters to programs written in callable languages. Refer to the appropriate SQL/MP or SQL/MX manual for a complete list of SQL data type correspondence. Also note that the return value sizes given in these tables do not correspond to the storage size of SQL data types. Note. COBOL includes COBOL 74, HP COBOL, and SCREEN COBOL unless otherwise noted. If you are using the Data Definition Language (DDL) utility to describe your files, see the Data Definition Language (DDL) Reference Manual for more information. Table B-1. Integer Types, Part 1 (page 1 of 2) HP C and HP C++ COBOL 8-Bit Integer 16-Bit Integer 32-Bit Integer char1 unsigned char int in the 16-bit data model int in the 32-bit or wide data model signed char short long unsigned unsigned long Alphanumeric-Edited PIC S9(n ) COMP or PIC 9(n ) COMP without P or V, 1 <=n <= 4 PIC S9(n ) COMP or PIC 9(n ) COMP without P or V, 5 <=n <= 9 Alphanumeric Index Data Item2 Index Data Item2 Numeric-Edited NATIVE-23 NATIVE-43 -- INTEGER4 INTEGER*4 Alphabetic Numeric DISPLAY FORTRAN INTEGER*2 1. Unsigned integer 2. Index Data Item is a 16-bit integer in COBOL 74 and a 32-bit integer in HP COBOL 3. HP COBOL only 4. INTEGER is normally equivalent to INTEGER*2. The INTEGER*4 and INTEGER*8 compiler directives redefine INTEGER HP COBOL Manual for TNS and TNS/R Programs —522555-006 B- 1 Data Type Correspondence Table B-1. Integer Types, Part 1 (page 2 of 2) Pascal 8-Bit Integer 16-Bit Integer 32-Bit Integer BYTE INTEGER LONGINT Enumeration, unpacked, <= 256 members INT16 INT32 CARDINAL1 Subrange, unpacked n…m, –2147483648 <=n and m <= 2147483647, but at least n or m outside -32768…32767 range Subrange, unpacked, n …m, 0 <= n and m <= 255 BYTE or CHAR value parameter Enumeration, unpacked, > 256 members Subrange, unpacked, n …m, -32768 <=n and m <= 32767, but at least n or m outside 0…255 range SQL/MP or SQL/MX CHAR NUMERIC(1)… NUMERIC(4) NUMERIC(5)… NUMERIC(9) PIC 9(1) COMP… PIC 9(4) COMP PIC 9(5) COMP …PIC 9(9) COMP SMALLINT INTEGER INT(32) TAL STRING INT pTAL UNSIGNED(8) INT(16) UNSIGNED(16) Return Value Size (Words) 1 1 2 1. Unsigned integer 2. Index Data Item is a 16-bit integer in COBOL 74 and a 32-bit integer in HP COBOL 3. HP COBOL only 4. INTEGER is normally equivalent to INTEGER*2. The INTEGER*4 and INTEGER*8 compiler directives redefine INTEGER HP COBOL Manual for TNS and TNS/R Programs —522555-006 B- 2 Data Type Correspondence Table B-2. Integer Types, Part 2 64-Bit Integer Bit Integer of 1 to 31 Bits Decimal Integer HP C and HP C++ long long -- -- COBOL PIC S9(n) COMP or PIC 9(n) COMP without P or V, 10 <= n <= 18 -- Numeric DISPLAY NATIVE-81 FORTRAN INTEGER*8 -- -- Pascal INT64 UNSIGNED(n), 1 <= n <= 16 DECIMAL INT(n), 1 <= n <= 16 SQL/MP or SQL/MX NUMERIC(10)… NUMERIC(18) -- DECIMAL (n,s) PIC 9(n) DISPLAY PIC 9(10) COMP… PIC 9(18) COMP LARGEINT TAL FIXED(0), INT(64) UNSIGNED(n), 1 <= n <= 31 -- 4 1 or 2 in TAL, 1 in other languages 1 or 2, depends on declared pointer size pTAL Return Value Size (Words) 1. HP COBOL only HP COBOL Manual for TNS and TNS/R Programs —522555-006 B- 3 Data Type Correspondence Table B-3. Floating, Fixed, and Complex Types 32-Bit Floating 64-Bit Floating 64-Bit Fixed Point 64-Bit Complex HP C and HP C++ float double -- -- COBOL -- -- PIC S9(n–s)v9(s) COMP or PIC 9(n–s)v9(s) COMP, 10 <= n <= 18 -- FORTRAN REAL DOUBLE PRECISION -- COMPLEX Pascal REAL LONGREAL -- -- SQL/MP or SQL/MX -- -- NUMERIC (n,s) PIC 9(n-s)v9(s) COMP -- TAL REAL REAL(64) FIXED(s), -19 <= s <= 19 -- pTAL REAL(32) Return Value Size (Words) 2 4 4 4 HP COBOL Manual for TNS and TNS/R Programs —522555-006 B- 4 Data Type Correspondence Table B-4. Character Types Varying Length Character String Character Character String HP C and HP C++ signed char unsigned char pointer to char struct { int len; char val [n] }; COBOL Alphabetic Numeric DISPLAY Alphanumeric-Edited Alphanumeric Numeric-Edited Alphabetic Numeric DISPLAY Alphanumeric-Edited Alphanumeric Numeric-Edited 01 name. 03 len USAGE IS NATIVE-21 03 val PIC X(n). FORTRAN CHARACTER CHARACTER array CHARACTER*n -- Pascal CHAR or BYTE value parameter PACKED ARRAY OF CHAR STRING(n) Enumeration, unpacked, <= 256 members FSTRING(n) Subrange, unpacked n…m, 0 <= n and m <= 255 SQL/MP or SQL/MX PIC X CHAR CHAR(n) PIC X(n) VARCHAR(n) TAL STRING STRING array -- 1 1 or 2, depends on declared pointer size 1 or 2, depends on declared pointer size pTAL Return Value Size (Words) 1. HP COBOL only HP COBOL Manual for TNS and TNS/R Programs —522555-006 B- 5 Data Type Correspondence Table B-5. Structured, Logical, Set, and File Types ByteAddresse dStructur e Word-Addressed Structure Logical (true or false) Boolean Set File HP C and HP C++ -- struct -- -- -- -- COBOL -- 01-level RECORD -- -- -- -- FORTRAN RECORD -- LOGICAL1 -- -- -- Pascal RECORD, bytealigned RECORD, wordaligned -- BOOLEAN Set File SQL/MP or SQL/MX -- -- -- -- -- -- TAL Byteaddressed standard STRUCT pointer Word-addressed standard STRUCT pointer -- -- -- -- 1 or 2, depends on declared pointer size 1 or 2, depends on declared pointer size 1 or 2, depends on compiler directive 1 1 1 pTAL Return Value Size (Words) 1. LOGICAL is normally defined as 2 bytes. The LOGICAL*2 and LOGICAL*4 compiler directives redefine LOGICAL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 B- 6 Data Type Correspondence Table B-6. Pointer Types Procedure Pointer Byte Pointer Word Pointer Extended Pointer HP C and HP C++ function pointer byte pointer word pointer extended pointer COBOL -- -- -- -- FORTRAN -- -- -- -- Pascal Procedure pointer Pointer, byteaddressed BYTEADDR Pointer, byteaddressed WORDADDR Pointer, extendedaddressed EXTADDR SQL/MP or SQL/MX -- -- -- -- TAL -- 16-bit pointer, byteaddressed 16-bit pointer, word-addressed 32-bit pointer pTAL PROCPTR 16-bit pointer, byteaddressed 16-bit pointer, word-addressed 32-bit pointer Return Value Size (Words) 1 or 2, depends on declared pointer size 1 or 2, depends on declared pointer size 1 or 2, depends on declared pointer size 1 or 2, depends on declared pointer size HP COBOL Manual for TNS and TNS/R Programs —522555-006 B- 7 Data Type Correspondence Table B-7. Address Types1 Procedure Pointer Byte Address Word Address Extended Address HP C and HP C++ -- -- -- -- COBOL -- -- -- -- FORTRAN -- -- -- -- Pascal -- -- -- -- SQL/MP or SQL/MX -- -- -- -- TAL -- -- -- -- pTAL PROCADDR BADDR WADDR EXTADDR SGBADDR SGWADDR SGXBADDR SGXWADDR CBADDR CWADDR 1 or 2, depends on declared pointer size 1 or 2, depends on declared pointer size Return Value Size (Words) 1 or 2, depends on declared pointer size 1 or 2, depends on declared pointer size 1. Only the pTAL compiler supports address types HP COBOL Manual for TNS and TNS/R Programs —522555-006 B- 8 Glossary 16-bit addressing. Referencing a data item or parameter by using a 16-bit address (also called standard addressing). Compare to 32-bit addressing. 32-bit addressing. Referencing a data item or parameter by using a 32-bit address (also called extended addressing). Compare to 16-bit addressing. abbreviated combined relation condition. A combined condition that results from the explicit omission of a common subject, a common relational operator, or both in a consecutive sequence of relation conditions. accelerate. To speed up emulated execution of a TNS object file by applying the Accelerator for TNS/R system execution or the TNS Object Code Accelerator (OCA) for TNS/E system execution before running the object file. accelerated mode. See TNS accelerated mode. accelerated object file. A TNS object file that, in addition to its TNS instructions (in the TNS region) and symbol information (in the symbol region), has been augmented by the Accelerator with equivalent but faster MIPS RISC instructions (in the MIPS region), the Object Code Accelerator (OCA) with equivalent but faster Intel® Itanium® instructions (in the Itanium instruction region), or both. Accelerator. A program optimization tool that processes a TNS object file and produces an accelerated object file that also contains equivalent MIPS RISC instructions (called the MIPS region). TNS object code that is accelerated runs faster on TNS/R processors than TNS object code that is not accelerated. See also TNS Object Code Accelerator (OCA). access mode. The form of file access permitted for a user or process. actual decimal point. The physical representation of the decimal point position in a data item, as either a period (.) or a comma (,). Compare to assumed decimal point. actual parameter. A data item that a calling program passes to a called program. Compare to formal parameter. aligned. In native mode, a data item is aligned if its address is a multiple of its size. For example, a four-byte data item is aligned if its byte address is a multiple of four. alphabet-name. A user-defined word assigned to a specific character set or collating sequence or both in the SPECIAL-NAMES paragraph of the Environment Division. alphabetic character. Any uppercase or lowercase letter or a space. alphanumeric character. A letter, digit, or hyphen. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -1 Glossary alternate record key alternate record key. A data item, other than the prime record key, whose value identifies a record in a structured file. API. See application program interface (API). application program interface (API). A set of services (such as programming language functions or procedures) that are called by an application program to communicate with other software components. For example, an application program in the form of a client might use an API to communicate with a server program. archive file. A file that contains a collection of files. An archive file is built by using the ar facility. For information about the ar facility, see the nld Manual. arithmetic expression. One of: • • • • • An identifier of a numeric elementary item A numeric literal Two or more such identifiers or literals separated by arithmetic operators Two arithmetic expressions separated by arithmetic operator An arithmetic expression enclosed in parentheses arithmetic operation. The process caused by the execution of an arithmetic statement, or the evaluation of an arithmetic expression, that results in a mathematically correct solution to the arguments presented. arithmetic operator. One of: Operator Meaning + Addition – Subtraction * Multiplication / Division ** Exponentiation arithmetic statement. A statement that causes an arithmetic operation to be executed. The arithmetic statements are the ADD, SUBTRACT, MULTIPLY, DIVIDE, and COMPUTE statements. assumed decimal point. A logical decimal point position that does not occupy a character position in a data item or have any physical representation. Compare to actual decimal point. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -2 Glossary at-end condition at-end condition. A condition that occurs at these times: • • • During the execution of a READ statement for a sequential file, when no more records exist During the execution of a RETURN statement, when no next logical record exists for the associated sort file or merge file During the execution of a SEARCH statement, when the search ends without satisfying a condition specified in any of the associated WHEN phrases BIND. A program invoked during system generation that creates TNS object (file code 100) system code files and system library files. Binder. A programming utility that combines one or more compilation units’ TNS object code files to create an executable TNS object code file for a TNS program or library. Used only with TNS object files. BINSERV. The form of Binder that the COBOL85 compiler uses. block. A grouping of one or more system enclosures that an HP NonStop™ S-series system recognizes and supports as one unit. A block can consist of either one processor enclosure, one I/O enclosure, or one processor enclosure with one or more I/O enclosures attached. On disk, a block is a physical unit of data composed of one or more logical records and their associated control information transferred between the file system and a disk volume as a unit. A record cannot span blocks. See also data block and code block. On tape, a block is a physical record. body. See page body. bottom margin. An empty area of a logical page that follows the page body. C85LIB. The object file that contains the COBOL85 run-time routines that can be bound into the executable object file built from a COBOL program. called program. A program whose name appears in a CALL or ENTER statement in a calling program. calling program. A program that contains a CALL or ENTER statement. character. The basic, indivisible unit of data or of source program text in the COBOL language. character position. The amount of physical storage required to store in standard data format a single character of a data item whose usage is DISPLAY (one byte). character-string. A sequence of contiguous characters that form a COBOL word, literal, PICTURE character-string, or comment-entry. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -3 Glossary CISC CISC. See complex instruction-set computing (CISC). class condition. The proposition that a data item’s contents are all alphabetic or all numeric. A process can determine whether a class condition is true or false. clause. An ordered set of consecutive COBOL character-strings that specifies an attribute of an entry. CLIBOBJ. The object file containing the COBOL run-time routines that can be bound into the executable object file built from a COBOL program. client. A software process, hardware device, or combination of the two that requests services from a server. Often, the client is a process residing on a programmable workstation and is the part of an application that provides the user interface. The workstation client might also perform other portions of the application logic. A client that runs only in the Guardian environment using an interface defined by HP is called a requester. COBOL character set. One of: Characters Character Name Characters Character Name 0 ... 9 Digit , Comma (decimal point) A ... Z Uppercase Letter ; Semicolon a ... z Lowercase Letter . Period (decimal point) Space (blank) " Quotation mark + Plus sign ( Left parenthesis – Minus sign (hyphen) ) Right parenthesis * Asterisk > Greater than symbol / Slash (slant, virgule) < Less than symbol = Equal sign : Colon $ Dollar sign Also, in a nonnumeric literal, comment, or comment-entry, any ASCII character. COBOL file name. The name by which an HP COBOL program recognizes a file. Compare to system file name. COBOL word. A character-string up to 30 characters long that forms a user-defined word, system file name, or reserved word. COBOLEX0, COBOLEX1, COBOLEXT. The object files of dummy routines that enable the COBOL compiler to accept ENTER statements whose references to system routines are to be resolved at loading time. COBOLEX0 represents the latest RVU; COBOLEX1, the next-to-latest; and COBOLEXT, the second-next-to-latest. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -4 Glossary COBOLLIB COBOLLIB. The object file of utility routines for HP COBOL, including COBOLSPOOLOPEN, COBOLFILEINFO, CREATEPROCESS, and the Saved Message Utility (SMU) routines. code block. In COBOL, the object code that the compiler generates from a single source program; in binding or linking, the smallest separately relocatable unit of code in an object file. collating sequence. The order of the characters of a character set, for the purpose of sorting, merging, or comparing. column. A character position within a print line. The leftmost character position is column 1. combined condition. Two or more conditions connected by the logical operator AND or OR. comma separator. A comma (,) followed by one or more spaces. command interpreter. The operating system’s primary user interface to an HP computer system, through which you can use system utilities and run programs. comment. A line in a source program that begins with an asterisk (*) or a slash (/) in the indicator area and contains any combination of ASCII characters in area A and area B. comment-entry. An entry in the Identification Division that can be any combination of ASCII characters. common program. A program that is directly contained in another program that can be called from any program directly or indirectly contained in that other program. Common Run-Time Environment (CRE). A set of services implemented by the CRE library that supports mixed-language programs. Compare to non-CRE environment. Common Run-Time Environment (CRE) library. A collection of routines that supports requests for services managed by the CRE, such as I-O and heap management, math and string functions, exception handling, and error reporting. CRE library routines can be called by HP C, HP COBOL, FORTRAN, Pascal, and pTAL user routines and runtime libraries. compatible programs. Two programs are compatible if one can call the other. Compatible programs must run in the same environment (the Common Run-Time Environment (CRE) or the non-CRE environment) and on the same type of machine (TNS architecture, TNS/R architecture, or TNS/E architecture). compilation. The process of translating a source file to an object file; the joint activity of the compiler and its processes. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -5 Glossary compilation unit compilation unit. A set of source files compiled in one call to a compiler, including any compiler directives in the command that starts the compiler but not including any object files that the compiler summons to resolve external references; in COBOL, one or more source programs. compile time. The time at which a compiler translates a source file into an object file. compiler directive. An instruction to a compiler. complex condition. A condition in which one or more logical operators act upon one or more conditions. See abbreviated combined relation condition, negated simple condition, and combined condition. complex instruction-set computing (CISC). A processor architecture based on a large instruction set, characterized by numerous addressing modes, multicycle machine instructions, and many special-purpose instructions. Compare to reduced instructionset computing (RISC) and explicitly parallel instruction set computing (EPIC). condition. A proposition about the values of variables and literals of a program for which an executing program can determine a truth value. condition-name. One of these: • • A user-defined word assigned to a specific value, set of values, or range of values within the complete set of values that a conditional variable can have A user-defined word assigned to the status of a switch condition-name condition. A proposition that the value of a conditional variable is a member of the set of values attributed to a condition-name associated with the variable, for which an executing program can determine a truth value. conditional expression. A simple condition or complex condition specified in an IF, PERFORM, or SEARCH statement. conditional statement. A statement that tells a process to determine the truth value of a condition and to base subsequent execution of the object program on the truth value. conditional variable. A data item that has one or more values to which the program assigns a condition-name. content parameter. A parameter that is passed by content (also called a value parameter). A called program cannot permanently change the value of a content parameter. Compare to reference parameter. contiguous. See contiguous data items. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -6 Glossary contiguous data items contiguous data items. Two or more data items that have a hierarchical relationship to each other, which you describe by consecutive data description entries at the same level (except consecutive level-01 entries) in the Data Division; for example: 01 ABLE. 02 BAKER 02 CHARLIE 02 DOG. 04 EASY 04 FOX 02 GOOSE PIC X(2). PIC X(2). PIC X(2). PIC X(2). PIC X(2). BAKER, CHARLIE, DOG, and GOOSE are contiguous; EASY and FOX are contiguous. counter. A data item in which a process stores a number, or number representation, in a way that the process can: • • Increase or decrease the number by the value of another number Change or reset the number to zero or to an arbitrary positive or negative value CRE. See Common Run-Time Environment (CRE). CRE library. See Common Run-Time Environment (CRE) library. CRE program. A program that runs in the Common Run-Time Environment (CRE). If a CRE program was compiled by the COBOL85 compiler, the directive ENV COMMON or ENV LIBRARY was specified. Compare to non-CRE program. CROSSREF utility program. The HP software product that produces cross-reference listings of source programs. It can be used directly or initiated by a compiler directive. currency sign. The character $. currency symbol. The character defined by the CURRENCY SIGN clause in the SPECIALNAMES paragraph or, if the program has no CURRENCY SIGN clause, the currency sign. current record. The record currently available in the record area associated with a file. current record pointer. A conceptual entity that specifies the next record to be accessed in a file. data block. The smallest separately relocatable unit of data in an object file; in COBOL, a collection of data that the COBOL compiler groups and names. Data Definition Language (DDL). An HP language that describes the record and file structures of a database. When a database is described in DDL, the DDL compiler can create a COPY library for use in COBOL compilations and other libraries for other languages. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -7 Glossary data item data item. One of these: • • A unit of storage that can hold a character (or set of contiguous characters) or a computational value defined as a unit of data by a COBOL program. The character, set of characters, or value that occupies such a unit of storage. data-name. One of these: • • A user-defined word that names a data item described in a data description entry. In a syntax description, a word that you cannot subscript, index, or qualify unless the explanation of the format says that you can. data structure. A named contiguous set of data items (elementary items or other data structures). deadlock. One of these situations: • • • Two processes cannot proceed because each is waiting for a reply from the other. Two transactions cannot proceed because each is waiting for the other to release a lock. A block to data access caused by processes contending for the same data. If two servers are deadlocked, their respective requesters are also deadlocked because neither requester receives a reply from its server. Debug. The HP machine-oriented, run-time debugging tool. DEBUG-ITEM. An obsolete special register that the compiler generates when the debugger is used. debugging line. Any line that has a D or d in its indicator field, which line the compiler handles as a comment unless you specify the DEBUGGING MODE clause of the SOURCE-COMPUTER paragraph in the Environment Division. debugging section. A section that contains a USE DEBUGGING statement. declaratives. A set of one or more special-purpose sections at the beginning of the Procedure Division preceded by the keyword DECLARATIVES and followed by the keywords END DECLARATIVES, in which each section consists of a section header followed by a USE statement and zero or more associated paragraphs. Other sections without USE statements can appear in the declaratives portion and can be performed by statements in the declarative sections. de-edit. The logical removal of all editing characters from a numeric edited numeric-edited item to determine that item’s unedited numeric value. delimited-scope statement. Any statement that includes its explicit scope terminator. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -8 Glossary delimiter delimiter. A character or sequence of contiguous characters that identify the beginning or end of a string of characters but are not part of the string of characters. digit position. The amount of physical storage required to store a single digit, an amount that depends on the USAGE of the data item described to hold the digit. directive. An instruction to a compiler (also called a compiler directive). directive line. In HP COBOL, a line in a source program that begins with a question mark (?) and contains one or more compiler directives, separated by semicolon separators. division. A division header followed by zero or more sections or paragraphs formed according to specific rules; any of the four major parts of a COBOL program— Identification, Environment, Data, and Procedure divisions. division header. A combination of words, followed by a period (.), that indicates the beginning of a division; any of: • • • • IDENTIFICATION DIVISION. ENVIRONMENT DIVISION. DATA DIVISION. PROCEDURE DIVISION. DLL. See dynamic-link library (DLL). dynamic access. An access mode in which the process can read specific logical records from a disk file sequentially or nonsequentially and write such records to the file nonsequentially while the same OPEN statement is active for that file. Compare to sequential access and random access. dynamic file. A file whose COBOL file name is associated with its system file name at run time. dynamic-link library (DLL). A PIC library of functions or data for use by other PIC loadfiles. In UNIX, this type of file is called a shared object file or dynamic shared object (DSO). EDIT. The HP text file editor program. EDIT file. In the Guardian file system, an unstructured file with file code 101. An EDIT file can be processed by either the EDIT or PS Text Edit (TEDIT) editor. An EDIT file typically contains source program or script code, documentation, or program output. Open System Services (OSS) functions can open an EDIT file only for reading. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -9 Glossary editing characters editing characters . One of: Character Meaning Character Meaning B Space Z Zero suppress 0 Zero * Check protect + Plus $ Currency sign - Minus , Comma (decimal point) CR Credit / Slash (slant, virgule) DB Debit eld utility. A utility that collects, links, and modifies code and data blocks from one or more position-independent code (PIC) object files to produce a target TNS/E native object file. See also ld utility and nld utility. elementary item. A data item whose description has no logical subdivisions into other items. ENABLE. A utility that SCREEN COBOL uses to generate an interactive update application under the Pathway/TS transaction processing software. ENFORM. A query/report writer system that has an English-like relational query language; a host-language interface allows a COBOL program to call a compiled ENFORM query and receive a sequence of records collected or created by ENFORM. enoft utility. A utility that reads and displays information from TNS/E native object files. See also noft utility. Enscribe. The HP database record manager; provides access to and manipulation of records in disk files. EPIC. See explicitly parallel instruction set computing (EPIC). executable object file. See loadfile. execution time. Denotes events that occur at the time a process executes an object program (also called object time or run time). Expand. The HP data communication network, an extension of the operating system. explicit scope terminator. A reserved word that terminates the scope of a particular Procedure Division statement. explicitly parallel instruction set computing (EPIC). A processor architecture in which the instruction stream encodes what can be done in parallel (so that the hardware need not do this). Compare to complex instruction-set computing (CISC) and reduced instruction-set computing (RISC). expression. An arithmetic expression or conditional expression. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -10 Glossary EXTEND mode EXTEND mode. The state of a file after a process executes an OPEN statement including an EXTEND phrase for the file and before the process executes a CLOSE statement without the REAL or UNIT phrase for the file, allowing the process to extend the file by appending additional records. extended addressing. Data access through an extended (32-bit) pointer (also called 32-bit addressing). Compare to standard addressing. Extended-Storage Section. The section of the Data Division that describes data items that the process stores in the segment of extended memory a program can address on an HP system. (The items can be noncontiguous data items or records.) extended storage. An additional segment of data storage available on NonStop systems. external data. The data described in a program as external external data items and external file connectors. external data item. A data item that is described as part of an external record in one or more programs of a run unit and that itself can be referenced from any program in which it is described. external data record. A logical record that is described in one or more programs of a run unit and whose constituent data items can be referenced from any program in which they are described. external file connector. A file connector that is accessible to one or more object programs in the run unit. external reference. The call to a routine that is not present in the source file that a compiler is translating. external switch. A software device, defined and named by HP, that is used to indicate that one of two alternate states exists. Fast I-O. See HP COBOL Fast I-O. fault-tolerant facility. The software provided by HP and used by a process to cause the process to execute as a fault-tolerant process pair. figurative constant. A compiler-generated value that you can reference by one or more specific reserved words. file. An object to which data can be written or from which data can be read. A file has attributes such as access permissions and a file type. In the Open System Services (OSS) environment, file types include regular file, character special file, block special file, FIFO, and directory. In the Guardian environment, file types include disk files, processes, and subdevices. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -11 Glossary file connector file connector. A storage area that contains information about a file; the linkage between a file name and a physical file and between a file name and its associated record area. FILE-CONTROL. The name of an Environment Division paragraph that declares the data files for the program. file-control entry. An entry in the FILE-CONTROL paragraph in the Input-Output Section of the Environment Division composed of a SELECT clause followed by one or more clauses that declare the relevant physical attributes of a file. file description entry. An entry in the File Section of the Data Division composed of the level indicator FD followed by a file name and a set of file clauses, as required. file name. A string of characters that uniquely identifies a file. In the PC environment, file names for disk files normally have at least two parts (the disk name and the file name); for example, B:MYFILE. In the Guardian environment, disk file names include an Expand node name, volume name, subvolume name, and file identifier; for example, \NODE.$DISK.SUBVOL.MYFILE. In the Open System Services (OSS) environment, a file is identified by a pathname; for example, /usr/john/workfile. See also filename and file-name. file-name. A user-defined word that names a file described in a file description entry or a sort-merge file description entry in the File Section of the Data Division. file organization. The permanent logical structure established for a file when a process creates it. file position indicator. A conceptual entity that either: • • • • • • • Contains the value of the current key within the key of reference for an indexed file Contains the record number of the current record for a sequential file Contains the relative record number of the current record for a relative file Indicates that no next logical record exists Indicates that the number of significant digits in the relative record number is larger than the size of the relative key Indicates that an optional input file is not present Indicates that no valid next record has been established File Utility Program (FUP). The file utility program provided by HP. filename. In the Open System Services (OSS) environment, a component of a pathname containing any valid characters other than slash (/) or null. See also file-name and file name. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -12 Glossary fixed attributes fixed attributes. Information about a file that is established when a process creates a file and that cannot subsequently be changed during the existence of the file. These attributes include the organization of the file (sequential organization, relative organization, or indexed organization), the prime record key, the alternate record keys, the code set, the minimum and maximum record size, the record type (fixed-length record or variable-length record), the collating sequence of the keys for an indexed file, the blocking factor, the padding character, and the record delimiter. fixed-length record. A record associated with a file whose file description entry or sortmerge file description entry requires that all records contain the same number of character positions. fixup. A phase of the program-loading operation performed by the operating system in which external references to entry points in other code segments are resolved. flag. In a UNIX or Open System Services (OSS) command, a character sequence that begins with a hyphen and is processed as a unit. footing area. The part of the page body (of a logical page) adjacent to the bottom margin. formal parameter. A parameter defined by a called program. Compare to actual parameter. format. A specific arrangement of a set of data. FUP. See File Utility Program (FUP). global name. A name that is declared in only one program but that can be referenced from that program and from any program directly or indirectly contained within that program. These names can be global names: condition-names, data-names, file-names, recordnames, and some special registers. Compare to local name. Guardian. An environment available for interactive or programmatic use with the HP NonStop™ operating system. Processes that run in the Guardian environment usually use the Guardian system procedure calls as their application program interface. Interactive users of the Guardian environment usually use the HP Tandem Advanced Command Language (TACL) or another HP product’s command interpreter. Compare to Open System Services (OSS). Guardian environment. The Guardian application program interface (API), tools, and utilities. GUARDIAN-ERR. A special register associated with a run unit, which the process updates each time it executes an input-output statement. The contents of GUARDIAN-ERR is the value delivered to the COBOL run-time routines by the Guardian operating system upon its completion of the requested input-output statement. high-order end. The leftmost character of a string of characters. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -13 Glossary high PIN high PIN. A process identification number (PIN) that is greater than 255. Compare to low PIN. HP COBOL Fast I-O. A fast form of sequential block buffering in which run-time routines handle the record deblocking. HP COBOL program. A program written in the HP COBOL language. It can be compiled with the COBOL85, NMCOBOL, or ECOBOL compiler. HP NonStop™ operating system. The operating system for HP NonStop systems. HP NonStop™ Transaction Management Facility (TMF). HP software that provides transaction protection and database consistency in demanding online transaction processing (OLTP) and decision-support environments. It gives full protection to transactions that access distributed SQL/MP, SQL/MX, and Enscribe databases, as well as recovery capabilities for transactions, online disk volumes, and entire databases. HP Tandem Advanced Command Language (TACL). The user interface to the NonStop operating system. TACL is both a command interpreter and a command language. Users can write programs in TACL that perform complex tasks simply or provide a consistent user interface across independently programmed applications. HP Transaction Application Language (TAL). A systems programming language with many features specific to stack-oriented TNS systems. identifier. A data name followed, as required, by the combination of qualifiers, subscripts, and indexes necessary to make a unique reference to a data item. imperative statement. A statement that either begins with an imperative verb and specifies an unconditional action for a process to take or is a delimited-scope statement. An imperative statement can consist of a sequence of imperative statements. implicit scope terminator. A period (.) that terminates the scope of any preceding unterminated statement, or a phrase of a statement that by its occurrence indicates the end of the scope of any statement contained within the preceding phrase. index. A computer storage position containing a value that identifies a particular table element; an index-name and an index data item both designate such a storage position. index data item. A data item described with a USAGE INDEX phrase that a process uses to hold a value associated with an index-name. index-name. A user-defined word specified in an INDEXED clause of a table description to refer to an index associated with the table. indexed file. A file that has indexed organization. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -14 Glossary indexed organization indexed organization. A permanent logical file structure in which a process can identify each record by the value of one or more keys within the record. IN file. The input file of a process, either specified explicitly at process start time or inherited from the parent process. initial program. A program that is placed into an initial state every time the program is called in a run unit. initial state. The state of a program when it is first called in a run unit. input file. A file open in the INPUT mode. INPUT mode. The state of a file after a process executes an OPEN statement including an INPUT phrase for the file and before the process executes a CLOSE statement (without the REEL or UNIT phrase for the file), allowing the process to read records from the file. input-output file. A file open in the I-O mode. Input-Output Section. A section of the Environment Division that names the files and the external media required by an object program and that provides information a process needs for transmitting and handling data when it executes the object program. input-output statement. A statement that causes files to be processed by performing operations upon individual records or upon the file as a unit. The input-output statements are: ACCEPT with mnemonic-name, CLOSE, DELETE, DISPLAY, OPEN, READ, REWRITE, START, and WRITE. input procedure. A Procedure Division section or group of sections executed during a SORT operation; the statements of the section generate or obtain the records to be sorted, and pass the records to the sort utility one at a time using the RELEASE statement. When the input procedure terminates by passing through the end of its final paragraph, that signals the end of the set of records to be sorted. integer. A numeric literal or a numeric item that does not include any digit positions to the right of the assumed decimal point; in syntax diagrams, an unsigned numeric literal that does not equal zero, unless the explanation of a format says otherwise. Intel® Itanium® instructions. Register-oriented Itanium instructions that are native to and directly executed by a TNS/E system. Itanium instructions do not execute on TNS and TNS/R systems. Compare to TNS instructions and MIPS RISC instructions. TNS Object Code Accelerator (OCA) produces Itanium instructions to accelerate TNS object code. A TNS/E native compiler produces native-compiled Itanium instructions when it compiles source code. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -15 Glossary internal data internal data. The data described in a program, including all internal data items and internal file connectors. Items described in the Linkage Section of a program are handled as internal data. internal data item. A data item that is described in one program in a run unit. An internal data item can have a global name. internal file connector. A file connector that is accessible to only one object program in the run unit. invalid key condition. A condition caused at object time when the process determines that a specific value of the key associated with a structured file is invalid—has a value to which no record in the associated file corresponds, or has a value which exceeds the bounds of the file, or specifies a value that would cause a duplicate key value in the file where no duplicate key values are allowed. I-O-CONTROL. The name of an Environment Division paragraph that specifies object program requirements for specific input-output techniques, rerun points, several data files sharing the same areas, and multiple file storage on a single input-output device. I-O mode. The state of a file after a process executes an OPEN statement including an I-O phrase for the file and before the process executes a CLOSE statement (without the REEL or UNIT phrase for the file), allowing the process to read records from the file and write records to the file. I-O status. A conceptual entity that contains the two-character value indicating the resulting status of an input-output operation. This value is made available to the program through the use of the FILE STATUS clause in the file-control entry for the file. job. The output from a process that a spooler receives and stores on a disk, queued for delivery to a print process. key. A data item that identifies either: • • The location of a record A set of data items whose values a process can use to order data key of reference. The prime record key or alternate record key that a process is currently using to access records in a structured file. keyword. A character sequence recognized by a command process. language-specific run-time environment. A set of services implemented by the run-time library of each language; a non-CRE environment. Without the CRE, HP C, HP COBOL, FORTRAN, Pascal, and pTAL programs each have their own language-specific run-time environments. These language-specific run-time environments are often incompatible with each other. Compare to Common Run-Time Environment (CRE). HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -16 Glossary language-specific run-time library language-specific run-time library. A collection of routines outside the CRE that supports requests from a specific language for services such as I-O and heap management, math and string functions, exception handling, and error reporting. ld utility. A utility that collects, links, and modifies code and data blocks from one or more position-independent code (PIC) object files to produce a target TNS/R native object file. See also eld utility and nld utility. letter. A character belonging to one of these two sets: Uppercase letters: A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z Lowercase letters: a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z level indicator. Two alphabetic characters that identify a specific type of entry in the Data Division: file description entry or sort-merge file description entry. level-number. A user-defined word that indicates the position of a data item in the hierarchical structure of a logical record (a number in the range 1 through 49); a userdefined word that indicates the special properties of a data description entry (the numbers 66, 77, and 88). library-name. A user-defined word that names a COPY library file for the compiler to copy text from during a compilation. LINAGE-COUNTER. A special register that the compiler generates for each file description that has a LINAGE clause. At any given time, a LINAGE-COUNTER contains the value of the current line number within the current page body. line sequential file. A file that has line sequential organization (code 180) that is compatible with the system text editor of the Open System Services (OSS) environment (also called OSS ASCII text file). LINE-COUNTER. A special register that is not available in HP COBOL. Linkage Section. A section of the Data Division in a called program that describes data items available from the calling program (the items to which both programs can refer). linkfile. An object file that requires linking with other object files before execution (also called a nonexecutable object file). Compare to loadfile. linking. The operation of examining, collecting, connecting, and modifying code blocks and data blocks from one or more object files to produce one target file. literal. A character-string whose ordered set of characters implies its value. loadfile. An object file that is ready for immediate execution (also called an executable object file). Compare to linkfile. Program files, user libraries, shared run-time libraries, and dynamic link libraries are loadfiles. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -17 Glossary loading loading. The operation of mapping an object file into the memory of a process. local name. A name that is not global, and therefore, can be referenced only by the program that declares it. Compare to global name. logical page. A conceptual page of a report consisting of a top margin area, a body (including a footing area), and a bottom margin; all governed by the LINAGE clause of the file description entry. logical operator. Any of these reserved words: • • • AND (logical connector) OR (logical connector) NOT (logical negation) logical record. The most inclusive data item, either an elementary item or data structure that has a level number of 01; in the File Section, the unit of data read from, written to or removed from a file by a single READ, WRITE, REWRITE, or DELETE statement. low PIN. A process identification number (PIN) that ranges from 0 through 254. Compare to high PIN. main program. The first program to execute when a run unit is run. The main program determines the run-time environment for a program. man page. See reference page. map. A tabular representation of the elements of a program. merge file. A collection of records for a process to merge during execution of a MERGE statement; a file declared in the sort-merge file description entry, and created and used only by the merge function. migrate. To take a source program that was compiled with one compiler and recompile it with another compiler so that the resulting object program runs on another platform. MIPS RISC instructions. Register-oriented 32-bit machine instructions in the MIPS-1 RISC instruction set that are native to and directly executed on TNS/R systems. MIPS RISC instructions do not execute on TNS systems and TNS/E systems. Compare to TNS instructions and Intel® Itanium® instructions. Accelerator-generated MIPS RISC instructions are produced by accelerating TNS object code. Native-compiled MIPS RISC instructions are produced by compiling source code with a TNS/R native compiler. misaligned. In TNS mode and accelerated mode, an erroneous address that is odd-byte aligned. In native mode, an inefficient address that is not aligned. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -18 Glossary mixed-language program mixed-language program. A program made up of routines compiled from more than one programming language. A program with HP C routines and TAL routines is an example of a mixed-language program. mnemonic-name. A user-defined word you associate with an implementor name in the SPECIAL-NAMES paragraph of the Environment Division and use elsewhere in the program to refer to the implementor name. native character set. The ASCII character set. native link editor. See nld utility. native mode. TNS/R native mode or TNS/E native mode. native object code. TNS/R native object code or TNS/E native object code. native object file. TNS/R native object file or TNS/E native object file. native object file tool. See noft utility. native PIC linker. See ld utility. native process. A TNS/R native process or TNS/E native process. NATIVE-n data format. NATIVE-2, NATIVE-4, and NATIVE-8 data formats, collectively. negated combined condition. A combined condition, within parentheses, immediately preceded by the NOT logical operator. negated simple condition. A simple condition immediately preceded by the NOT logical operator. next executable sentence. The next sentence to which the process is to transfer control after it finishes executing the current statement. next executable statement. The next statement to which the process is to transfer control after it finishes executing the current statement. next record. The record that logically follows the current record of a file; if the file is being accessed sequentially, the next record in the file; if the file is being accessed randomly, the record to which the key of reference refers; if the file is being accessed dynamically, the next record according to the key of reference. nibble. Half of a byte or computer character, four bits. nld utility. A utility that collects, links, and modifies code and data blocks from one or more object files to produce a target TNS/R native object file. See also ld utility. noft utility. A utility that reads and displays information from TNS/R native object files. See also to enoft utility. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -19 Glossary noncontiguous items noncontiguous items. Elementary data items that bear no hierarchical relationship to other items and that you describe in the Working-Storage, Extended-Storage, and Linkage Sections of the Data Division: • • Level 77 items Level 01 items (each one of which is noncontiguous with respect to each other one) non-CRE environment. A set of services implemented by the COBOL85 run-time library. Without the CRE, HP C, HP COBOL, FORTRAN, Pascal, or pTAL programs each have their own language-specific run-time environments. These language-specific run-time environments are often incompatible with each other. Compare to Common Run-Time Environment (CRE). non-CRE program. A program that runs in its own language-specific run-time environment (as opposed to the CRE). If it is an HP COBOL program, it was compiled with the COBOL85 compiler and the directive ENV OLD. Compare to CRE program. nonexecutable object file. See linkfile. nonnumeric literal. A character-string, delimited by quotation marks, that can include any ASCII character (with any quotation mark within the character-string represented by two contiguous quotation marks). non-PIC. See position-dependent code (non-PIC). nonshared code. See position-dependent code (non-PIC). NonStop operating system. See HP NonStop™ operating system. NonStop Series architecture. See TNS architecture. NonStop Series/Itanium architecture. See TNS/E architecture. NonStop Series/RISC architecture. See TNS/R architecture. numeric character. Any of the digits 0 through 9. numeric-edited item. A data item described to contain numeric characters and the special editing signs, which are: B, P, Z, CR, DB, plus (+), minus (–), asterisk (*), slash (/), dollar sign ($), period (.), and comma (,). numeric item. A data item described to contain only numeric characters and, if signed, a plus sign (+), minus sign (–), or other representation of an operational sign. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -20 Glossary numeric literal numeric literal. A string of these characters: • • • One or more digits (required) A decimal point in any character position except the rightmost (optional) An algebraic sign in the leftmost character position (optional) OBEY command file. An EDIT file that contains a series of commands and serves as a source of command input. OBJECT-COMPUTER. The name of an Environment Division paragraph that describes the computer environment in which you can execute the object program. object file. A file generated by a compiler, binder, or linker that contains machine instructions and other information needed to construct the executable code spaces and initial data for a process. The file can be a complete program that is ready for immediate execution (an executable object file), or it can be incomplete and require binding or linking with other object files before execution (a nonexecutable object file). An object file can contain more than one object program. object library. An object file to be used as a source of object programs for binding or linking. object of entry. A set of operands and reserved words that immediately follows the subject of a Data Division entry. object program. A set or group of executable machine language instructions and other material designed to interact with data to provide problem solutions; the machine language result of the operation of a COBOL compiler on a source program. open mode. The state of a file after a process executes an OPEN statement for the file and before the process executes a CLOSE statement (without the REEL or UNIT phrase) for the file, governing the types of operations a process can perform on the file; one of these modes, which you can specify in an OPEN statement: • • • • INPUT mode OUTPUT mode I-O mode EXTEND mode OSS ASCII text file. See line sequential file. Open System Services (OSS). An open system environment available for interactive or programmatic use with the NonStop operating system. Processes that run in the OSS environment use the OSS application program interface; interactive users of the OSS environment use the OSS shell for their command interpreter. Compare to Guardian. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -21 Glossary operand operand. In syntax formats, any lowercase word or words that appear in a statement or entry format; an implied reference to data or to a literal value. operational sign. An algebraic sign associated with a numeric data item or a numeric literal to indicate whether its value is positive or negative. optional file. An input file that you declare is not necessarily present during each execution of the object program, the presence or absence of which file the object program determines during execution. optional word. A reserved word that appears in a syntax diagram of a statement or entry only to improve readability and that you can omit when you use the statement or entry in a source program. OSS environment. The application program interface (API), tools, and utilities of the Open System Services (OSS). OUT file. The output file of a process, either specified explicitly at process start time or inherited from the parent process. output file. A file open in either the output mode or the extend mode. OUTPUT mode. The state of a file after a process executes an OPEN statement that includes an OUTPUT phrase for that file and before the process executes a CLOSE statement (without a REEL or UNIT phrase for that file); EXTEND mode includes the capabilities of OUTPUT mode. output procedure. A Procedure Division section or group of sections executed during either SORT or MERGE statements; obtains the ordered records from the SORT or MERGE operation by executing a RETURN statement, the end of the set of records being signalled by the EOF condition, which can be tested for with the AT END phrase of the RETURN statement; receives control (1) during execution of a SORT statement, after the sort operation is complete, or (2) during execution of a MERGE statement, after the merge function selects the next record in merged order. padding character. An alphanumeric character used to fill the unused character positions in a block. HP COBOL does not pad records. page. One of these: • • On disk, a contiguous block of storage starting on a sector boundary and containing 2,048 bytes; a unit of disk allocation. In memory, a division of memory consisting of 2,048 bytes; the 2-byte pages of physical memory are numbered from 0 through 1,023. page body. The part of a logical page in which you can put lines or spaces. PAGE-COUNTER. A special register that is not available in HP COBOL. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -22 Glossary paragraph paragraph. In the Procedure Division, a paragraph-name followed by a period (.) and zero, one, or more sentences; in the Identification Division or Environment Division, a paragraph header followed by zero, one, or more entries. paragraph header. A reserved word, followed by a period (.), that indicates the beginning of a paragraph in the Identification Division or Environment Division. The paragraph headers in the Identification Division are: • • • • • • PROGRAM-ID AUTHOR INSTALLATION DATE-WRITTEN DATE-COMPILED SECURITY The paragraph headers in the Environment Division are: • • • • • • SOURCE-COMPUTER OBJECT-COMPUTER SPECIAL-NAMES FILE-CONTROL I-O-CONTROL RECEIVE-CONTROL paragraph-name. A user-defined word that identifies and begins a paragraph in the Procedure Division. parameter. A name specified in a prepared command for which the user substitutes a value when executing the command. pathname. In the Open System Services (OSS) file system and Network File System (NFS), the string of characters that uniquely identifies a file within its file system. A pathname can be either relative or absolute. See also ISO/IEC IS 9945-1:1990 (ANSI/IEEE Std. 1003.1-1990 or POSIX.1), Clause 2.2.2.57. Pathway/TS. An HP product that provides tools for developing and interpreting screen programs to support online transaction processing (OLTP) applications in the Guardian environment on NonStop systems. Pathway/TS screen programs communicate with terminals and intelligent devices. Pathway/TS includes the TCP, the SCREEN COBOL compiler and run-time environment, and the SCREEN COBOL Utility Program (SCUP). It requires the services of the identifier product. period separator. A sequence of two or more characters where the first one is a period, and the remaining ones are spaces. phrase. An ordered set of one or more consecutive COBOL character-strings that form a portion of a COBOL procedural statement or of a COBOL clause. physical record. See block. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -23 Glossary PIC PIC. See position-independent code (PIC). PIN. See process identification number (PIN). position-dependent code (non-PIC). Executable code that must be modified to run at different virtual addresses. External reference addresses appear in non-PIC code. Non-PIC is also called nonshared code. position-independent code (PIC). Executable code that need not be modified to run at different virtual addresses. External reference addresses appear only in a data area that can be modified by the loader; they do not appear in PIC code. PIC is also called shared code. prime record key. A data item in the record description entry of an indexed file whose value uniquely identifies the record; alternate record keys can be unique, but the prime record key is the principal key by virtue of being explicitly declared the prime record key in the RECORD KEY clause of the file-control entry for the file. procedure. One of these: • A paragraph, a group of logically successive paragraphs, a section, or a group of logically successive sections in the Procedure Division Such a procedure functions as a unit of code to be executed by a PERFORM, SORT, MERGE, or USE statement. Although good programming practice dictates that procedures be composed of physically successive paragraphs or sections, execution of a GO TO statement can extend the scope of a procedure to paragraphs or sections that are logically but not physically successive. • Routines coded in TAL, as the routines of the operating system are, sometimes are referred to as procedures. procedure branching statement. A statement that causes the explicit transfer of control to a statement other than the next executable statement in the sequence in which the statements are written in the source program. The procedure branching statements are: ALTER, CALL, EXIT, EXIT PROGRAM, GO TO, MERGE (with the OUTPUT PROCEDURE phrase), PERFORM, and SORT (with the OUTPUT PROCEDURE phrase). procedure-name. A paragraph-name, a qualified paragraph-name, or a section-name in the Procedure Division. process. 1. A program that has been submitted to the operating system for execution, or a program that is currently running in the computer. 2. An address space, a single thread of control that executes within that address space, and the system resources required by that thread of control. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -24 Glossary process identification number (PIN) process identification number (PIN). An unsigned integer that identifies a process in a processor module. Internally, a PIN is used as an index into the process control block table. process pair. Two instances of the same executable object file (called the primary process and the backup process) that are executing in separate processors of a NonStop system. Only the primary process is active, performing its tasks and passing information about its progress to the backup (checkpointing). If the primary process fails, the backup process becomes the primary process, continuing the tasks from the site of the last checkpoint. program name. The name of an object program. program-name. A user-defined word that identifies a COBOL source program. PROGRAM-STATUS. A special register to which the STARTBACKUP statement assigns a value that reflects the success or failure of the creation of the backup process. program unit. A single source program or object program. PS Text EDIT. An HP text-editing program, often abbreviated TEDIT. pseudo-text. A sequence of text-words, comments, and separators, preceded and followed by the pseudo-text pseudo-text delimiter (==). pseudo-text delimiter. Two contiguous equal signs (==) that identify the beginning or end of a pseudo-text, but are not part of the pseudo-text. punctuation character. One of: Character Character Name Character Character Name ; Semicolon ( Left parenthesis : Colon ) Right parenthesis . Period " Quotation mark Space = Equal sign pTAL. A machine-independent systems programming language based on TAL. The pTAL language excludes architecture-specific TAL constructs and includes new constructs that replace the architecture-specific constructs. Compare to HP Transaction Application Language (TAL). qualified data-name. An identifier that consists of a data-name followed by one or more sets of these: • • The connective OF and a data-name, file-name, or condition-name qualifier The connective IN and a data-name, file-name, or condition-name qualifier HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -25 Glossary qualifier qualifier. One of these: • • • A data name or file name used in a reference, together with a data name that is at a lower level in the same hierarchy. A section-name that you use in a reference together with a paragraph-name specified in that section. A library name you use in a reference together with a text name associated with that library. queue file. An indexed file that can function as a queue. random access. An access mode in which the value that a program specifies for a key identifies the logical record on which the process operates in a structured file. RECEIVE-CONTROL. The name of an Environment Division paragraph that defines the Receive-Control table and the Reply table used by a $RECEIVE process. record. See logical record. record area. A storage area the process allocates for processing a record described by a record description entry in the File Section. record description entry. The total set of data description entries associated with a particular record. record key. A data item whose value identifies a record in a structured file. See prime record key, relative key, and alternate record key. record-name. A user-defined word that names a record described by a record description entry in the Data Division. record number. The ordinal number of a record in a sequential file. reduced instruction-set computing (RISC). A processor architecture based on a relatively small and simple instruction set, a large number of general-purpose registers, and an optimized instruction pipeline that supports high-performance instruction execution. Compare to complex instruction-set computing (CISC) and explicitly parallel instruction set computing (EPIC). reference format. A format that provides a standard method for describing COBOL source programs: • • Tandem reference format ANSI reference format reference modifier. The leftmost character position and length used to establish and refer to a data item. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -26 Glossary reference page reference page. The online or hard-copy version of a file that provides reference information for a software facility. Some UNIX documentation uses the term man page instead, referring either to the online delivery mechanism used to display the file (usually the shell man command) or to the nature of the file as part of the manual. reference parameter. A parameter that is passed by reference (that is, its address is passed). A called routine can permanently change the value of a reference parameter. Compare to content parameter. relation condition. The proposition, for which a process can determine a truth value, that the value of an arithmetic expression or data item has a specific relationship to the value of another arithmetic expression or data item. relative file. A file that has relative organization. relative key. A data item whose value identifies a logical record in a relative file. relative organization. A permanent logical file structure in which an integer value greater than zero uniquely identifies each record, specifying the record’s logical ordinal position in the file. relative record number. The ordinal number of a record in a relative file. This number is handled as a integer numeric literal. release version update (RVU). A collection of compatible revisions of NonStop operating system software products, identified by an RVU ID, and shipped and supported as a unit. An RVU consists of the object modules, supporting files, and documentation for the product revisions. An RVU also includes a set of documentation for the overall RVU. requester. A client that runs only in the Guardian environment by using an interface defined by HP. reserved word. A COBOL word that you cannot use for a user-defined word or a system name in a source program. resource. A facility or service, controlled by the operating system, that an executing program can use. RISC. See reduced instruction-set computing (RISC). RISC instructions. See MIPS RISC instructions. routine-name. A user-defined word that identifies a procedure written in a language other than COBOL. run-time environment. The services provided by run-time library routines and data objects (data blocks and pointers) to a program at run-time. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -27 Glossary run-time library run-time library. A collection of routines that supports requests for I-O and heap management, math and string functions, exception handling, and error reporting. run-time routine. A subprogram, supplied as part of the COBOL product, which performs some function needed in the course of executing a statement in the COBOL language and which the object code produced by the COBOL compiler automatically calls when needed. run unit. A set of one or more object programs in the same object file. RVU. See release version update (RVU). Saved Message Utility (SMU). A set of utility routines, available to COBOL or FORTRAN programs, that can be used to examine and modify portions of the initial processcreation messages (ASSIGN, PARAM, and startup) in the environment of a process. SCI. SQL Compiler Interface. SCREEN COBOL. A procedural language developed by HP and based on COBOL that is used to define and control screen displays on terminals and other input-output devices. SCREEN COBOL allows programmers to write requester programs that communicate with operator terminals and intelligent input-output devices and that send data to server processes that manage application databases. SCREEN COBOL programs are compiled into pseudocode form by the SCREEN COBOL compiler and are then interpreted by the TCP. section. A section header followed by a section body, which includes zero or more paragraphs or entries. section header. In the Procedure Division, a section-name followed by the reserved word SECTION, a segment number (optional), a period, and a space; in the Environment Division or Data Division, a combination of reserved words followed by a period (.). The section headers in the Environment Division are: • • CONFIGURATION SECTION INPUT-OUTPUT SECTION The section headers in the Data Division are: • • • • FILE SECTION WORKING-STORAGE SECTION EXTENDED-STORAGE SECTION LINKAGE SECTION section-name. A user-defined word that names a section in the Procedure Division. segment number. A user-defined word, expressed as a one- or two-digit number, that classifies a Procedure Division section for segmentation. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -28 Glossary semicolon separator semicolon separator. A sequence of two or more characters where the first one is a semicolon, and the remaining ones are spaces. sentence. A sequence of one or more statements, the last terminated by a period (.). separately compiled program. A program that (together with its contained programs) is compiled separately from all other programs. In the HP COBOL implementation, several separately compiled programs can be presented to the compiler as a group; each must be separated from its neighbor by an ENDUNIT directive or its end program header. separator. A string of one or two punctuation characters used to delimit character-strings. sequential access. An access mode in which a process reads logical records from or writes logical records to a file in a consecutive predecessor-to-successor sequence determined by the order of the records in the file (or, in the case of sequential access by an alternate record key, in a sequence governed by the value of the alternate key selected in a START statement). sequential block buffering. An Enscribe feature, enabled by the RESERVE clause of the FILE-CONTROL paragraph, that speeds the reading of a sequential, relative, indexed, or queue file by reading a block of records together into a memory buffer. sequential file. A file that has sequential organization (includes entry-sequenced and unstructured files). sequential organization. A permanent logical file structure in which a process identifies a record by a predecessor-successor relationship established when the same or another process writes the record to the file. server. A process that handles database input and output and related logical and computational operations specified by a requester. session. The period of time between a command interpreter LOGON command and the next LOGON or LOGOFF command; certain environmental attributes, such as the current default system, volume, and subvolume, selected debugger, and saved ASSIGN and PARAM messages persist until you explicitly change them or issue the LOGOFF command to end a command interpreter session. shared code. See position-independent code (PIC). shared run-time library (SRL). A collection of procedures whose code and data can be loaded and executed only at a specific assigned virtual memory address (the same address in all processes). SRLs use direct addressing and do not have run-time resolution of links to and from the main program and other independent libraries. Compare to dynamic-link library (DLL). HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -29 Glossary sign condition sign condition. The proposition, for which a process can determine a truth value, that the algebraic value of a data item or an arithmetic expression is less than, greater than, or equal to zero. signal. The method by which an environment notifies a process of an event. Signals are used to notify a process when an error that is not related to input or output has occurred. A signal is often an indication of a run-time event that requires immediate attention. Many such events preclude continuing the interrupted instruction stream. Signals are generated for TNS/R native Guardian processes. (TNS Guardian processes receive traps instead.) A SIGILL signal indicates that an instruction cannot be executed because the instruction or its data are invalid. Compare to trap. simple condition. Any single condition that is either: • • • • • • Relation condition class condition condition-name condition switch-status condition sign condition Simple condition enclosed in parentheses single-language program. A program in which all routines are written in the same programming language. sort file. One of: • • A collection of records for a process to sort during the execution of a SORT statement A file declared in the sort-merge file description entry and created and used only by the sort function sort-merge file description entry. An entry in the File Section of the Data Division composed of the level indicator SD followed by a file name and then a set of file clauses, as required. SOURCE-COMPUTER. The name of an Environment Division paragraph that describes the computer environment in which you can compile the source program. source file. A file that consists of one or more source programs. source library file. A file containing source code that a compiler can copy into a source program when specified by a COPY statement in COBOL. source program. A set of COBOL statements, headers, entries, and comments that includes the Identification Division, Environment Division, Data Division, and Procedure Division, in that order, and optionally includes compiler directives. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -30 Glossary space separator space separator. A sequence of one or more space characters (which are not part of some other separator) used as a separator. special character. One of: Character Meaning Character Meaning + Plus sign ; Semicolon - Minus sign . Period (decimal point) * Asterisk " Quotation mark / Slash (slant, virgule) ( Left parenthesis = Equal sign ) Right parenthesis $ Currency sign > Greater than symbol , Comma (decimal point) < Less than symbol special-character word. A reserved word that is an arithmetic operator or a relation character. SPECIAL-NAMES. The name of an Environment Division paragraph in which you can assign mnemonic-names you choose to certain implementor-names, define a currency symbol other than dollar sign ($), and exchange the function of commas and periods in both PICTURE character-strings and numeric literals. special register. Storage areas the compiler generates primarily to store information produced by certain COBOL features. spooler. A set of processes that act as an interface between a process and a print device. SQL. Structured Query Language. SQL Compiler Interface (SCI). Embedded SQL statement processor. SRL. See shared run-time library (SRL). standard addressing. Referencing a data item or parameter by using a 16-bit address (also called 16-bit addressing). Compare to extended addressing. standard data format. A way to express the characteristics or properties of data as it would appear on a printed page of infinite length and breadth rather than as the form in which the computer or a particular external medium stores the data. statement. A syntactically valid combination of character-strings and separators beginning with a verb. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -31 Glossary structured file structured file. A disk file of fixed-length records or variable-length records, to which a process gains access through the Enscribe record manager, that has one of three organizations: • • • Entry sequenced Key sequenced Relative subprogram. See called program. subscript. An occurrence number represented by either an integer, a data-name optionally followed by an integer with the operator + or -, or an index-name optionally followed by an integer with the operator + or -, that identifies a particular table element. subvolume. A logical subdivision of a volume, used to group files on the volume. switch-status condition. The proposition, for which a process can determine a truth value, that an implementor-defined switch is set to ON or OFF. symbolic-character. A user-defined word that specifies a user-defined figurative constant. sync-id. A numeric identifier, assigned by the operating system to write requests in a faulttolerant process pair, used to keep track of the requests to prevent the repetition of requests that cannot be tried again after a takeover by the backup process. system file name. The name by which the operating system recognizes a file. Compare to COBOL file name. system-name. A COBOL word that a process uses to communicate with the operating system. system services. The tasks performed on behalf of the user or user programs by the operating system, including formatting, process control, I-O support, performance measurement, HP process pair support, standard security, and transaction management. table. A set of logically consecutive data items defined in the Data Division by a data description entry that includes an OCCURS clause. table element. A data item that belongs to a set of repeated items comprising a table. TACL. See HP Tandem Advanced Command Language (TACL). TAL. See HP Transaction Application Language (TAL). target file. An object file that is output by the compiler or the Binder or nld utility or ld utility (as opposed to an object file that is input to the Binder or linker). TEDIT. An abbreviation for PS Text EDIT, an HP text-editing program. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -32 Glossary terminal terminal. An input-output device. terminal control process (TCP). A process used for terminal management and transaction control, provided by HP as a part of the Pathway/TS product. A TCP is a multithreaded process that interprets compiled SCREEN COBOL requester programs (screen programs) in the user’s application, executing the appropriate program instructions for each I-O device or process for which the TCP is configured. The TCP coordinates communication between screen programs and server processes. text-name. A user-defined word that identifies library text. text-word. A character or a sequence of contiguous characters between margin A and margin R in a COBOL library, source program, or in pseudo-text which is: • • • • A separator, except for: a space, a pseudo-text delimiter, and the opening and closing delimiters for nonnumeric literals. The right parenthesis and left parenthesis characters, regardless of context within the library, source program, or pseudo-text, are always considered text-words. A literal including, in the case of nonnumeric literals, the opening quotation mark and the closing quotation mark that bound the literal Any other sequence of contiguous COBOL characters except comments and the word COPY, bounded by separators, which is neither a separator nor a literal. TMF. See HP NonStop™ Transaction Management Facility (TMF). TNS. Refers to fault-tolerant HP computers that support the HP NonStop™ operating system and are based on microcoded complex instruction-set computing (CISC) technology. TNS systems run the TNS instruction set. Compare to TNS/R and TNS/E. TNS accelerated mode. A TNS emulation environment on a TNS/R or TNS/E system in which accelerated TNS object files are run. TNS instructions have been previously translated into optimized sequences of MIPS or Intel® Itanium® instructions. TNS accelerated mode runs much faster than TNS interpreted mode. Accelerated or interpreted TNS object code cannot be mixed with or called by native mode object code. See also TNS Object Code Accelerator (OCA). Compare to TNS mode and native mode. TNS architecture. NonStop Series architecture. HP computers that are based on CISC technology. TNS architecture implements the TNS instruction set. TNS compiler. A compiler in the TNS development environment that generates 16-bit TNS object code following the TNS conventions for memory, stacks, 16-bit registers, and call linkage. The COBOL85 compiler is an example of such a compiler. Contrast with TNS/R native compiler and TNS/E native compiler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -33 Glossary TNS instructions TNS instructions. Stack-oriented, 16-bit machine instructions that are directly executed on TNS systems by hardware and microcode. TNS instructions can be emulated on TNS/E and TNS/R systems by using millicode, an interpreter, and either translation or acceleration. Compare to MIPS RISC instructions and Intel® Itanium® instructions. TNS interpreted mode. A TNS emulation environment on a TNS/R or TNS/E system in which individual TNS instructions in a TNS object file are directly executed by interpretation rather than permanently translated into MIPS or Intel® Itanium® instructions. TNS interpreted mode runs slower than TNS accelerated mode. Each TNS instruction is decoded each time it is executed, and no optimizations between TNS instructions are possible. TNS interpreted mode is used when a TNS object file has not been accelerated for that hardware system, and it is also sometimes used for brief periods within accelerated object files. Accelerated or interpreted TNS object code cannot be mixed with or called by native mode object code. Compare to TNS accelerated mode, TNS/R native mode, and TNS/E native mode. TNS mode. The operational environment in which unaccelerated TNS instructions execute. Compare to TNS accelerated mode and native mode. TNS object code. The TNS instructions that result from processing program source code with a TNS compiler. TNS object code executes on TNS, TNS/R, and TNS/E systems. TNS Object Code Accelerator (OCA). A program optimization tool that processes a TNS object file and produces an accelerated file for the TNS/E architecture. OCA augments a TNS object file with equivalent Intel® Itanium® instructions. TNS object code that is accelerated runs faster on TNS/E systems than TNS object code that is not accelerated. TNS process. A process whose main program object file is a TNS object file, compiled using a TNS compiler. A TNS process executes in interpreted or accelerated mode while within itself, when calling a user library, or when calling into TNS system libraries. A TNS process temporarily executes in native mode when calling into native-compiled parts of the system library. Object files within a TNS process might be accelerated or not, with automatic switching between accelerated and interpreted modes on calls and returns between those parts. Compare to TNS/R native process and TNS/E native process. TNS user library. A user library available to TNS processes in the Guardian environment. TNS/E. Refers to fault-tolerant HP computers that support the HP NonStop™ operating system and are based on the Intel® Itanium® processor. TNS/E systems run the Itanium instruction set and can run TNS object files by interpretation or after acceleration. TNS/E systems include all HP NonStop™ systems that use NSE-x processors. Compare to TNS and TNS/R. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -34 Glossary TNS/E architecture TNS/E architecture. NonStop Series/Itanium architecture. HP computers that are based on Itanium technology. TNS/E architecture implements the Itanium instruction set [explicitly parallel instruction set computing (EPIC)] and are upwardly compatible with the TNS and TNS/R system-level architectures. TNS/E native compiler. A compiler in the TNS/E development environment that generates TNS/E native object code, following the TNS/E native-mode conventions for memory, stack, registers, and call linkage. The ECOBOL compiler is an example of such a compiler. Contrast with TNS compiler and TNS/R native compiler. TNS/E native mode. The primary execution environment on a TNS/E system, in which native-compiled Intel® Itanium® object code executes, following TNS/E native-mode compiler conventions for data locations, addressing, stack frames, registers, and call linkage. Compare to TNS interpreted mode and TNS accelerated mode. See also TNS/R native mode. TNS/E native object code. The Intel® Itanium® instructions that result from processing program source code with a TNS/E native compiler. TNS/E native object code executes only on TNS/E systems, not on TNS systems or TNS/R systems. TNS/E native object file. An object file created by a TNS/E native compiler that contains Intel® Itanium® instructions and other information needed to construct the code spaces and the initial data for a TNS/E native process. TNS/E native process. A process initiated by executing a TNS/E native object file. Compare to TNS process and TNS/R native process. TNS/E native user library. A user library available to TNS/E native processes in both the Guardian and Open System Services (OSS) environments. A TNS/E native user library is implemented as a TNS/E native dynamic-link library (DLL). TNS/R. Refers to fault-tolerant HP computers that support the HP NonStop™ operating system and are based on 32-bit reduced instruction-set computing (RISC) technology. TNS/R systems run the MIPS-1 RISC instruction set and can run TNS object files by interpretation or after acceleration. TNS/R systems include all HP systems that use NSR-x processors. Compare to TNS and TNS/E. TNS/R architecture. NonStop Series/RISC architecture. HP computers that are based on RISC technology. TNS/R architecture implements the RISC instruction set and are upwardly compatible with the TNS system-level architecture. TNS/R native compiler. A compiler in the TNS/R development environment that generates TNS/R native object code, following the TNS/R native-mode conventions for memory, stack, 32-bit registers, and call linkage. The NMCOBOL compiler is an example of such a compiler. Contrast with TNS compiler and TNS/E native compiler. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -35 Glossary TNS/R native mode TNS/R native mode. The primary execution environment on a TNS/R system, in which native-compiled MIPS object code executes, following TNS/R native-mode compiler conventions for data locations, addressing, stack frames, registers, and call linkage. Compare to TNS interpreted mode and TNS accelerated mode. See also TNS/E native mode. TNS/R native object code. The MIPS RISC instructions that result from processing program source code with a TNS/R native compiler. TNS/R native object code executes only on TNS/R systems, not on TNS systems or TNS/E systems. TNS/R native object file. An object file created by a TNS/R native compiler that contains MIPS RISC instructions and other information needed to construct the code spaces and the initial data for a TNS/R native process. TNS/R native process. A process initiated by executing a TNS/R native object file. Compare to TNS process and TNS/E native process. TNS/R native shared run-time library (TNS/R native SRL). A shared run-time library (SRL) available to TNS/R native processes in both the Guardian and Open System Services (OSS) environments. TNS/R native SRLs can be either public or private. A TNS/R native process can have multiple public SRLs but only one private SRL. TNS/R native user library. A user library available to TNS/R native processes in both the Guardian and Open System Services (OSS) environments. A TNS/R native user library is implemented as a special private TNS/R native shared run-time library (TNS/R native SRL). top margin. An empty area of a logical page that precedes the page body. trap. A software interrupt that provides a way of handling certain events, such as detection of a hardware (or software) fault, a timer expiration, or a lack of system resources. A trap is often an indication of a run-time event that requires immediate attention. Most such events preclude continuing the interrupted instruction stream. Traps are generated for TNS Guardian processes. (native Guardian processes and all OSS processes receive signals instead.) An Instruction Failure trap indicates that an instruction cannot executed because the instruction or its data are invalid. Compare to signal. truth value. The result of evaluating a condition to determine one of two values: TRUE or FALSE. unary operator. A plus sign (+) or minus sign (-) that precedes a variable or a left parenthesis (but does not follow a variable, numeric literal, or right parenthesis) in an arithmetic expression and that has the effect of multiplying the expression by +1 or -1, respectively. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -36 Glossary unstructured file unstructured file. A disk file organized as a byte stream. Each byte is directly addressable by an application, which manages its own access to the file contents. In COBOL, unstructured files are limited to sequential organization and access with fixed-length records. The COBOL run-time routines handle any blocking and deblocking for unstructured files, which can improve performance. user-defined word. A COBOL word that you supply within the format of a clause or statement. user library. 1. An object code file that the operating system links to a program file at run time. A program can have only one user library. See also TNS user library, TNS/R native user library, and TNS/E native user library. 2. A library loadfile associated with a program so that it emulates the user library feature of the operating system on TNS systems. For PIC programs on TNS/R and TNS/E systems, the user library is a dynamic-link library (DLL). It is treated as if it were the first library in the program's libList; thus it is searched first for symbols required by the program. However, a user library does not appear in the program's libList; instead, its name is recorded internally in the program's loadfile. A program can be associated with at most one user library; the association can be specified using the linker at link time or in a later change command, or at run time using the process creation interfaces. (The /LIB …/ option to the RUN command in TACL uses these interfaces.) value parameter. See content parameter. variable. A data item whose value a process can change. variable-length record. A record associated with a file whose file description entry or sortmerge file description entry permits records to contain a varying number of character positions. variable-occurrence data item. A table element which is repeated a variable number of times. Such an item must contain an OCCURS DEPENDING ON clause in its data description entry, or be subordinate to such an item. verb. A word that expresses an action for the COBOL compiler or an object program to take. volume. A logical disk, which can be one or two magnetic disk drives. In HP NonStop™ S-series systems, volumes have names that begin with a dollar sign ($), such as $DATA. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -37 Glossary word word. An instruction-set-defined unit of memory that corresponds to the width of registers and to the most common and efficient size of memory operations. A TNS word is 2 bytes (16 bits) wide, beginning on any 2-byte boundary in memory. A MIPS RISC word is 4 bytes (32 bits) wide, beginning on any 4-byte boundary in memory. An Intel® Itanium® word is also 4 bytes (32 bits) wide, beginning on any 4-byte boundary in memory. Working-Storage Section. The section of the Data Division that describes Working-Storage data items, which can be noncontiguous data items or Working-Storage records or both. $RECEIVE. A pseudodevice from which a server reads its request messages and to which it writes its replies; any process can read system messages from $RECEIVE by declaring in the RECEIVE-CONTROL paragraph which messages it requires. HP COBOL Manual for TNS and TNS/R Programs —522555-006 Glossary -38 Index Numbers 9 in PICTURE clause 7-57 A A in PICTURE clause 7-55 Abbreviated combined relation conditions 8-66 ABEND 25-6 Abnormal program termination 33-10 Accelerated mode 1-3 ACCEPT statement description of 9-1/9-8 in OSS environment 19-24 terminals and 29-2/29-3, 29-13 Access mode description of 4-8 heritability of 7-40 of parameters 9-27 ACCESS MODE clause description of brief 6-25 complete 7-39/7-40 file type and 6-24 for indexed file 6-49 for line sequential file 6-39, 19-13 for relative file 6-43 for sequential file 6-32 Access path 28-21 Accessor ID 31-27/31-30 ACOS function 14-8 ADD DEFINE command how to use 12-23, 25-2/25-3 SEARCH DEFINEs and 11-36, 22-19 ADD statement description of 9-9/9-16 precision of 8-49 Addition operator 8-46 Address misalignment causes of general 33-6 in HP COBOL programs 33-10/33-11 handling 33-8/33-9 tracing facility for 33-7/33-8 Addressing modes native 23-20 TNS 23-20 Addressing parameters 9-62 add_define command 27-15 AFTER phrase in INSPECT CONVERTING statement 9-114 in INSPECT REPLACING statement 9-104 in INSPECT TALLYING REPLACING statement 9-108, 9-110 in INSPECT TALLYING statement 9-96, 9-99 Alignment migrating to native mode and 33-5, 33-6/33-12 of data in data items 4-15 of data items in memory 4-15/4-16 of decimal point in data conversion 8-43 READ statement and 9-181 REDEFINES clause and 7-51 ALL literal description of 3-23 as subscript 14-7 DISPLAY statement and 9-49 ALLOCATESEGMENT routine 24-22 Allocation See Storage allocation ALPHABET clause 6-15/6-18 Alphabetic class and category 4-1 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -1 Index A ALPHABETIC class test in simple condition 8-60 with default character set 6-8 with nondefault character sets 6-9 Alphabetic data items description of 7-61 ACCEPT statement and 9-3 alignment of data in 4-15 MOVE statements and 9-129 ALPHABETIC-LOWER class test in simple condition 8-60 with default character set 6-8 ALPHABETIC-UPPER class test in simple condition 8-60 with default character set 6-8 Alphabet-name 6-15/6-17 Alphanumeric class and category 4-1 Alphanumeric data items description of 7-61 ACCEPT statement and 9-3 alignment of data in 4-15, 33-10 migration to native mode and 33-10 MOVE statement and 9-129 Alphanumeric edited category 4-1 Alphanumeric edited data items description of 7-62 ACCEPT statement and 9-3 alignment of data in 4-15 MOVE statement and 9-129 Alphanumeric functions description of 14-3 CHAR 14-13/14-14 CURRENT-DATE 14-16 LOWER-CASE 14-28 REVERSE 14-53 UPPER-CASE 14-61 WHEN-COMPILED 14-63/14-64 ALTER DEFINE command 25-9 ALTER statement description of 9-16/9-18 paragraphs with 8-12 Altering programs 22-5/22-10 Alternate key files alternate record keys and 28-22 creating and using 28-45/28-47 improving performance of 28-35/28-37 ALTERNATE RECORD KEY clause description of 6-26/6-27 file type and 6-24 for indexed file 6-50 for relative file 6-44 for sequential file 6-32 Alternate record keys description of 28-22/28-23 for entry-sequenced files 28-12 for indexed files 6-51, 28-18 for relative files 6-45, 28-16 for sequential files 6-34 for unstructured files 28-9 insertion order and 6-27 maximum number of 6-27 null values for 28-36 with duplicate values 6-26 ALTERPARAMTEXT routine 13-106/13-108 Ampersand (&) as CROSSREF prompt 15-9 in TACL command 22-19 ANNUITY function 14-9 ANSI directive 11-53 ANSI reference format description of 16-1, 16-4 COLUMNS directive and 11-59 compiler listing and 22-42, 22-45 directive for 11-53 program creation and 22-6 text libraries and 22-22 ANSI standard labels 27-20 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -2 Index A Apostrophe (') in national literal 3-21 in simple nonnumeric literal 3-19 Approximate positioning 28-24 ar utility 34-10 Arccosine function 14-8 Archive files 34-10 Arcsine function 14-11 Arctangent function 14-12 Area A in ANSI reference format 16-4 in Tandem reference format 2-6 paragraph headers and 8-12 Area B in ANSI reference format 16-4 in Tandem reference format 2-6 Arithmetic expressions description of 8-45, 8-48 as parameters 14-7, 23-22 precision of 8-51/8-53 summary of 38-8/38-9 Arithmetic mean function 14-31 Arithmetic operands 8-46 Arithmetic operations 8-42/8-53 Arithmetic operators 8-46 Arithmetic overflow COBOL85^ARMTRAP and 13-39 COMPUTATIONAL data format and 8-25 error messages for 48-8 in CRE 18-6 TRAP2 and NOTRAP2 and 11-132 TRAP2-74 and NOTRAP2-74 and 11-134 Arithmetic precision 8-48/8-53 Arithmetic statements description of 8-42 common features of 8-43 ASCII character set in alphabetic order A-6 in numeric order A-1 ASIN function 14-11 ASSIGN clause description of 6-25 file type and 6-24 for indexed file 6-48 for line sequential file 6-39, 19-13 for relative file 6-41 for sequential file 6-29 for sort-merge file 6-55 ASSIGN command description of 12-4/12-9 compared to DEFINE 12-19 for overriding file assignments 25-3 for specifying file characteristics 25-4 maximum number of 25-4 OSS environment and 19-23 showing active ones 25-8 #DYNAMIC and 26-9 ASSIGN message portions 13-36 Associating COBOL and system file names 26-5/26-9 Asterisk (*) as arithmetic operator 8-46 in ANSI reference format 16-2 in EXECUTION-L0G parameter 12-13 in PICTURE clause 3-24, 7-57, 7-67 in Tandem reference format 2-4 AT END phrase See also At-end condition in READ statement for line sequential file 9-194, 19-21 for other files 9-180, 9-185, 9-187, 9-189 in RETURN statement 9-201 in SEARCH ALL statement 9-218 in SEARCH VARYING statement 9-212 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -3 Index B AT END phrase (continued) USE AFTER EXCEPTION procedures and 9-288 ATAN function 14-12 Atomic functions (pTAL) 33-8 Attributes CLASS 12-21 DEFINE description of 12-21/12-23 for labeled tape files 27-18/27-24 for unlabeled tape files 27-16/27-18 security 28-4/28-6 At-end condition See also AT END phrase for READ statement file position indicator and 9-182 multiple-reel tape files and 9-185 recoverable errors and 9-187 for SEARCH ALL statement 9-215, 9-218 for SEARCH VARYING statement 9-210, 9-211, 9-212 input-output errors and 8-40 simulated 9-238 $RECEIVE and 31-17 Audited disk files audit trails and 32-17 cache buffering and 28-33 HP COBOL Fast I-O and 6-36 AUTHOR paragraph 5-2 Averaging function 14-31 Avoiding deadlock 28-38/28-40 B B in PICTURE clause 3-24, 7-55 Background processes 25-13 Backup processes description of 32-4/32-6 CHECKPOINT statement and 9-34 STARTBACKUP statement and 9-253 Backward slash (\) 18-8 Banner, compilation 22-40, 22-41 Batch compilation 22-22 BEFORE phrase in INSPECT CONVERTING statement 9-114 in INSPECT REPLACING statement 9-104 in INSPECT TALLYING REPLACING statement 9-108, 9-110 in INSPECT TALLYING statement 9-96, 9-99 Binary arithmetic operators 8-46 BINARY data format description of 7-69, 7-73 PORT directive and 11-104 SYNCHRONIZED clause and 7-87 tape I-O and 27-14 BINARY data items 33-10, 33-11, 33-12 Binary searches 9-216 BIND utility description of 11-27, 24-5 binding with 24-14/24-16 OBEY command files for 24-15 Binder messages 22-52 Binder object file builder description of 11-27/11-28 in compilation 22-16 maps from 22-63 messages from 22-52 statistics from 11-29 Binder process 24-4 Binding description of 24-1/24-23 called programs’ object code 11-23 directives for 11-51 HP COBOL programs automatically 24-10/24-11 to be called dynamically 24-14 with BIND utility 24-14/24-16 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -4 Index C Binding (continued) mixed-language programs 24-16 process of 24-4 BINSERV process description of 11-10, 11-12, 11-27, 11-43, 24-5 in compilation 24-10/24-13 selecting processor for 11-34 BLANK directive description of 11-54 initializing data items and 7-36 migrating to native mode and 33-15 Blank lines in replacement text 10-17 in Tandem reference format anywhere 2-6 in continuation lines 2-5 BLANK WHEN ZERO clause description of 7-88 for BINARY/COMPUTATIONAL data item 7-73 for INDEX data item 7-76 for NATIVE-n data item 7-76 in record description entry 7-46 BLOCK CONTAINS clause description of 7-15/7-17 for external file 7-12 for labeled tape file 27-21 for unlabeled tape file 27-2 HP COBOL Fast I-O and 6-36 sequential block buffering and 6-35 Blocked files closing 9-39 creating 7-16 Blocked records in structured files 28-31/28-35 in tape files 27-2 BLOCKLEN attribute of DEFINE for labeled tape file 27-21 for unlabeled tape file 27-16 Blocks code description of 24-1/24-3 calling each other 24-3 replacing 24-15/24-16 data 24-1/24-3 Body of page 7-26 Borland integrated development environment (IDE) 34-4 Break key 29-8/29-9 BREAK message 6-75 BUFFERED attribute 6-35 Buffering cache indexed files and 6-52 relative files and 6-45 sequential files and 6-35, 9-298 structured files and 28-32 HP COBOL Fast I-O 28-34/28-35 local for indexed files 6-52 for relative files 6-46 for sequential files 6-36 sequential block disk input-output and 28-33 for indexed files 6-52 for relative files 6-45 for sequential files 6-34 HP COBOL Fast I-O and 9-190 BUFFER-SIZE parameter 13-56, 13-58 Bypassing labels 27-20 C C routines calling 9-58 in TNS user library 24-19 migrating to native mode 33-4 passing parameters to 9-63, 23-26/23-29 restrictions on 9-63/9-64, 23-16 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -5 Index C C routines (continued) run-time environment for 23-2 sharing data with 23-17 C8LIB file 22-13 Cache buffering See Buffering, cache Cache, write-through 28-32 CALL statement description of 9-18/9-31, 11-12/11-16 at object program level 24-3 detailed explanation of 11-16/11-23 dynamic 23-6, 24-14 EXTENDED access mode and 7-40 PIC loadfiles and 9-25 STANDARD access mode and 7-40 static 23-5 X/Open See X/Open CALL statement Called programs description of 11-4 compilation units and 11-7/11-8 EXIT PROGRAM statement and 9-80 how compiler finds COBOL programs 11-16/11-18 non-COBOL programs 11-18/11-22 limits on 20-7 non-COBOL 9-58 reading disk files from 28-7 termination of 12-26 that return values 9-61 utility routines 13-1/13-139 Calling programs and routines description of 11-4, 23-1/23-34 COBOL 23-3/23-7 dynamically 23-6 in unspecified languages 23-8 non-COBOL 23-7/23-19 Calling programs and routines (continued) operating system routines description of 23-10/23-15 parameters for 23-10 resolution of 23-13/23-15 run-time routines 24-6 statically 23-5 that return values 23-9 CALL-SHARED directive description of 11-55 migrating to native mode and 33-20 CANCEL directive 11-56 CANCEL statement description of 9-32/9-33 X/Open CALL statement and 23-7 Caret (^) 12-20, 47-2 Case sensitivity ACCEPT statement and 9-3 in HP COBOL 3-3 in record keys 28-22 in simple nonnumeric literals 3-19 in system file names 26-2 user-defined currency sign and 6-21 Categories of data description of 4-1, 7-60 in Data Division 7-2 CBL85UTL file overview of 13-23, 13-24 CRE and 18-7 descriptions of routines in 13-38/13-84 list of routines in 13-24 syntax summary of routines in 45-1/45-10 CBLIBEXT file description of 13-23 COBOLLIB routines in system code space and 13-29 Changing the compilation environment 22-20/22-22 CHAR function 14-13/14-14 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -6 Index C Character sets COBOL 3-2/3-3 nondefault 6-9 CHARACTER-SET clause 6-6, 6-8/6-9 Character-strings description of 3-6/3-24 COBOL words 3-7/3-16 comments 3-24 literals 3-16/3-23 PICTURE editing characters in 3-24 punctuation characters in 3-6 size of 7-55 CHECK directive 11-56/11-57 Check protect 3-24 CHECKLOGICALNAME routine 13-108/13-109 CHECKMESSAGE routine 13-110 CHECKPOINT statement description of 9-34/9-36 CRE and 18-6 Extended-Storage Section and 24-22 fault-tolerant facility and 32-2 migrating to native mode and 33-13 Checkpointing description of 32-6 automatic 9-35 for data items in Extended-Storage Section 7-38 in Working-Storage Section 7-36 for process pairs 13-35 for sync blocks 32-7 migration to native mode and 33-15 rules for 32-8, 32-9 STARTBACKUP statement and 9-254, 9-255 with multiple checkpoints 9-36 Circumflex(^) 12-20, 47-2 CLASS attribute description of 12-21, 25-3 for labeled tape file 27-19 for unlabeled tape file 27-16 CLASS clause 6-19/6-21 Class conditions 8-59/8-61 Classes of data description of 4-1 tests for character sets and 6-8 numeric data and 8-61 user-defined 6-19 CLEAR command description of 12-17/12-18 examples of 22-22, 25-9 CLOSE message 6-75 CLOSE routine 13-139 CLOSE statement description of 9-37/9-41 fault-tolerant facility and 32-10 file connector and 4-11 implicit CANCEL statement and 9-32 run unit termination and 9-38 Closed open mode 4-10 CLULIB file 13-30/13-31 CLU_PROCESS_CREATE_ routine 13-30 CLU_PROCESS_FILE_NAME_ routine 13-30 COBOL character set 3-2/3-3 COBOL file names associating with system file names 9-144, 26-5/26-9 characteristics of 26-4 COBOL language HP See HP COBOL standard See Standard COBOL HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -7 Index C cobol utility (OSS) running COBOL85 compiler with 19-2/19-3 COBOL words description of 3-7 qualified names 3-13/3-16 reserved words 3-9 system-names 3-10 user-defined names 3-10 COBOL85 compiler See also cobol utility (OSS) See also Compiler description of 1-4 object files produced by 11-27 COBOL85^ARMTRAP routine 13-39 COBOL85^COMPLETION routine 13-40/13-42 COBOL85^RETURN^SORT^ERRORS routine 13-46/13-48 COBOL85^REWIND^SEQUENTIAL routine 13-49/13-50 COBOL85^SET^SORT^PARAM^TEXT routine 13-51/13-54 COBOL85^SET^SORT^PARAM^VALUE routine 13-55/13-65 COBOL85^SPECIAL^OPEN routine description of 13-70 for partitioned disk files 13-80/13-82 for printers and spoolers 13-71/13-77 for system log files 13-77/13-79 for tape files in CRE 13-82/13-84 COBOLASSIGN routine 13-86/13-88, 18-8 COBOLEX0 file 11-15, 13-23, 23-14 COBOLEX1 file 11-15, 13-23, 23-14 COBOLEXT file 11-15, 11-19, 11-23, 13-23, 23-13/23-15, 24-6 COBOLFILEINFO routine description of 13-91/13-93 disk input-output and 28-42 in CRE 18-8 in OSS environment 19-25 COBOLLIB file overview of 13-26, 13-29 CRE and 18-8 descriptions of routines in 13-85/13-104 list of routines in 13-27 COBOLSPOOLOPEN routine description of 13-95/13-100 error codes for 13-100 in CRE 18-8 COBOL_ASSIGN_ routine description of 13-89/13-91 COBOL_SET_MAX_RECORD routine and 13-67 in OSS environment 19-25 COBOL_COMPLETION_ routine 13-40/13-42 COBOL_CONTROL_ routine 13-43/13-45 COBOL_FILE_OPEN_ routine 13-93/13-95 COBOL_GETENV_ routine 13-45 COBOL_PUTENV_ routine 13-46 COBOL_RETURN_SORT_ERRORS_ routine description of 13-46/13-48 in OSS environment 19-25 COBOL_REWIND_SEQUENTIAL_ routine 13-49/13-50 COBOL_SETMODE_ routine 13-67/13-70 COBOL_SET_MAX_RECORD_ routine 13-66/13-67 COBOL_SET_SORT_PARAM_TEXT_ routine description of 13-51/13-54 in OSS environment 19-25 COBOL_SET_SORT_PARAM_VALUE_ routine 13-55/13-65 COBOL_SPECIAL_OPEN_ routine description of 13-70 for partitioned disk files 13-80/13-82 for printers and spoolers 13-71/13-77 for system log files 13-77/13-79 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -8 Index C COBOL_SPECIAL_OPEN_ routine (continued) for tape files in CRE 13-82/13-84 in OSS environment 19-25 Code blocks description of 11-27, 24-1/24-3 calling each other 24-3 replacing 24-15/24-16 CODE directive description of 11-58 compiler listing and 22-41 migrating to native mode and 33-18 sample output from 22-54 Code generation control directives 11-49 Code segments 24-17/24-18 Codewright See HP Tandem Extensions for Codewright (TEC) CODE-SET clause description of 7-29 in external file 7-13 Collector process 30-3 Colon (:) 3-5 COLUMNS directive 10-13, 11-59 Combined conditions 8-65, 8-66 Comma (,) See also Decimal point as separator 3-5 in PICTURE clause 3-24, 7-57, 7-64 Command files See OBEY command files Command log, TACL 22-2/22-4 Command summary 35-1/35-12 Comments description of 3-24 in ANSI reference format for top of page 16-2 ordinary 16-2 in replacement text 10-10, 10-17 Comments (continued) in Tandem reference format for top of page 2-4 ordinary 2-4 restrictions on 2-7 punctuation characters in 3-6 COMMON attribute 9-25 Common phrases 8-22/8-27 Common programs 2-14, 9-25, 23-5 Common Run-Time Environment See CRE Common semantic rules 8-21 COMP data format See COMPUTATIONAL data format COMPACT directive description of 11-60/11-61 migrating to native mode and 33-18 Comparisons in EVALUATE statement 9-72 nonnumeric 8-55 numeric 8-55 of indexes 8-56 of national data items 8-56 of national literals 8-56 Compatible programs 11-74 Compilation See also Compiler banner 22-40, 22-41 batch 22-22 details of 11-9/11-25 environment for 22-20/22-22 for syntax checking only 22-18 in Guardian environment description of 11-1/11-136, 22-13/22-22 with COBOL85 compiler 11-38 with NMCOBOL compiler 11-39 in OSS environment with COBOL85 compiler 19-2/19-3 with NMCOBOL compiler 19-3/19-4 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -9 Index C Compilation (continued) statistics from 11-29/11-32 summary of description of 22-41 for COBOL85 compiler 22-65 for NMCOBOL compiler 22-66 terminating in Guardian environment 11-44 in OSS environment 19-1 units of description of 11-5/11-7, 23-3 called programs and 11-7/11-8 with native COBOL cross compiler 34-7 COMPILE directive 11-61 Compiler See also Compilation COBOL85 1-4 diagnostic messages from 47-1/47-93 directives for See Compiler directives errors See Error messages, compiler improving speed of 22-22 input to 1-5, 11-2/11-8 limits of 20-1/20-8 listing from See Compiler listing NMCOBOL 1-4 output from 1-6, 11-25/11-33 space allocation for 22-21 statistics from 11-30 terminating in Guardian environment 11-44 in OSS environment 19-1 Compiler directives description of 11-44/11-136 categories of 11-47/11-52 COPY statement and 10-5 Compiler directives (continued) for code generation control 11-49 for CRE support 18-3 for listing control 11-48, 22-40 for miscellaneous control 11-51 for resolution and binding control 11-51 for warning messages 22-50 in ANSI reference format 16-2 in COPY libraries 10-13 in OSS environment 19-24 in Tandem reference format 2-4 locations for 11-45, 22-18 summary of 36-1/36-49 Compiler listing banner 22-40 controlling 22-39/22-41 COPY statement and 10-5, 22-44/22-47 creation of 11-26 cross-reference 11-63, 33-22 diagnostic messages in See Error messages, compiler directives that control 22-40 discarding 22-40 embedded NonStop SQL/MP and 22-48 empty 22-14 IF and IFNOT directives and 11-86 INNERLIST directive and 22-41 minimal 22-40 mnemonic codes in COBOL85 compiler 11-83 NMCOBOL compiler 11-87 octal code in 11-58 reference format and 22-42 REPLACE statement and 10-16, 22-44 SOURCE libraries and 22-48 spooling 30-8 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -10 Index C Compiler listing (continued) summary for COBOL85 compiler 22-65 for NMCOBOL compiler 22-66 uncompiled lines in 11-86 Completion codes 11-33 Complex conditions 8-64 Composites of arithmetic operands 8-43 COMPUTATIONAL data format description of 7-69, 7-73 allocation for 4-14 arithmetic overflow and 8-25 compared to NATIVE-n data format 7-77 PORT directive and 11-104 SYNCHRONIZED clause and 7-87 tape I-O and 27-14 value 8224 or 224 and 7-73 COMPUTATIONAL data items 33-10, 33-11, 33-12 COMPUTATIONAL-3 data format 7-69/7-72, 7-74 COMPUTATIONAL-5 data format 7-70, 7-74, 7-77 COMPUTE statement 9-41/9-43 COMP-3 data format See COMPUTATIONAL-3 data format COMP-5 data format See COMPUTATIONAL-5 data format Concatenation expressions description of 8-69/8-70 summary of of 38-13 Conditional compilation description of 11-84 for maintaining common source code 33-23 Conditional expressions description of 8-53/8-69 summary of 38-9/38-12 Conditional statements description of 8-6/8-7 EVALUATE 9-67/9-75 GO TO 9-82/9-83 IF 9-86/9-90 Conditional variables description of 8-61 INDEX data items as 7-76 Conditions abbreviated combined relation 8-66 at-end 8-40 class 8-59/8-61 combined 8-65, 8-66 complex 8-64 condition-name See Conditional variables error 8-40 evaluation rules for 8-68 invalid-key 8-40 negated 8-64 relation See Relation conditions sign 8-63 simple 8-53 switch-status 8-62 Condition-names description of 4-25 description entries for 7-95 identical 3-16 in SET statement 9-224 qualified 3-13, 3-14 scope of 2-13 Configuration Section 6-3/6-22 Consistency checking of labeled tape information 27-10 Consoles See Terminals Constants, figurative See Figurative constants HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index- 11 Index C CONSULT directive description of 11-62/11-63 migrating to native mode and 33-15, 33-16, 33-17, 33-22 Content, passing parameters by 23-21/23-22 Continuation lines in ANSI reference format 16-3 in Tandem reference format 2-5 CONTINUE statement explicit 9-44, 9-86, 9-211, 9-216 implicit 9-77 CONTROL message 6-75 CONTROLBUF message 6-75 Conversion between EBCDIC and ASCII 27-12 for labeled tape files 27-11 from COBOL 74 to HP COBOL TRAP2 and NOTRAP2 directives 11-132 TRAP2-74 and NOTRAP2-74 directives 11-134 of arithmetic operands 8-43 of other data types 27-13 to native mode See Migrating to native mode COPY libraries description of 2-9, 10-11/10-14, 22-22/22-24 altering 22-24/22-29 copying from 22-30, 22-31 creating 22-24/22-29 debugging lines in 10-10 default, specifying 22-18 efficient use of 22-33 for CROSSREF utility 15-9 format of 10-12 from DDL compiler 22-26 including text from 22-29/22-33 matching text in 10-9 COPY libraries multiple 22-33 names of, specifying 10-11 nondefault, specifying 22-33 REPLACE statement and 22-38 COPY statement compared to SOURCE directive 22-23 compiler listing and 22-44/22-47 debugging lines and 22-33 diagnostic messages and 22-45/22-47 directives that control 22-40 IF directive and 11-85 REPLACING phrase of 10-7/10-11, 22-31 simple 22-30 SOURCE directive and 11-120 source manipulation and 10-2/10-6 substrings and 22-32 Correspondence in DATA RECORDS clause 7-24 in EVALUATE statement 9-71 in MOVE CORRESPONDING statement 9-132 of data items 8-22 CORRESPONDING phrase description of 8-22 size error condition and 8-26 Corrupt bit 6-37 COS function 14-15 Cosine function 14-15 CPU option of RUN command 22-15 CPU utility routine parameter 13-56, 13-58 CPU-DOWN message 6-75 CPU-MASK parameter 13-53 CPU-UP message 6-75 CR (credit) 3-24, 7-57, 7-65 CRE (Common Run-Time Environment) description of 23-2 HP COBOL support for 18-1/18-8 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -12 Index D CRE (Common Run-Time Environment) (continued) library 23-2 structured files and 28-32 CREATEPROCESS routine 13-101/13-104 CREATE-NEW-OUTPUT parameter 13-56, 13-59 CREATE-NEW-SCRATCH parameter 13-56, 13-59 Creating HP COBOL files indexed 28-17/28-18 queue 28-19 relative 28-16/28-17 sequential 28-14/28-16 Creating programs 22-5/22-10 Creator ID, changing 31-39 Credit (CR) 3-24, 7-57, 7-65 CROSSREF directive description of 11-63/11-66 compiler listing and 22-41 cross-reference listing and 22-63 migrating to native mode and 33-18 CROSSREF utility description of 15-8/15-10 compared to CROSSREF directive 11-63 Cross-reference listing description of 22-63 compiler listing and 22-41 CROSSREF directive and 11-63 migrating to native mode and 33-18, 33-22 CURRENCY SIGN clause 6-21 Current position 30-12 Current spooler job 30-12 CURRENT-DATE function 14-16 Cursors 9-2 Customizing the PS TEXT EDIT (TEDIT) editor 22-10 C++ routines calling 9-58, 23-18 constructs peculiar to 9-64 ENTER statement and 9-58 migrating to native mode 33-4 passing parameters to 9-63, 23-26/23-29 restrictions on 9-63/9-64 D D or d (the letters) in ANSI reference format 16-2 in Tandem reference format 2-5 Data blocks 11-27, 24-1/24-3, 33-21 Data categories 7-60 Data declaration libraries 22-26 Data Definition Language (DDL) description of 22-25/22-29 migrating to native mode and 33-5 Data description entries for condition-names 7-95 for files 7-5/7-32 for independent data items 7-3 for records 7-2, 7-43/7-90 in Extended-Storage Section 7-37 in Linkage Section 7-39 in Working-Storage Section 7-34 level 66 7-91 level 77 7-93 level 88 7-95 Data dictionary 22-29 Data Division description of 7-1/7-97 HP extensions affecting 17-3 summary of 42-1/42-14 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -13 Index D Data items alignment of in memory 4-15/4-16 migrating to native mode and 33-5, 33-6/33-12 standard debugging tools and 15-1 alignment of data in 4-15 alphabetic 7-61 alphanumeric 7-61 alphanumeric edited 7-62 BINARY See BINARY data format categories of description of 4-1 in Data Division 7-2 checkpointing 32-7 classes of 4-1 COMPUTATIONAL See COMPUTATIONAL data format COMPUTATIONAL-3 See COMPUTATIONAL-3 data format COMPUTATIONAL-5 See COMPUTATIONAL-5 data format corresponding 8-22 description entries for See Data description entries DISPLAY See DISPLAY data format elementary See Elementary data items external See External objects group See Data structures in File Section 7-46 in Linkage Section 7-46 independent 7-3 Data items (continued) INDEX See INDEX data format initialization of in Linkage Section 7-39 in Working-Storage Section 7-36 very large 11-54 intermediate 8-21, 8-44 internal See Internal objects levels of description 4-1 level 01-49 See Records level 66 7-91 level 77 7-3, 7-93 level 88 7-95 national See National data items NATIVE-n See NATIVE-n data format noncontiguous elementary 7-93 numeric See Numeric data items numeric edited 7-62 PACKED-DECIMAL See PACKED-DECIMAL data format POINTER See POINTER data format qualifiers for 4-19 receiving 8-21 redefined 7-48/7-49, 7-81 references to 4-18/4-26 renaming 7-91 representation of 4-14 sending 8-21 shared 2-18/2-23, 23-17 size of 7-59 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -14 Index D Data items (continued) synchronized 7-86 that cannot have VALUE clauses 7-89 Data misalignment See Address misalignment DATA RECORDS clause 7-23, 7-32 Data structures See also Files See also Records See also Tables description of 4-2/4-14, 22-25 initializing 7-90, 9-93 MOVE statement and 9-130 redefined 7-49 storage allocation for 7-46 that cannot have VALUE clauses 7-89 USAGE clause and 7-72 VALUE clause and 7-90 Data type correspondence B-1 Data types other than HP 27-13 Databases describing 22-25/22-29 NonStop SQL/MP, process pairs and 9-36 Data-names identical 3-16 qualified 3-13, 3-14 scope of 2-13 DATA-SLACK parameter 13-56, 13-59 DATE phrase 9-7 Date, current ACCEPT statement and 9-7 CURRENT-DATE function 14-16 DATE-COMPILED paragraph 5-3, 5-5/5-6 DATE-OF-INTEGER function 14-17 DATE-WRITTEN paragraph 5-2, 5-3, 40-2 DAY phrase 9-7 DAY-OF-INTEGER function 14-18 DAY-OF-WEEK phrase 9-8 DB (debit) 3-24, 7-57, 7-65 DDL See Data Definition Language (DDL) Deadlock 28-38/28-40 DEB1 parameter 11-126 Debit (DB) 3-24, 7-57, 7-65 Deblocking files 7-16 Debug debugger 15-5/15-6 Debuggers Debug 15-5/15-6 entering 25-15, 25-16 Inspect 15-5 native programs and 33-6 run-time 15-4 selecting 15-6/15-8 Visual Inspect 15-4 Debugging batch-oriented 15-1/15-3 mode, entering 25-15/25-16 on native COBOL cross compiler 34-7/34-10 position-independent code (PIC) 33-23, 34-8 programs native 33-6 that use fault-tolerant facility 32-14 that use TMF 32-20 standard tools for 15-1/15-3 with debugging lines 15-1 with declaratives 15-2 Debugging lines COPY statement and 10-5, 22-33 in ANSI reference format 16-2 in COPY libraries 10-10 in replacement text 10-17 in Tandem reference format 2-5 DEBUGGING MODE clause 6-4, 25-4 DEBUG-CONTENTS field 9-286 DEBUG-ITEM special register 9-285, 15-2/15-3 DEBUG-LINE field 9-286 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -15 Index D DEBUG-NAME field 9-286 Decimal numeric literals 3-17/3-18 Decimal point See also Comma See also Period in decimal numeric literal 3-17 in intermediate results 8-52 in PICTURE clause 3-24 placement in division 8-50 DECIMAL-POINT clause 6-22 Decision tables 9-67 Declarative procedures conditional GO TO statement and 9-82, 9-83 for debugging 15-2/15-3 LOCKFILE statement and 9-117 unconditional GO TO statement and 9-81 Declaratives Portion execution of 8-20 syntax of 8-15/8-16 Declarative-file connections 13-100 Declaring parameters 9-27 Default misalignment handling method 33-9 Defaults ASSIGN command maximum 25-4 COPY library for COPY statements 22-18 for CROSSREF utility 15-9 file security 28-5/28-6 function key 22-10 input device 25-10 object file name 22-16 output device 25-10 pathname, in OSS environment 19-6 processor for compilation processes 22-20 reference format 22-6 run-time environment 22-19 Defaults (continued) shortest record on tape file 27-1 subvolume 26-3 system 26-3 volume 19-6, 26-3 DEFINEs description of 12-19/12-23 adding 25-2/25-3 attributes of 12-21/12-23, 25-3 characteristics of changing 25-9 showing 25-8 clearing 25-9 compared to ASSIGNs 12-19 creating 12-22 deleting 25-9 for tape files description of 27-15/27-24 labeled 27-18/27-24 unlabeled 27-16/27-18 maximum number of 25-8 names of 12-20, 25-3, 26-9 on PC 34-10 predefined 11-36, 22-19 propagation of 12-20 DELETE DEFINE command 25-9 DELETE statement 9-45/9-47 DELETEASSIGN routine 13-111/13-113 Deleted records 28-14 DELETEPARAM routine 13-114/13-115 DELETESTARTUP routine 13-116/13-117 Delimited-scope statements 8-7 Depending items 7-84 Deploy command 34-11 Descendants of processes 31-35 Describing databases 22-25/22-29 DEV subcommand of SPOOLCOM utility 30-17 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -16 Index D DEVICE attribute of DEFINE for labeled tape file 27-22 for unlabeled tape file 27-16 DEVICEINFO2-COMPLETION message 6-75 Devices default input and output 25-10 default input-output 25-5 DISPLAY statement and 9-48 OPEN statement and 9-144 system file names of 26-3 DEVICE-INFO message 6-75 DIAGNOSEALL directive 11-71 DIAGNOSE-74 directive 11-66/11-69 DIAGNOSE-85 directive description of 11-70 migrating to native mode and 33-20 Diagnostic messages compiler See Error messages, compiler directives that control 22-40 reported against copied lines 22-45/22-47 run-time See Error messages, run-time separately compiled programs and 22-51 Dictionary overflow 33-6 Directives See Compiler directives Directly contained programs 2-10, 23-4 Disk files See also Files allocation of 28-2 audited 28-33 blocking and deblocking 7-17 entry-sequenced description of 28-12 alternate keys and 28-36 creating and using 28-14 Disk files (continued) establishing starting points in 28-20/28-30 exclusion modes for 28-6 improving performance of 28-31/28-35 in TMF environment 32-17 indexed 28-13/28-14, 28-17/28-18 input-output with description of 28-1/28-12 by called programs 28-7 Enscribe routines and 28-40/28-47 time limits on 28-7, 28-39 key-sequenced 28-13/28-14 locking 28-3 maximum number per volume 28-9 modifying 28-9 on other nodes 28-6 optimizing processing of 28-31/28-37 optimizing storage of 28-37 ownership of 28-3 partitioned 28-2, 28-37 permanent 26-2 purging 28-2 record blocking for 28-31/28-35 relative 28-12/28-13, 28-16/28-17 security of 28-3/28-6 sharing 28-8/28-9 structured description of 28-10 entry-sequenced 28-12, 28-14 improving performance of 28-31/28-35 indexed 28-13/28-14, 28-17/28-18 key-sequenced 28-13/28-14 record blocking for 28-31/28-35 relative 28-12/28-13, 28-16/28-17 temporary 26-3 types of 28-9 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -17 Index E Disk files (continued) unstructured description of 28-9 creating and using 28-15 faster processing of 28-31 with fixed-length records 28-6 with variable-length records 28-6 DISPLAY data format description of 7-70, 7-75 converting 27-14 SYNCHRONIZED clause and 7-87 DISPLAY statement description of 9-47/9-50 in OSS environment 19-24 unqualified 25-10 with NO ADVANCING phrase 9-2 with printer 30-22 with terminal 29-2/29-3, 29-10, 29-13 Displaying figurative constant values 9-49 large amounts of data 9-50 multiple values 9-49 nonnumeric values 9-49 numeric values 9-49 on devices 9-48 records 9-50 TACL commands 22-2 DIVIDE statement description of 9-50/9-57 precision of 8-50/8-51 Division operator 8-24, 8-46 DLLs See Dynamic-link libraries (DLLs) Dollar sign ($) 3-24, 7-57, 7-66 Dummy routines, files of 13-23 Dumps, online 32-17 Duplicate operations 32-7/32-8 Duplicate replies 6-64 Duplicate requests 6-64 DUPLICATES phrase description of 6-26 for indexed file 6-51 for relative file 6-45 for sequential file 6-34 Dynamic access mode DELETE statement and 9-47 file organization and 4-8 file processing and 6-25 Dynamic calls 23-6, 24-14 Dynamic file assignments 26-8, 27-3 Dynamic-link libraries (DLLs) 13-11/13-22 E EBCDIC code set 7-29 EBCDIC tape files 27-12 EDIT editor 22-7 EDIT files description of 22-5 creating and using 28-16 FILE-CONTROL paragraph and 6-33 variable-length records in 28-9 writing to 9-296 Editing in PICTURE clause description of 3-24, 7-63/7-68 fixed insertion 7-65 floating insertion 7-66 simple insertion 7-64 special insertion 7-64 zero suppression 7-67 of source code See Editors of TACL commands 22-4 Editors Codewright with TEC 22-11/22-12 EDIT 22-7 HP 22-24 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -18 Index E Editors (continued) PS TEXT EDIT (TEDIT) 22-8/22-10 VS full-screen 22-8 Elementary data items description of 4-1 clauses restricted to 7-46 default USAGE for 7-75 initializing 9-93 passed by content 23-21 passed by reference 23-23 redefined 7-49 storage allocation for 7-46 that cannot have VALUE clauses 7-89 USAGE clause and 7-72 Elements of HP COBOL language 3-1/3-24 of records 4-5 of tables 4-12 Embedded NonStop SQL/MP compiler listing and 22-48 format restrictions on 2-7 in user libraries 33-22 migrating to native mode and 33-22 Embedded SQL/MP 1-2, 34-3, 34-4, 34-7 Embedded SQL/MX 1-2, 34-3, 34-4, 34-7 EMS See Event Management Service (EMS) ENABLE utility 28-9 END PROGRAM statement 2-2 ENDIF directive 11-71 ENDUNIT directive 11-72 ENFORM programs 23-15 Enscribe database record manager 6-34, 28-10 Enscribe routines 28-40/28-47 ENTER COBOL statement 9-67 ENTER statement description of 9-58/9-66, 11-12/11-16, 23-7 at object program level 24-3 ENTER statement (continued) detailed explanation of 11-16/11-23 migrating to native mode and 33-15, 33-17 X/Open CALL statement and 9-29, 23-7 Enterprise Toolkit (ETK) debugging and 34-7 native COBOL cross compiler and 34-3 online help for 34-11 TACL DEFINE files and 34-2 Entry-sequenced files description of 28-12 alternate keys and 28-36 creating and using 28-14 ENV directive 11-72 description of 11-72/11-74 migrating to native mode and 33-13, 33-18 Environment compilation 22-20/22-22 run-time description of 23-2 determining 11-73, 22-19 for various languages 18-2 Environment Division description of 6-1/6-76 HP extensions affecting 17-3 summary of 41-1/41-22 syntax of 6-2 Environment variables 19-7, 35-10 Equal sign as operator 8-54 in pseudo-text delimiter 3-5 EQUAL TO operator 8-54 ERROR CODE phrase 6-67, 6-72, 11-25 Error codes for COBOLSPOOLOPEN routine 13-100 Error conditions 8-40 Error files 22-52 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -19 Index E Error messages Binder 22-52 compiler description of 22-49/22-52 See also Failure messages See also Warning messages characteristics of 47-1 ERROR directive and 11-76 ERRORFILE directive and 11-75, 22-15 format of 47-3 from other products 47-95 list of 47-4/47-93 run-time description of 25-14, 48-1 associated with tape files 27-26 external 8-34/8-39 fatal 8-42 format of CRE 48-5 non-CRE 48-2/48-4 Guardian abnormal termination 48-7/48-10 input-output 8-33/8-39, 48-6 list of 48-10/48-70 procedures for handling 25-14 program logic 8-33 SORT 48-6 ERRORFILE directive 11-75, 22-52 Errors See Error messages ERRORS directive 11-76 Error-handling procedures 25-14 Establishing starting points in disk files 28-20/28-30 ETK See Enterprise Toolkit (ETK) EVALUATE statement 9-67/9-75 Event Management Service (EMS) devices opening 13-77 sending events to 13-79 tracing facility and 33-8 Exact positioning 28-23 EXCEPTION phrase 9-22 Exclamation mark (!) 22-3, 30-16 Exclusion modes 4-10, 9-155, 28-6 EXCLUSIVE exclusion mode 4-10, 9-155, 28-38 Executable files See Loadfiles Execution of Declaratives Portion 8-20 of loadfiles 1-8 of paragraphs 8-17 of Procedure Division 8-16/8-20 of procedures 8-20 of programs description of 27-24/27-26 in Guardian environment 12-1/12-26, 25-9/25-14 in OSS environment 19-4 that use tape files 27-24/27-26 of sections 8-18 of sentences 8-17 of statements 8-16 Execution modes 1-3 EXECUTION-LOG parameter 12-13 EXIT statement 9-76/9-80 EXPIRATION attribute of DEFINE for labeled tape file 27-23 for unlabeled tape file 27-18 Expired time limit 8-41 Explicit scope terminators 8-7 Explicit transfer of control 8-18 Exponentiation operator description of 8-24, 8-46 migrating to native mode and 33-17 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -20 Index F Expressions arithmetic See Arithmetic expressions concatenation description of 8-69/8-70 summary of 38-13 conditional description of 8-53/8-69 summary of 38-9/38-12 EXTDECS file 23-13, 23-14 EXTDECS0 file 23-14 EXTDECS1 file 23-14 Extend open mode 4-10 Extended addressing 7-40 Extended entry point (XEP) table 24-17 EXTENDED parameter 11-125 EXTENDED-STORAGE access mode 7-40 Extended-Storage Section description of 7-37/7-38 backing up 9-255 checkpointing and 9-35 data description entries in 7-37 large amounts of data and 24-21 LESS-CODE 1 directive and 24-22 migrating to native mode and 33-18 Extensible parameter lists 23-13 Extensions to ISO/ANSI COBOL 17-1/17-5 Extents, file 28-2 EXTERNAL clause description of 7-11/7-13, 7-52/7-53 CRE and 18-5 heritability of 7-12 in record description entry 7-45 initializing data items and 7-36 REDEFINES clause and 7-50 External errors 8-34/8-39 External objects description of 2-17, 7-2 files connectors for 4-11 consistency of 7-12 keys in 7-12 names of 28-41 #RECEIVE blocks for 11-25 global 2-18 initialization of 7-36 items required to be 7-12 native user library and 13-10 records 7-52 sharing with C programs 23-17 status during program execution 12-25 switches 8-62, 9-224, 25-6 External references 24-3 F FACTORIAL function 14-19 FAIL misalignment handling method 33-9 Failure messages format of 47-3 in compiler listing 22-51 list of 47-4/47-93 FALL THROUGH field 9-286 FALSE value 8-54 Fast I-O See HP COBOL Fast I-O FastSort interface routines 13-25/13-26 Fatal errors 8-42 Fault-tolerant facility description of 32-3/32-14 debugging programs for 32-14 designing programs for 32-13 example of 32-12/32-13 FC command 22-4 FD entries See File description entries HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -21 Index F Federal Information Processing Standard (FIPS) 11-76 Figurative constants description of 3-21 defined by SYMBOLIC CHARACTERS clause 6-18 displaying values of 9-49 length associated with 3-22 program collating sequence and 6-18 where allowed 3-22 File assignments at compilation time 25-3 dynamic 26-8, 27-3 File attributes 28-41/28-42 File connectors description of 4-11 CANCEL statement and 9-32 external and internal 2-17 shared 7-11 File description entries description of 7-5/7-30 for line sequential files 19-14 record description entries and 7-47 File extents 28-2 File names COBOL associating with system file names 9-144, 26-5/26-9 characteristics of 26-4 HP, for permanent disk files 26-2 multiple, for one physical file 28-42 physical 28-41 scope of 2-13 special 26-5 system description of 26-2/26-4 for devices 26-3 for nondisk files 26-3 for temporary disk files 26-3 unqualified 11-36, 22-19 File numbers 28-41/28-42 File position indicators description of 4-11 OPEN statement and 9-146 timed input-output and 8-42 File Section 7-3/7-32 FILE STATUS clause description of 6-26 file type and 6-24 for indexed file 6-51 for line sequential file 6-40, 19-14 for relative file 6-44 for sequential file 6-33 File system 26-1 File system routines 23-10 File Utility Program (FUP) DDL compiler and 22-28 multiple-tape files and 9-40, 27-7 FILENAME-FINDNEXT-COMPLETION message 6-75 Files description of 4-6/4-12, 26-1/26-10 access modes of 4-8 assigned to disk devices 9-150 assigned to processes 9-149 assigned to tape devices 9-154 assigned to terminals 9-149 attributes of 28-41/28-42 audited 6-36, 32-17 blocking and deblocking 7-16 closing blocked 9-39 code 180 See Line sequential files command See OBEY command files created by programs 25-4 disk See Disk files EDIT See EDIT files HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -22 Index F Files (continued) error 22-52 exclusion modes of 4-10 executable See Loadfiles external 7-12 See External objects, files in OSS environment 19-8/19-11 indexed See Indexed files internal See Internal objects, files key-sequenced See Indexed files labeled See Labeled tape files line sequential See Line sequential files locking 9-37, 9-115/9-118, 26-9, 28-38 nonexistent 9-148, 9-151/9-152 numbers of 28-41/28-42 OBEY command 22-16 object See Object files of dummy routines 13-23 open modes of 4-10 opening 9-138/9-156 organization of 4-7 OSS 19-11 partitioned 28-37 positioning description of 28-23/28-30 approximate 28-24 exact 28-23 generic 28-24/28-26 to record with same alternate key 28-26/28-30 prereading records of 26-10, 27-1 processes treated as 26-10 Files (continued) purging description of 28-2 contents only 28-44 entire 28-43/28-44 queue See Queue files reading 9-177/9-200 relative See Relative files renaming 28-44 saveabend 11-111 scratch See Scratch file sequential See Sequential files shared 2-24 sort-merge See Sort-merge files swap See Swap file TACL DEFINE 34-2 tape See Tape files target 11-10 in single program unit compilation 11-11 temporary See Temporary files terminals as 29-4/29-5 type 101 See EDIT files type 106 22-52 unaudited 32-3 unqualified 22-19 updating 9-202 writing 9-292/9-305 FILES command 22-18 FILESEQ attribute of DEFINE 27-22 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -23 Index F File-control entries generally 6-23/6-27 for indexed files 6-47/6-53 for line sequential files 6-38/6-40, 19-12/19-14 for queue files 6-54 for relative files 6-40/6-46 for sequential files 6-28/6-37 for sort-merge files 6-55/6-56 FILE-CONTROL paragraph 6-23/6-56 FILE-GETINFOBYNAME-COMPLETION message 6-75 File-Mnemonic clause description of 6-14/6-15 migrating to native mode and 33-15 File-status data item description of 6-26 CLOSE statement and 9-38 UNLOCKRECORD statement and 9-271 FILE_GETINFO_ routine 28-42 FILLER bytes 4-16/4-18, 33-11, 33-12 FILLER keyword in DATA RECORDS clause 7-24 in record description entry 7-44, 7-48 FIPS directive 11-76 Fixed insertion editing 7-65 Fixed-length records description of 4-5, 7-20 in entry-sequenced files 28-12 in indexed files 28-14 in key-sequenced files 28-14 in relative files 28-13 in unstructured files 28-9 Fixed-size tables 7-79 FIXERRS macro 15-10, 22-52 Fixup operation 24-8/24-9 Flags (OSS) cobol utility 19-2 nmcobol utility 19-3 FLOAT directive 11-78 Floating insertion editing 7-66 FMAP directive description of 11-78 migrating to native mode and 33-20 Footing of page 7-26 Form names for spooler jobs 30-7 Formal parameters, adding 23-13 Format reference See ANSI reference format See Tandem reference format report 30-20/30-21 source program 2-1/2-24 standard COBOL 8-13 FORTRAN routines calling 9-58 in TNS user library 24-19 migrating to native mode 33-5 passing CHARACTER parameters to TAL routines 9-65 passing parameters to 9-62, 23-29/23-30 restrictions on 9-64, 23-18 run-time environment for 23-2 FROM phrase 8-27 FTP tool 34-11 Functions C and C++ 9-63/9-64 GIVING phrase and 9-61 intrinsic See Intrinsic functions Pascal 9-64 TAL 9-65 X/Open CALL statement and 9-19, 23-9 FUP See File Utility Program (FUP) HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -24 Index G G GENERIC phrase 9-238 Generic positioning 28-24/28-26 GETASSIGNTEXT routine 13-118/13-120 GETASSIGNVALUE routine 13-120/13-121 GETBACKUPCPU routine 13-122 getenv (C function) 9-64 GETPARAMTEXT routine 13-123/13-124 GETSTARTUPTEXT routine 13-125/13-126 GIVING phrase description of 9-61, 23-9 C functions and 9-64 GLOBAL clause 7-14, 7-53 Global names 2-16 GO TO statement description of 9-81/9-83 ALTER statement and 9-16 initial state of program and 12-24 PERFORM cycle and 9-158 program termination and 12-26 status during program execution 12-25 GREATER THAN operator 8-54 GREATER THAN OR EQUAL TO operator 8-54 Group data items See Data structures Guardian environment features 19-23/19-24 GUARDIAN-ERR special register 9-187, 13-82, 13-84, 13-93, 13-95 H HEADING directive 11-79 HEAP directive 11-80 Heritability of access mode 7-40 of EXTERNAL clause 7-12 of global attribute 7-54 Heritability (continued) of global names 2-16 of internal file access 9-28 Hexadecimal literals nonnumeric 3-20 numeric 3-18 Hierarchy of arithmetic operators 8-47 of qualified names 3-14 HIGH parameter 11-125 HIGHPIN directive description of 11-80/11-82 migrating to native mode and 33-18 HIGHREQUESTERS directive description of 11-83 migrating to native mode and 33-19 High-PIN requester servers 11-83 HIGH-VALUE or HIGH-VALUES figurative constant 3-23 HISTORY command 22-2 Home terminal 25-11 HP COBOL language description of 1-1/1-2 addressing parameters in 9-62 CRE support in 18-1/18-8 elements of 3-1/3-24 limits of 20-1/20-8 modules of 1-2 HP extensions to ISO/ANSI COBOL 17-1/17-5 HP NonStop Transaction Management Facility (TMF) description of 32-3, 32-14/32-20 debugging programs that use 32-20 designing programs for 32-18 requester screen transactions and 32-19 HP NonStop TS/MP system servers 32-3 HP Tandem Advanced Command Language See TACL HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -25 Index I HP Tandem Extensions for Codewright (TEC) 22-11/22-12 HP COBOL Fast I-O description of 28-34/28-35 audited files and 6-36 for indexed files 6-52 for relative files 6-46 for sequential files 9-190 WAITED-IO and 12-12 HP COBOL programs altering 22-5/22-10 called description of 11-4 reading disk files from 28-7 calling 11-4 common 2-14, 9-25, 23-5 compiling See Compilation creating 22-5/22-10 designed for fault-tolerant facility 32-13 designed for TMF 32-18 directly contained 23-4 divisions of 2-2 executing See Execution for both COBOL85 and NMCOBOL compilers 33-23 format and organization of 2-1/2-24 in same run unit 2-14 in TNS user library 18-6, 24-19 indirectly contained 23-4 initial See Initial programs initial state of 9-26 libraries of 11-73 logging activity of 30-22 main See Main programs migrating to native mode 33-1/33-23 HP COBOL programs (continued) nested See Nested programs non-COBOL characters in 3-3 OSS files in 19-11 OSS pathnames in 19-10 segmentation of 24-23 separately compiled See Separately compiled programs text manipulation in 10-1/10-18 with large amounts of code 24-17/24-20 with large amounts of data 24-21/24-22 with same name 9-25 Hyphen (-) See also Minus sign (-) in ANSI reference format 16-3 in COBOL words 3-7 in Tandem reference format 2-5 I IBM standard labels 27-20 ICODE directive description of 11-83 compiler listing and 22-41 migrating to native mode and 33-19 sample output from 22-55 IDE See Borland integrated development environment (IDE) Identification Division description of 5-1/5-6 summary of 40-1/40-2 Identification field 16-4, 22-43 Identifiers 4-24/4-25 IF directive 11-84 IF sentences 9-87 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -26 Index I IF statement description of 9-83/9-90 nested conditional 9-87 delimited-scope 9-84 IFNOT directive 11-84 Imperative statements 8-5 Implicit CLOSE statement 9-32 Implicit FILLER bytes 4-16/4-18, 33-11, 33-12 Implicit MOVE statement 9-93/9-94 Implicit transfer of control 8-18 Improving compilation speed 22-22 IN option of RUN command 22-13, 25-11, 26-6 Independent segments description of 8-14, 24-23 ALTER statement and 9-18 INDEX data format See also Indexes description of 7-70, 7-76 Indexed files description of 4-7 access modes of 4-9 closing 9-40 creating 28-17/28-18 determining key value of last record of 9-248 file description entries for 7-10 file-control entries for 6-24, 6-47/6-53 opening 9-138 poorly organized 6-52 rewriting 9-202/9-207 with alternate keys 28-18 writing 9-301/9-305 description of 28-13 INDEXED phrase 7-80 Indexes as parameters 9-28 converting to occurrence numbers 4-21 Indexes (continued) instead of subscripts 4-21, 7-82 MOVE statement and 9-128 Index-names description of 7-80 applied to different tables 7-82 as parameters 9-28 assigning values to 9-221/9-224 comparisons of 8-56 in Linkage Section 7-42 incrementing and decrementing 9-226 scope of 2-14 searching tables and 9-218 SET TO statement for 9-221/9-224 SET UP or SET DOWN statement for 9-226 INDEX-SLACK parameter 13-56, 13-60 Indicator area description of 22-43 in ANSI reference format 16-2 in Tandem reference format 2-4/2-6 Indirectly contained programs 2-10, 23-4 Initial programs description of 2-14, 23-5 CALL statement and 9-26 CANCEL statement and 9-32 storage allocation for 9-27 Initial state of program 9-26, 12-24 Initialization messages caused by 11-109, 11-128 of data items in Linkage Section 7-39 in Working-Storage Section 7-36 very large 11-54 when it occurs 7-36 of STRING statement 9-259 tallying and 9-99 INITIALIZE statement 9-91/9-94 Initiating processes 31-3/31-6 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -27 Index I INNERLIST directive description of 11-87 compiler listing and 22-41 migrating to native mode and 33-20 sample output from 22-55 Input See also Input-output description of 26-1/26-11 default device for 25-10 from disk files 28-1/28-47 from tape 27-1/27-26 from terminals 29-1/29-15 open mode 4-10 to compiler 1-5, 11-2/11-8 Input-output See also Input See also Output description of 8-28/8-42 default device for 25-5 errors diagnosing 8-33/8-39 messages for 48-6 recovering from 8-39/8-41 mixing COBOL and FORTRAN operations in 9-64 open mode 4-10 statements 9-148 status codes description of 8-28/8-42 DELETE statement and 9-46 GUARDIAN-ERR and 8-35/8-39 LOCKFILE statement and 9-116 OPEN statement and 9-144 timed 8-41/8-42 Input-Output Section 6-22/6-76 INSERTIONORDER parameter 6-27, 6-34, 6-51 INSPCI error messages 22-51 Inspect debugger description of 15-5 native COBOL cross compiler and 34-8 native programs and 33-6 symbol table for 11-130 INSPECT directive 11-88 INSPECT statement 9-95/9-115 INSTALLATION paragraph 5-2 Instruction Failure trap (trap 1) 33-9 Integer date format converting to Julian date format 14-18 to standard date format 14-17 obtaining from Julian date format 14-23 from standard date format 14-21 INTEGER function 14-20 Integer functions description of 14-5 DATE-OF-INTEGER 14-17 DAY-OF-INTEGER 14-18 FACTORIAL 14-19 INTEGER 14-20 INTEGER-OF-DATE 14-21 INTEGER-OF-DAY 14-23 INTEGER-PART 14-24 LENGTH 14-25 MOD 14-37 ORD 14-43 ORD-MAX 14-43/14-44 ORD-MIN 14-45/14-46 INTEGER-OF-DATE function 14-21 INTEGER-OF-DAY function 14-23 INTEGER-PART function 14-24 Intermediate data items 8-21, 8-44 Intermediate results 8-51 Internal objects description of 2-17, 7-2 CANCEL statement and 9-32, 12-26 file connectors 4-11 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -28 Index I Internal objects (continued) files, #RECEIVE blocks for 11-25 initialization of 7-36 status during program execution 12-25 Internal references 24-3 Interprocess communication example 31-13/31-15 Interrecord gaps 27-2 INTO phrase 8-27 Intrinsic functions description of 14-1/14-64 alphanumeric description of 14-3 CHAR 14-13/14-14 CURRENT-DATE 14-16 LOWER-CASE 14-28 REVERSE 14-53 UPPER-CASE 14-61 WHEN-COMPILED 14-63/14-64 arguments of 14-6 integer description of 14-5 DATE-OF-INTEGER 14-17 DAY-OF-INTEGER 14-18 FACTORIAL 14-19 INTEGER 14-20 INTEGER-OF-DATE 14-21 INTEGER-OF-DAY 14-23 INTEGER-PART 14-24 LENGTH 14-25 MOD 14-37 ORD 14-43 ORD-MAX 14-43/14-44 ORD-MIN 14-45/14-46 nested 14-3 numeric description of 14-4 ACOS 14-8 ANNUITY 14-9 ASIN 14-11 Intrinsic functions (continued) numeric (continued) ATAN 14-12 COS 14-15 LOG 14-26 LOG10 14-27 MEAN 14-31 MEDIAN 14-32 MIDRANGE 14-34 NUMVAL 14-38/14-39 NUMVAL-C 14-40/14-42 PRESENT-VALUE 14-47/14-48 RANDOM 14-49 REM 14-52 SIN 14-54 SQRT 14-55 STANDARDDEVIATION 14-56/14-57 TAN 14-60 VARIANCE 14-62/14-63 summary of 44-1/44-12 types of 14-3 variable-type description of 14-6 MAX 14-29/14-30 MIN 14-35/14-36 RANGE 14-50/14-51 SUM 14-58/14-59 INVALID KEY phrase in DELETE statement 9-45 in READ statement 9-197 in REWRITE statement 9-203, 9-207 in START statement 9-242, 9-244, 9-245 in WRITE statement 9-294 USE AFTER EXCEPTION procedures and 9-288 Invalid-key condition description of 8-40 for READ statement 9-199 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -29 Index J Invalid-key condition (continued) for REWRITE statement 9-207 for START statement 9-244 IN-FILE-COUNT parameter 13-56, 13-59 IN-FILE-EXCL parameter 13-56, 13-60 In-line PERFORM statement 9-159 I-O See Input-output I-O-CONTROL paragraph 6-57/6-63 I/O See Input-output Keys (continued) merge 9-122 of reference 28-21/28-22 record 6-51 relative 6-45 sort 9-231 Status Key 1 8-29 Status Key 2 8-30 Key-sequenced files See Indexed files L J JOB subcommand of SPOOLCOM utility 30-16 Jobs, spooler See Spooler jobs JOB-PROCESS-CREATION message 6-75 Julian date format converting to integer date format 14-23 obtaining from integer date format 14-18 JUSTIFIED clause description of 7-87 for INDEX data item 7-76 for NATIVE-n data item 7-76 K Key of reference OPEN statement and 9-146 READ statement and 9-199 KEY phrase 7-81 Keys alternate record for indexed files 6-51 for relative files 6-45 for sequential files 6-34 in external files 7-12 in START statement 9-244 locking 32-18 LABEL RECORDS clause description of 7-22 for labeled tape file 27-20 for unlabeled tape file 27-17 in external file 7-13 Labeled tape files description of 27-8/27-12 bypassing labels of 27-20 consistency checking of 27-10 converting programs to use 27-11 DEFINEs for 27-18/27-24 describing 27-10 mount messages for 27-25 OPEN statement and 9-146 LABELS attribute of DEFINE for labeled tape file 27-20 for unlabeled tape file 27-17 Language elements HP extensions affecting 17-2 ignored 20-8 summary of 38-1/38-6 Large data area description of 13-7 LARGEDATA directive and 11-88 LARGEDATA directive description of 11-88/11-90 migrating to native mode and 33-16 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -30 Index L Large-memory model 9-63 LD directive 11-91 ld utility native COBOL cross compiler and 34-7 NMCOBOL compiler and 33-21 Leading characters 9-97 LEFT keyword 7-87 LENGTH function 14-25 LESS THAN operator 8-54 LESS THAN OR EQUAL TO operator 8-54 LESS-CODE directive 11-91/11-93, 24-22 Level 2 spooler protocol 13-95/13-99 Level 66 data items 7-91 Level 77 data items 7-3, 7-93 Level 88 data items 7-95 Levels of data 4-1 Level-1 spooling 30-8 Level-2 spooling 30-9/30-10 Level-3 spooling 30-10 Level-numbers description of 4-2/4-3 in redefined data items 7-50 OCCURS clause and 7-81 LIB option of RUN command 24-9 Libraries description of 13-1/13-139 COPY See COPY libraries data declaration 22-26 dynamic-link (DLLs) See Dynamic-link libraries (DLLs) linkfiles as 13-8 migrating to native mode and 33-14, 33-21 native shared run-time See Native SRLs programs in 11-73 public shared run-time 13-1 Libraries (continued) shared run-time See Dynamic-link libraries (DLLs) See Native SRLs system 13-8 TNS 13-1 user See User library LIBRARY directive description of 11-93 migrating to native mode and 33-15, 33-16 Library programs 11-73 Limits of HP COBOL 20-1/20-8 LINAGE clause description of 7-24/7-25 in external files 7-13 LINAGE-COUNTER special register description of 7-28 qualified 3-14, 3-15 Line sequential files description of 4-7, 19-11/19-12 access modes of 4-8 closing 9-37/9-40 file description entries for 7-9/7-10 file-control entries for 6-24, 19-12/19-14 opening 19-17/19-19 reading 9-193/9-194, 19-20/19-21 repositioning 9-40 rewriting 9-208, 19-21/19-22 writing 9-300, 19-22 LINES directive 11-94 Linkage Section description of 7-38/7-42 absence of 7-42 data description entries in 7-39 initializing data items in 7-39 types of items in 7-41 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -31 Index L Linkfiles as libraries 13-8 combining into one DLL 13-16 when COBOL85 compler produces 11-27 when NMCOBOL compler produces 11-27 Linking called programs’ object code 11-23 HP COBOL programs automatically 24-10/24-13 to be called dynamically 24-14 with nld utility 24-14 native COBOL cross compiler and 34-7 PIC and non-PIC object files 11-55, 11-101, 11-116 LIST directive description of 11-95, 22-40 overriding 11-129 Listing cross-reference 22-41, 22-63, 33-22 directives that control 11-48 octal code 22-41, 22-54 symbol table 22-53 symbolic code 22-41, 22-55 Literals description of 3-16/3-23 national See National literals NATIVE-8 data format and 7-76 nonnumeric See Nonnumeric literals numeric See Numeric literals LMAP directive description of 11-96/11-97 compiler listing and 22-41 migrating to native mode and 33-19 sample output from 22-63 Load maps 22-41, 22-63 Loadfiles executing 1-8 in OSS 1-4 main programs and 11-3 of separately compiled parts 1-7 on PC 1-4 processes and 24-8 RUNNABLE directive and 11-107 running as processes 12-2 when COBOL85 compler produces 11-27 when NMCOBOL compler produces 11-27 Local buffering for indexed files 6-52 for relative files 6-46 for sequential files 6-36 Local names 2-16 LOCK phrase for relative, indexed, or queue file 9-41 for sequential or line sequential file 9-38 Locked open mode 4-10 LOCKFILE statement 9-115/9-118 Locking files 9-37, 26-9, 28-3, 28-38 keys 32-18 records 28-38, 32-18 LOG function 14-26 LOG10 function 14-27 Logging program activity to printer 30-22 to terminal 29-14 Logical operators in combined conditions 8-65 in conditional expressions 8-64 Logical pages 7-26 Logical records 4-4 LOGICAL-CLOSE message 6-75 LOGICAL-OPEN message 6-75 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -32 Index M LOWER-CASE function 14-28 LOW-VALUE or LOW-VALUES figurative constant 3-23 M MAIN directive 11-98 Main programs description of 11-3, 11-98, 23-3 CANCEL statement and 9-33 identifying 7-42 Manipulating object files 11-28, 33-21 MAP directive 11-99, 22-41, 22-53 Margins See also Reference format A 2-4, 2-6, 16-4 B 16-4 C 2-4, 16-2 L 16-1 R 2-6, 16-4 top and bottom 7-26 MAX function 14-29/14-30 Maximum code block size 24-18 MEAN function 14-31 MEDIAN function 14-32 MEM option of RUN command 25-4 Memory 31-2 Memory areas 13-6/13-7 MEMORY-LOCK-COMPLETION message 6-75 MEMORY-LOCK-FAILURE message 6-75 MEMORY-SIZE clause 6-5, 6-6 Merge keys 9-122 MERGE statement 9-119/9-127 Message indicator line 47-2 MESSAGE SOURCE phrase description of 6-67, 6-72 CRE and 18-5 operating system messages and 26-11 #RECEIVE and 11-25 Messages determining source of 31-24 error See Error messages failure 47-3 generated by asynchronous hardware events 6-74 initialization 11-109, 11-128 REPORT clause 6-75 saved 13-36 system CRE and 18-6 intercepting 26-10 list of 6-73 tape mount 13-84 warning 8-34, 47-3 MESSAGE-CANCELLED message 6-75 MESSAGE-MISSED message 6-75 MIDRANGE function 14-34 Migrating to native mode description of 33-1 guidelines for 33-3/33-22 reasons for 33-2/33-3 MIN function 14-35/14-36 MINSPACE parameter 13-56, 13-60 MINTIME parameter 13-56, 13-61 Minus sign (-) See also Hyphen (-) as arithmetic operator 8-46 in PICTURE clause 3-24, 7-57, 7-65, 7-66 MISALIGNLOG attribute (SCF) misalignment handling and 33-8 misalignment tracing facility and 33-7 Misalignment See Address misalignment Misalignment tracing facility 33-7/33-8 Mixed-language programs description of 23-1 binding 24-16 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -33 Index N Mixed-language programs (continued) CRE and 18-1 data type correspondence and B-1 DDL and 22-25 ENTER statement and 9-58 in OSS environment 19-5/19-6 sharing data 23-17 sharing standard files 28-8 Mnemonic codes in compiler listing COBOL85 compiler 11-83 NMCOBOL compiler 11-87 Mnemonic names for object files 24-11 for terminals 29-2 MOD function 14-37 Modules of HP COBOL 1-2 Mount messages See Tape mount messages MOVE statement explicit description of 9-128/9-132 instead of ALTER statement 9-17 implicit 9-93/9-94 Multidimensional tables 7-82, 9-209, 9-212 Multiple COPY libraries 22-33 MULTIPLE FILE clause description of 6-59, 6-63 LABEL RECORDS clause and 7-22 labeled tape files and 27-22 Multiple-file tapes 27-5 Multiple-file transactions 32-16 Multiple-reel tape files 9-39, 9-297, 27-6 Multiplication operator 8-46 MULTIPLY statement description of 9-132/9-138 precision of 8-50 N Named processes 11-108, 25-12/25-13 Names global 2-16 local 2-16 qualified 3-13/3-16 unqualified 11-36 user-defined 3-10 National class and category 4-1 National data items alignment of data in 4-15 BLANK WHEN ZERO clause and 7-88 CHARACTER-SET clause and 6-8 comparisons of 8-56 in INSPECT statements 9-97 in PICTURE clause 7-62 in STRING statement 9-260 in UNSTRING statement 9-281 MOVE statements and 9-129 SIGN clause and 7-79 SPECIAL-NAMES paragraph and 6-10 SYNCHRONIZED clause and 7-87 USAGE clause and 7-72 National literals description of 3-20 CHARACTER-SET clause and 6-8 comparisons of 8-56 continuing in ANSI format 16-3 in Tandem reference format 2-5 in INSPECT statements 9-97 in STRING statement 9-260 in UNSTRING statement 9-281 punctuation characters in 3-6 restrictions on 3-21 SIGN clause and 7-79 SPECIAL-NAMES paragraph and 6-10 USAGE clause and 7-72 N in PICTURE clause 7-55 NAME option of RUN command 25-12 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -34 Index N Native COBOL cross compiler description of 34-1/34-11 ar utility and 34-10 compilation with 34-7 debugging on 34-7/34-10 documentation for 34-11 environments for 34-1 features of 34-2 file extension for 34-4 from PC command line 34-4 in ETK (NonStop COBOL) 34-3 in TDS (Tandem NMCOBOL) 34-4 linking and 34-7 online help for 34-11 OSS environment and 34-5 PC-to-NonStop host transfer tools and 34-11 Native mode migrating HP COBOL programs to 33-1/33-23 Native programs debugging after migration 33-6 on PC 34-7/34-10 that can also be compiled as TNS programs 33-23 Native SRLs description of 13-1/13-2 diagram of 13-2 Native user library building 13-10 in binding 24-6 migrating to native mode and 33-5 UL directive and 11-135 NATIVEATOMICMISALIGN attribute (SCF) 33-8 NATIVE-n data format description of 7-76, 7-70 compared to COMPUTATIONAL data format 7-77 NATIVE-n data format (continued) compared to COMPUTATIONAL-5 data format 7-77 PORT directive and 11-105 tape input-output and 27-15 Natural logarithm function 14-26 Negated conditions 8-64 Negative zero 8-44 Nested intrinsic functions 14-3 Nested programs description of 2-9/2-14, 23-4/23-5 code and data blocks and 24-2 directly contained 2-10 indirectly contained 2-10 precedence rules for 9-290 Nested SOURCE directives 11-120 Nested statements IF conditional 9-87 delimited-scope 9-84 PERFORM 9-160 NetBatch system 22-22 NEWPROCESS routine 24-9 NEWPROCESSNOWAIT-COMPLETION message 6-76 NEWPROCESS-COMPLETION message 6-75 Next executable statement 8-19 Next record 9-189 NEXT SENTENCE phrase 9-86 Nibbles 7-69 NLD directive 11-99 nld utility native COBOL cross compiler and 34-7, 34-10 NMCOBOL compiler and 33-21 NMCOBEX0 file 11-15, 23-14 NMCOBEX1 file 11-15, 23-14 NMCOBEXT file 11-15, 13-23, 23-13/23-15, 24-6 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -35 Index N NMCOBOL compiler See also Compiler See also nmcobol utility (OSS) description of 1-4 object files produced by 11-27, 33-21 nmcobol utility (OSS) 19-3/19-4 NO ADVANCING phrase 9-50 NO REWIND phrase 9-38 NOBLANK directive description of 11-54 initial state of program and 12-24 initializing data items and 7-36 migrating to native mode and 33-15 NOCANCEL directive description of 11-56 CANCEL statement and 9-33 NOCODE directive description of 11-58 compiler listing and 22-41 migrating to native mode and 33-18 NOCOMPACT directive description of 11-60/11-61 migrating to native mode and 33-18 NOCONSULT directive description of 11-62/11-63 migrating to native mode and 33-19 NOCROSSREF directive description of 11-63/11-66 compiler listing and 22-41 migrating to native mode and 33-18 NODE-DOWN message 6-76 NODE-UP message 6-76 NODIAGNOSEALL directive 11-71 NODIAGNOSE-74 directive 11-66/11-69 NODIAGNOSE-85 directive 11-70 NOFIPS directive 11-76 NOFLOAT directive 11-78 NOICODE directive description of 11-83 compiler listing and 22-41 migrating to native mode and 33-19 NOINNERLIST directive description of 11-87 compiler listing and 22-41 migrating to native mode and 33-20 NOINSPECT directive 11-88 NOLIST directive 11-86, 11-95, 22-40 NOLMAP directive description of 11-96/11-97 compiler listing and 22-41 migrating to native mode and 33-19 NOMAP directive 11-99, 22-41 Nonatomic access 33-8 Nonconforming elements 11-125 Noncontiguous elementary data items 7-93 Nondefault character sets 6-9 Nondisk files default input-output 25-5 system file names of 26-3 Nonexecutable files See Linkfiles Nonnumeric comparisons 8-55 Nonnumeric data items DISPLAY statement and 9-49 initializing 7-90 VALUE clause and 7-90 Nonnumeric literals continuing in ANSI format 16-3 in Tandem reference format 2-5 hexadecimal 3-20 punctuation characters in 3-6 simple 3-19 Nonprinting characters 6-18 NonStop COBOL 34-3 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -36 Index N NONSTOP directive description of 11-100 fault-tolerant facility and 32-9 migrating to native mode and 33-19 overriding 25-5 NonStop SQL/MP See Embedded NonStop SQL/MP NonStop TS/MP See HP Nonstop TS/MP Non-COBOL programs 9-58, 11-4, 23-7/23-19 Non-CRE environment 11-72, 28-32 NON-SHARED directive 11-101 NOPORT directive 11-104 NOPURGE-OUTPUT parameter 13-56, 13-61 NOROUND misalignment handling method 33-9 NOSAVEABEND directive description of 11-111 migrating to native mode and 33-17 NOSEARCH directive description of 11-112/11-113 migrating to native mode and 33-19 NOSHOWCOPY directive 11-117, 22-45 NOSHOWFILE directive 11-118 NOSQL directive description of 11-122/11-124 migrating to native mode and 33-19 NOSUPPRESS directive 11-129 NOSYMBOLS directive 11-130 NOT AT END phrase in READ statement 9-180, 9-185, 9-187, 9-194 in RETURN statement 9-201 NOT EQUAL TO operator 8-54 NOT EXCEPTION phrase 9-23 NOT GREATER THAN operator 8-54 NOT INVALID KEY phrase in DELETE statement 9-45 in READ statement 9-197 NOT INVALID KEY phrase (continued) in REWRITE statement 9-203, 9-207 in START statement 9-242, 9-245, 9-246 in WRITE statement 9-295 NOT LESS THAN operator 8-54 NOT modifier 8-59, 8-63 NOT SIZE ERROR phrase in ADD CORRESPONDING statement 9-14 in ADD GIVING statement 9-12 in ADD TO statement 9-9 in COMPUTE statement 9-41 NOTRAP2 directive description of 11-132/11-134 migrating to native mode and 33-19 NOTRAP2-74 directive description of 11-134/11-135 migrating to native mode and 33-19 NOWAIT option of RUN command 22-15, 25-13 NOWAIT-IO parameter 13-56, 13-61 NOWARN directive 11-136, 22-40 NO-CPU-MASK parameter 13-53 NULL pointer value in relation condition 8-58 in SET TO statement 9-221 Null values for alternate record keys 28-36 Numeric class and category 4-1 NUMERIC class test 8-59 Numeric comparisons 8-55 Numeric data items ACCEPT statement and 9-3 alignment of data in 4-15 displaying values of 9-49 initializing 7-89 PICTURE clause and 7-61 reading and writing 29-13 VALUE clause and 7-89 Numeric edited category 4-1 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -37 Index O Numeric edited data items ACCEPT statement and 9-3 alignment of data in 4-15 MOVE statements and 9-130 PICTURE clause and 7-62 Numeric functions description of 14-4 ACOS 14-8 ANNUITY 14-9 ASIN 14-11 ATAN 14-12 COS 14-15 LOG 14-26 LOG10 14-27 MEAN 14-31 MEDIAN 14-32 MIDRANGE 14-34 NUMVAL 14-38/14-39 NUMVAL-C 14-40/14-42 PRESENT-VALUE 14-47/14-48 RANDOM 14-49 REM 14-52 SIN 14-54 SQRT 14-55 STANDARD-DEVIATION 14-56/14-57 TAN 14-60 VARIANCE 14-62/14-63 Numeric literals COMPUTATIONAL-5 data items and 7-75 decimal 3-17/3-18 hexadecimal 3-18 passed by content 23-22 punctuation characters in 3-6 NUMVAL function 14-38/14-39 NUMVAL-C function 14-40/14-42 O OBEY command files for BIND utility 24-15 for CROSSREF utility 15-9 for pre-execution preparation 25-7/25-8 for running compiler 22-16 Object files See also Linkfiles See also Loadfiles adding to primary search list 24-12 adding to tertiary search list 24-13 as user libraries 24-12/24-13 binding 11-23 creating 11-27/11-28 default names for 22-16 description of 24-2 establishing mnemonic names for 24-11 manipulating 11-28, 33-21 naming 22-16 production of 24-4 reducing size of 11-56, 11-91 specifying 24-10 Object programs 11-28 OBJECT-COMPUTER paragraph 6-5/6-9 Obsolete elements 11-125 OBSOLETE parameter 11-126 OCCURS clause ALL subscript and 14-7 in record description entry for fixed-size table 7-79 for variable-size table 7-83 in redefined data item 7-50 Octal code listing 11-58, 22-41, 22-54 ODDUNSTR attribute 7-17 Offsets for fields 33-11 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -38 Index O OMITTED keyword in COBOLLIB routines 13-85 in ENTER statement 9-60 in ZCOBSRL routine 13-38 Omitted parameters 11-23 Online dumps 32-17 Online help for native COBOL cross compiler 34-11 OPEN message 6-76 Open modes description of 4-10 initial state of program and 12-24 of external files 7-13 summary of 9-148 OPEN routine 13-139 OPEN statement description of 9-138/9-156 fault-tolerant facility and 32-10 Open System Services (OSS) environment description of 19-1/19-25 native COBOL cross compiler and 34-5 Operands arithmetic 8-46 identification of description of 8-21 in ADD TO statement 9-11 overlapping description of 8-22 in INITIALIZE statement 9-94 in INSPECT CONVERTING statement 9-115 in STRING statement 9-260 in UNSTRING statement 9-280 pointer 8-58 Operating system routines description of 23-10/23-15, 28-40/28-47 generations of 23-14 parameters for 23-10 resolution of 23-13/23-15 Operators arithmetic 8-46 communicating with 29-10/29-14 logical in combined conditions 8-65 in conditional expressions 8-64 prompting 29-6/29-7 relational 8-54 Optimization of disk file processing 28-31/28-37 of disk file storage 28-37 OPTIMIZE directive description of 11-102 migrating to native mode and 33-16 ORD function 14-43 ORD-MAX function 14-43/14-44 ORD-MIN function 14-45/14-46 Organization of files 4-7 of HP COBOL programs 2-1/2-24 ORGANIZATION clause description of 6-25 file type and 6-24 for indexed file 6-49 for line sequential file 6-39, 19-13 for queue file 6-54 for relative file 6-43 for sequential file 6-31 OSS See Open System Services (OSS) environment OSS ASCII text files See Line sequential files OUT option of RUN command 22-14, 25-11, 26-7 Output See also Input-output description of 26-1/26-11 default device for 25-10 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -39 Index P Output (continued) from compiler 1-6, 11-25/11-33 merged 9-119 open mode 4-10 to disk files 28-1/28-47 to printers 30-1/30-22 to spoolers 30-1, 30-7/30-22 to tape 27-1/27-26 to terminals 29-1/29-15 waited 23-10 OUT-FILE-EXCL parameter 13-56, 13-62 OUT-FILE-FORMAT parameter 13-56, 13-62 Out-of-line PERFORM statement 9-159 Overflow arithmetic COBOL85^ARMTRAP and 13-39 CRE and 18-6 TRAP2 and NOTRAP2 and 11-132 TRAP2-74 and NOTRAP2-74 and 11-134 in STRING statement 9-260 page 9-294, 9-298 size error condition and 8-24 Overlapping operands description of 8-22 in INITIALIZE statement 9-94 in INSPECT CONVERTING statement 9-115 in STRING statement 9-260 in UNSTRING statement 9-280 Overprinting lines in output 30-19 Ownership of Break key 29-8/29-9 of disk files 28-3 of spooler jobs 30-4 P P in PICTURE clause 7-56 PACKED-DECIMAL data format 7-69/7-72, 7-74 PADDING CHARACTER clause file type and 6-24 in external file 7-12 in sequential file 6-31 Page overflow condition 9-294, 9-298 Pages, logical 7-26 Paragraphs execution of 8-17 syntax of 8-11 Paragraph-names identical 3-16 qualified 3-13, 3-15 PARAM commands description of 11-34, 12-9/12-16 DEBUG 12-10, 15-2, 25-4 EXECUTION-LOG 12-11, 25-5 INSPECT 12-11 maximum number of 25-8 NONSTOP 12-11, 25-5 OSS environment and 19-23 PRINTER-CONTROL 25-6, 30-22 SAMECPU 11-34, 22-20, 22-22 showing active 25-8 SWAPVOL 11-35, 22-22 SWITCH-nn 12-10, 25-6 SYMBOL-BLOCKS description of 11-35, 22-22 migrating to native mode and 33-6 WAITED-IO 12-11, 25-7 PARAM message portions 13-36 Parameters adding formal 23-13 addressing 9-62 arithmetic expressions as 23-22 COBOL file names as 23-22 declaring 9-27 elementary data items as 23-21, 23-23 established with FastSort 13-25 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -40 Index P Parameters (continued) established with =_SORT_DEFAULTS DEFINE 13-26 extensible 23-13 for operating system routines 23-10 formal, adding 23-13 index values as 9-28 lists of 23-13 numeric literals as 23-22 omitted 9-60, 11-23 passing See Passing parameters presenting 11-22 records as 23-23 reference 33-10 replacing code blocks and 24-16 string:length 9-60, 9-65, 23-33, 33-4 tables as 23-22 validation of 9-27 variable 23-13 Parentheses as separators 3-5 in arithmetic expressions 8-47 in conditions 8-68 Partitioned disk files 28-2, 28-37 Pascal routines addressing parameters in 9-63 calling 9-58 in TNS user library 24-19 migrating to native mode 33-5 passing parameters to 23-31/23-32 restrictions on 9-64, 23-19 run-time environment for 23-2 Passing parameters description of 23-19/23-34 by content 9-21, 23-21/23-22 by reference 9-21, 9-61, 11-23, 23-23 by value 9-21, 9-61, 11-22, 23-23 CALL statement and 9-27/9-28 Passing parameters (continued) COMPUTATIONAL-5 7-75 FORTRAN, to TAL routines 9-65 to COBOL programs 23-24/23-25 to non-COBOL routines description of 23-25/23-34 C and C++ 23-26/23-29 FORTRAN 23-29/23-30 Pascal 23-31/23-32 TAL 23-32/23-34 Passwords, remote 28-6 Pathnames for OSS files 19-8/19-9 PC-to-NonStop host transfer tools 34-11 PEP (program entry point) table 24-17 PERFORM cycle 9-158 PERFORM LOOP field 9-286 PERFORM statement description of 9-157/9-177 CALL statement and 9-26 initial state of program and 12-24 status during program execution 12-25 PERFORM-TRACE directive 11-103 Period (.) See also Decimal point as separator 3-5 format restrictions on 2-7 in delimited-scope IF statement 9-84 in PICTURE clause 3-24, 7-57, 7-64 PERUSE utility 22-14, 30-3, 30-11/30-15 Physical records 4-4 PIC See Position-independent code (PIC) PICTURE character-strings description of 3-24 editing characters in 3-24 punctuation characters in 3-6 size of 7-55 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -41 Index P PICTURE clause description of 7-54/7-68 for BINARY/COMPUTATIONAL data item 7-73 for COMPUTATIONAL-5 data item 7-75 for INDEX data item 7-76 for NATIVE-n data item 7-76 in record description entry 7-45 NUMERIC class test and 8-60 Plus sign (+) as editing character 3-24 in PICTURE clause 7-57, 7-65, 7-66 Pointer class and category 4-1 POINTER data format description of 7-70, 7-77 in relation conditions 8-58 PORT directive and 11-105 SYNCHRONIZE clause and 7-87 Pointers alignment of targets of 33-10 as operands 8-58 assigning values to 9-220/9-221 decrementing 9-225/9-226 incrementing 9-225/9-226 initializing 7-90 on IBM/370 machine 9-226 SET TO statement for 9-220/9-221 SET UP or DOWN statement for 9-225/9-226 VALUE clause and 7-90 PORT directive description of 11-104 CALL statement and 9-18, 23-7, 23-19 misaligned addresses and 33-12 unmatched items and 7-41 POSITION phrase 9-238, 28-26/28-30 Positioning, file description of 28-23/28-30 approximate 28-24 exact 28-23 Positioning, file (continued) generic 28-24/28-26 to record with same alternate key 28-26/28-30 Position-independent code (PIC) CALL statement and 9-25 CALL-SHARED directive and 11-55 debugging 33-23, 34-8 dynamic-link libraries and 13-11 SHARED directive and 11-116 Power, raising to a See Exponentiation operator POWER-ON message 6-76 Precedence of arithmetic operators 8-47 of nested programs 9-290 of PICTURE clause symbols 7-58 of SIGN clauses 7-79 Precision arithmetic 8-48/8-53 of ADD statement 8-49 of DIVIDE statement 8-50/8-51 of MULTIPLY statement 8-50 of SUBTRACT statement 8-49 Predefined DEFINEs 11-36, 22-19 Prereading file records 9-156, 26-10, 27-1 Presenting parameters 11-22 PRESENT-VALUE function 14-47/14-48 Pre-execution preparation description of 25-1/25-9 OBEY command files for 25-7/25-8 Primary process 32-4/32-6 Primary search list adding file to 24-12 binding or linking and 24-6, 24-10 unqualified references and 11-14 Primary (or prime) record keys 28-13 Print process 30-3 Printer control tape channel punch 30-19 Printer file records 9-154 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -42 Index P Printers DISPLAY statement and 30-22 logging program activity to 30-22 out of paper 30-22 output to description of 30-1/30-22 formatting of 30-20/30-21 vertical spacing in 30-18/30-20 unavailable 25-6 WRITE statement and 30-22 writing to 29-12 PRINTER-CONTROL parameter 12-12, 12-14 Priority of spooler jobs 30-6 PRIORITY parameter 13-56, 13-62 Procedure Division description of 8-1/8-69 components of 8-1, 8-2/8-3 example of 8-3 execution of 8-16/8-20 HP extensions affecting 17-4/17-5 summary of 43-1/43-59 syntax of 8-2 verbs in 9-1/9-305 Procedures error-handling 25-14 execution of 8-20 manipulating 33-21 syntax of 8-14 Process file segment 24-8 Process pairs description of 32-4/32-6 activity of 32-5/32-6 CANCEL statement and 9-33 checkpoint lists for 13-35 CHECKPOINT statement and 9-34, 9-36 CLOSE statement and 9-40 example of 32-12/32-13 mechanisms for 32-2/32-3 Process pairs (continued) migrating to native mode and 33-19 naming 25-12/25-13 NONSTOP directive and 11-100 OPEN statement and 9-154 OSS environment and 19-24 SQL databases and 9-36 Processes description of 24-8 background 25-13 backup 9-253, 32-4/32-6 changing creator IDs of 31-39 collector 30-3 communicating with 29-10/29-14, 31-6/31-18 definition of 12-1 descendants of 31-35 determining handles of 31-22 determining nodes of 31-23 determining status of 31-26/31-33 fault-tolerant 32-1/32-20 identifying creators of 31-33 initiating 31-3/31-6 involved in compilation 11-9 managing 31-22/31-40 named 11-108, 25-12/25-13, 31-12 primary 32-4/32-6 print 30-3 receiving from 29-12 requesting 6-70 separate 24-19 supervisor 30-3 suspending 31-39 treated as files 26-10 unnamed 9-254 with timestamp names 25-12 Processor used by compilation processes 22-20 PROCESS-CREATE-COMPLETION message 6-76 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -43 Index Q PROCESS-DELETION message 6-76 PROCESS-TIME-SIGNAL message 6-76 Production systems 33-9 Program collating sequence 6-18 PROGRAM COLLATING SEQUENCE clause description of 6-5, 6-7 MERGE statement and 9-123 Program entry point (PEP) table 24-17 Program logic errors 8-33 Programs called See Called programs calling See Calling programs and routines compatible 11-74 ENFORM 23-15 HP COBOL See HP COBOL programs mixed-language See Mixed-language programs native See Native programs non-COBOL 9-58, 11-4, 23-7/23-19 source See HP COBOL programs PROGRAM-ID paragraph 5-2, 5-4/5-5 Program-name, scope of 2-12 PROGRAM-STATUS special register 9-254, 32-10/32-12 PROGRAM-STATUS-1 special register 9-254 PROGRAM-STATUS-2 special register 9-254 PROMPT phrase 9-181 Prompting an operator 29-6/29-7 PROTECTED exclusion mode 4-10, 9-155, 28-38 PS TEXT EDIT (TEDIT) editor description of 22-8/22-10 commands of 22-10 PS TEXT EDIT (TEDIT) editor (continued) customizing 22-10 second window of 22-9 Pseudorandom number function 14-49 Pseudo-text COPY statement and 22-32 delimiter for 3-5 REPLACE statement and 22-37 pTAL routines migrating to native mode and 33-4 passing parameters to 9-63 Public shared run-time libraries See Native SRLs Punctuation characters description of 3-4/3-6 as separators 3-4/3-5 in comments 3-6 in literals national 3-6 nonnumeric 3-6 numeric 3-6 in PICTURE character-strings 3-6 Purging files description of 28-2 contents only 28-44 entire files 28-43/28-44 PUTASSIGNTEXT routine 13-127/13-130 PUTASSIGNVALUE routine 13-131/13-133 PUTPARAMTEXT routine 13-133/13-135 PUTSTARTUPTEXT routine 13-136/13-138 Q Qualification in CALL and ENTER statements 11-13 of data items ordinary 4-19 redefined 7-50 summary of 39-1/39-4 of file names 5-5 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -44 Index R Qualification (continued) of names 3-13/3-16 of references 11-13 operand identification and 8-21 Question mark (?) as TACL command 22-2 in ANSI reference format 16-2 in Tandem reference format 2-4 Queue files description of 4-8, 28-13 access modes of 4-9 closing 9-40 creating 28-19 determining key value of last record of 9-248 file description entries for 7-10 file-control entries for 6-24, 6-54 opening 9-138, 28-19 reading 28-20 removing records from 28-20 rewriting 9-202/9-207 writing 9-301/9-305, 28-20 Queuing printer file records 9-154 Quotation mark (") as separator 3-5 figurative constant for 3-23 in CALL statement 9-20, 24-11 in ENTER statement 9-59, 24-11 in literal hexadecimal nonnumeric 3-20 national 3-21 simple nonnumeric 3-19 QUOTE or QUOTES figurative constant 3-23 R Radix 10 7-69 Raising to a power See Exponentiation operator Random access mode description of 4-8 DELETE statement and 9-47 key values and 6-25 RANDOM function 14-49 RANGE function 14-50/14-51 READ statement description of 9-177/9-200 for line sequential file 19-20/19-21 LOCKFILE statement and 9-117, 9-186 READ NEXT 9-189 Reading from called programs 28-7 from processes 29-12 from tape files description of 27-1/27-15 labeled 27-8/27-12 other than HP 27-12/27-15 unlabeled 27-3/27-8 from terminals 29-12 numeric data 29-13 READWRITE (PROMPT phrase) 9-181 RECEIVE-CONTROL paragraph description of 6-64/6-76, 31-16 for run unit 6-64 without reply table 6-71 Receive-control table 6-70, 31-16 Receiving data items description of 8-21 in INITIALIZE statement 9-93 RECFORM attribute of DEFINE for labeled tape file 27-21 for unlabeled tape file 27-17 RECORD CONTAINS clause description of 7-17/7-21, 7-31 for labeled tape file 27-21 for unlabeled tape file 27-16, 27-17 in external file 7-13 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -45 Index R RECORD DELIMITER clause description of 6-25 file type and 6-24 for sequential file 6-31 in external file 7-12 RECORD KEY clause description of 6-50 file type and 6-24 Record keys alternate 28-22/28-23 OCCURS clause and 6-51 primary or prime 28-13 Records description of 4-4/4-6 blocking 27-2, 28-31/28-35 deleted 28-14 description entries for description of 7-2, 7-43/7-90 file description entries and 7-47 displaying 9-50 elements of 4-5 external 7-52 fixed-length 7-20 gaps between 27-2 implicit FILLER bytes and 4-17 in Extended-Storage Section 2-17, 24-22 in Linkage Section 2-18 in Working-Storage Section 2-17 keys to See Record keys length of 4-5 locking 28-38, 32-18 logical 4-4 names of identical 3-16 scope of 2-13 numbers for 28-12, 28-16 offsets for fields of 33-11 Records (continued) passed by reference 23-23 physical 4-4 prereading 9-156, 26-10, 27-1 short 7-20 variable-length 7-18 zero-length 28-11, 28-12 Recovery, roll-forward 32-17 Recursion 2-12, 9-28 Redefined data items 7-81 REDEFINES clause EXTERNAL clause and 7-50 GLOBAL clause and 7-54 implicit FILLER bytes and 4-18 in record description entry 7-45, 7-48/7-49 in redefined data item 7-50 OCCURS DEPENDING clause and 7-85 REEL phrase 9-38 Reel swaps 13-84 Reexecuting TACL commands 22-3, 22-4 Reference format ANSI See ANSI reference format COPY libraries and 10-13 COPY statement and 10-5 REPLACE statement and 10-17 source program lines and 2-3, 22-6, 22-42 Tandem See Tandem reference format text libraries and 22-22 Reference modifiers description of 4-22/4-26 migration to Native mode and 33-10 operand identification and 8-21 TAL routines and 9-65 REFERENCE parameters 33-10 Reference parameters 11-23, 23-23 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -46 Index R References external 24-3 internal 24-3 qualification of 11-13 References (continued) to data items 4-18/4-26 unresolved 24-8, 24-9 validation of 24-4, 24-6/24-7 Relation conditions generally 8-54, 8-57 abbreviated combined 8-66 with nonpointer operands 8-57 with pointer operands 8-58 Relational operators 8-54 Relative files description of 4-7, 28-12/28-13 access modes of 4-9 alternate keys and 28-16, 28-36 closing 9-40 creating 28-16/28-17 file description entries for 7-10 file-control entries for 6-24, 6-40/6-46 opening 9-138 rewriting 9-202/9-207 writing 9-301/9-305 RELATIVE KEY clause description of 6-43 file type and 6-24 Relative record keys 6-45 RELEASE statement 9-200 REM function 14-52 Remainder function 14-52 Remote passwords 28-6 REMOTE-CPU-DOWN message 6-76 REMOTE-CPU-UP message 6-76 REMOVAL phrase 9-38 REMOVE-DUPLICATES parameter 13-56, 13-63 RENAMES clause 7-91/7-92 Renaming of data items 7-91 of files 28-44 REPLACE statement description of 10-14/10-18 compiler listing and 22-44 COPY libraries and 22-38 IF directive and 11-85 REPLACING phrase of COPY statement and 22-38 SOURCE libraries and 22-39 source manipulation and 22-36/22-39 substrings and 22-37 Replacement of code blocks 24-15/24-16 with tallying 9-107 without tallying 9-103, 9-113 REPLACING phrase description of 10-7/10-11, 22-31 REPLACE statement and 22-38 substrings and 22-32 REPLY CONTAINS phrase 6-67 Reply table 6-70, 31-16 REPORT clause description of 6-73, 7-30 CRE and 18-5 message types of 6-75 syntax of 6-68 Reports names of 30-6 printed formatting of 30-20/30-21 vertical spacing in 30-18/30-20 Repositioning file to record with same alternate key 28-26/28-30 Requesters reply table and 6-70 screen transactions and TMF 32-19 RERUN clause 6-58 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -47 Index R RESERVE clause buffered cache and for indexed file 6-52 for relative file 6-45 for sequential file 6-35 file type and 6-24 for indexed file 6-48 for line sequential file 6-39, 19-13 for relative file 6-42 for sequential file 6-30 HP COBOL Fast I-O and 6-36 SAME AREA clause and 6-37 sequential block buffering and for indexed file 6-52 for relative file 6-45 for sequential file 6-34 Reserved words description of 3-9 all 21-1/21-11 categories of 21-1 HP COBOL 21-11/21-12 that cannot be split 2-6 RESETMEMORY routine 24-22 RESETSYNC message 6-76 RESETTOG directive 11-106 Resolution control directives for 11-51 of external references in binding 24-4, 24-6/24-7 to COBOL programs 11-16/11-18 to non-COBOL programs 11-18/11-22 of operating system routines 23-13/23-15 RETENTION attribute of DEFINE for labeled tape file 27-23 for unlabeled tape file 27-18 RETURN statement 9-201/9-202 Returned values GIVING phrase and 11-23 sizes of B-1 RETURN-CODE special register 9-19, 23-9 REVERSE function 14-53 REWRITE statement 9-202/9-208 RIGHT keyword in JUSTIFIED clause 7-88 in SYNCHRONIZED clause 7-87 Roll-forward recovery 32-17 ROUND (default) misalignment handling method 33-9 ROUNDED phrase description of 8-23 for NATIVE-n data item 7-76 in ADD CORRESPONDING statement 9-15 in ADD GIVING statement 9-12 in ADD TO statement 9-10 in COMPUTE statement 9-41 in DIVIDE GIVING REMAINDER 9-55 in DIVIDE GIVING statement 9-53 in DIVIDE INTO statement 9-51 migrating to native mode and 33-17 Rounding down addresses definition of 33-6 in HP COBOL programs 33-10 Routines C See C routines C++ See C++ routines dummy 13-23 Enscribe 28-40/28-47 FastSort interface 13-25/13-26 file system 23-10 FORTRAN See FORTRAN routines Guardian environment level 3 spooling 13-139 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -48 Index S Routines (continued) in CBL85UTL file 13-24, 13-38 in CLULIB file 13-30, 13-85 in COBOLLIB file 13-26, 13-85 in ZCOBSRL file 13-29, 13-38, 13-85 in ZCRESRL file 13-37 operating system See Operating system routines Pascal See Pascal routines pTAL See pTAL routines putting in TNS user library 24-19 Saved Message Utility (SMU) See Saved Message Utility routines TAL See TAL routines utility See Utility routines RUN or RUND command 12-2/12-4 RUNNABLE directive description of 11-107 migrating to native mode and 33-20 RUNNAMED directive description of 11-108, 25-13 migrating to native mode and 33-16 Running programs See Execution, of programs Running the compiler See Compilation RUNUNIT file 22-16 RUNV TACL macro and OSS script 34-8/34-10 Run-time environment description of 23-2 common See CRE determining 11-73, 22-19 for various languages 18-2 Run-time environment (continued) migrating to native mode and 33-3 non-CRE 11-72, 28-32 Run-time errors See Error messages, run-time Run-time routines, resolution of 24-6 S S in PICTURE clause 7-56 SAME AREA clause description of 6-59 for input-output file 6-60 for sort-merge file 6-61/6-62 RESERVE clause and 6-37 SAME MERGE AREA clause 6-62 SAME RECORD AREA clause description of 6-62 GLOBAL clause and 7-14, 7-54 SAME SORT AREA clause 6-62 SAVE directive 11-109/11-110 SAVEABEND directive description of 11-111 migrating to native mode and 33-17 Saveabend file 11-111 Saved Message Utility routines overview of 13-31, 13-36 individual 13-105/13-138 original and new 13-32 Saved messages 13-36 SAVE-SCRATCH parameter 13-56, 13-63 SCF user interface misalignment handling and 33-8 misalignment tracing facility and 33-7 Scope explicit terminators of 8-7 of condition-names 2-13 of data-names 2-13 of file-names 2-13 of index-names 2-14 of program-names 2-12, 9-25 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -49 Index S Scope (continued) of record-names 2-13 of statements 8-8 of user-defined names 2-11 Scratch file MERGE statement and 9-125 SORT statement and 9-230, 9-236 SCRATCH-BLOCK parameter 13-56, 13-63 SCRATCH-CHECK parameter 13-56, 13-64 SCRATCH-FILE parameter description of 13-53 MERGE statement and 9-125 Screen transactions 32-19 SD entries See Sort-merge files, file description entries for SEARCH directive description of 11-112/11-113 migrating to native mode and 33-15, 33-22 Search lists primary adding file to 24-12 binding or linking and 24-6, 24-10 unqualified references and 11-14 secondary 11-14 tertiary adding files to 24-13 binding or linking and 24-6, 24-10 unqualified references and 11-14 Search mode 31-30 SEARCH statement 9-209/9-219 Searches, binary 9-216 Secondary search list 11-14 SECOND-BUFFER parameter 13-56, 13-64 SECTION directive 10-13, 11-114 SECTION keyword as qualifier 3-15 Sections execution of 8-18 syntax of 8-13/8-14 Security of disk files 28-3/28-6 of operating system 31-27/31-30 SECURITY paragraph 5-3 SEG1 parameter 11-126 SEG2 parameter 11-126 SEGMENT parameter 13-56, 13-64 Segmentation 24-23 Segments code 24-17/24-18 independent description of 8-14 ALTER statement and 9-18 SEGMENT-LIMIT clause 6-5, 6-7 SELECT clause description of 6-25 file type and 6-24 for indexed file 6-47 for line sequential file 6-38, 19-12 for relative file 6-41 for sequential file 6-28 for sort-merge file 6-55 Semantic rules, common 8-21 Semicolon (;) 3-5 Sending data items description of 8-21 in INITIALIZE statement 9-94 Sentences execution of 8-17 syntax of 8-10 SEPARATE CHARACTER phrase 7-78 Separate processes 24-19 Separately compiled programs description of 1-7, 11-5, 23-3, 24-2, 24-18 diagnostic messages and 22-51 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -50 Index S Separately compiled programs (continued) sharing files 28-7 UL directive and 11-135 Separators 3-4/3-5 Sequence number 22-43 Sequence number area 16-1 Sequential access mode description of 4-8, 6-25 DELETE statement and 9-46 Sequential block buffering enabled by RESERVE clause 9-190 for indexed files 6-52 for relative files 6-45 for sequential files 6-34 for structured disk files 28-33 Sequential files description of 4-7 access modes of 4-8 closing 9-37/9-40 creating 28-14/28-16 file description entries for 7-7 file-control entries for 6-24, 6-28/6-37 opening 9-138 reading 9-178/9-192 repositioning 9-40 rewriting 9-202/9-207 structured 28-12, 28-14 unstructured 28-9, 28-15 writing 9-292/9-299 Servers breaking batch programs into 24-19 checkpointing rules for 32-9 debugging 25-15 example 31-18 for high-PIN requesters 11-83 HP NonStop TS/MP 32-3 SET DEFMODE command 25-2 SET statement 9-219/9-226 SETMODE message 6-76 SETPARAM message 6-76 SETTIME message 6-76 SETTOG directive 11-115 Shared code See Position-independent code (PIC) SHARED directive description of 11-116/11-117 migrating to native mode and 33-21 SHARED exclusion mode 4-10, 9-155, 28-38 Shared run-time libraries See Dynamic-link libraries (DLLs) See Native SRLs Sharing of data 23-17 of disk files 28-8/28-9 of file operations 18-4 of resources 2-15/2-24 of terminals 29-7/29-8 Short records 7-20 SHOWCOPY directive 11-117 SHOWFILE directive 11-118 SIGILL signal (signal #4) 33-9 Sign character (+ or -) 3-17 SIGN clause description of 7-78/7-79 CODE-SET clause and 7-29 for BINARY/COMPUTATIONAL data item 7-73 for NATIVE-n data item 7-76 in record description entry 7-45 Sign conditions 8-63 Simple conditions 8-53 Simple insertion editing 7-64 SIN function 14-54 Sine function 14-54 Single-tape files 9-39 Size error condition 8-24, 8-51 SIZE ERROR phrase description of 8-23/8-26 arithmetic precision and 8-49 for NATIVE-n data item 7-76 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -51 Index S SIZE ERROR phrase (continued) in ADD CORRESPONDING statement 9-14 in ADD GIVING statement 9-12 in ADD TO statement 9-9 in COMPUTE statement 9-41 Size limits in Extended-Storage Section 7-38 in Working-Storage Section 7-36 list of 20-1/20-4 Skipping lines in output 30-19 to new page 30-20 Slash (/) as arithmetic operator 8-46 in ANSI reference format 16-2 in PICTURE clause 3-24, 7-57, 7-64 in Tandem reference format 2-4 Small data area description of 13-7 LARGEDATA directive and 11-88 UL directive and 11-135 Small-memory model 9-63 SMU routines See Saved Message Utility routines SORT INPUT field 9-286 Sort keys 9-231 SORT OUTPUT field 9-286 SORT statement 9-227/9-237 Sort-merge files file description entries for 7-30/7-32 file-control entries for 6-24, 6-55/6-56 SORT statement and 9-232 SORT-PROGRAM parameter 13-53 SOURCE directive description of 11-119/11-122 compared to COPY statement 22-23 IF directive and 11-85 SOURCE libraries description of 22-22/22-24 altering 22-24/22-29 compiler listing and 22-48 creating 22-24/22-29 format of 11-121 including text from 22-34/22-35 REPLACE statement and 22-39 Source program listing See Compiler listing Source programs See HP COBOL programs SOURCE-COMPUTER paragraph 6-4 Space character as separator 3-4 figurative constant for 3-23 in PICTURE clause 7-64 inserting 3-24 SPACE or SPACES figurative constant 3-23 Special insertion editing 7-64 Special names 26-5 Special registers DEBUG-ITEM 9-285 GUARDIAN-ERR 9-187, 13-82, 13-84, 13-93, 13-95 LINAGE-COUNTER 7-28 PROGRAM-STATUS 9-254 PROGRAM-STATUS-1 9-254 PROGRAM-STATUS-2 9-254 RETURN-CODE 9-19, 23-9 SPECIAL-NAMES paragraph description of 6-10/6-22 migrating to native mode and 33-15 SPI devices opening 13-77 sending events to 13-79 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -52 Index S SPOOLCOM utility description of 30-3, 30-15/30-18 DEV subcommand 30-17 JOB subcommand 30-16 SPOOLCONTROL routine 13-139 SPOOLCONTROLBUF routine 13-139 SPOOLEND routine 13-139 Spooler jobs description of 30-4/30-7 current 30-12 form names for 30-7 location of 30-4 number of copies of 30-6 priority of 30-6 report names for 30-6 state of 30-5 Spoolers components of 30-2/30-3 jobs for See Spooler jobs level 2 protocol for 13-95/13-99 output to description of 30-1, 30-7/30-22 formatting of 30-20/30-21 from compiler listing 30-8 from programs 30-8/30-11 vertical spacing in 30-18/30-20 Spooling level-1 30-8 level-2 30-9/30-10 level-3 30-10 SPOOLSETMODE routine 13-139 SPOOLSTART routine 13-139 SPOOLWRITE routine 13-139 SQL databases 9-36 SQL directive description of 11-122/11-124 migrating to native mode and 33-13 SQLMEM directive description of 11-124 migrating to native mode and 33-19 SQL/MP 34-3, 34-4, 34-7 SQL/MX 34-3, 34-4, 34-7 SQRT function 14-55 Square root function 14-55 SRLs See Native SRLs Stack overflow error messages 48-9 Stacked compilation 11-5 STANDARD access mode 7-40 Standard addressing 7-40 Standard COBOL description of 1-1 formatting restrictions for 2-8, 8-14 Standard date format converting to integer date format 14-21 obtaining from integer date format 14-17 Standard files sharing 28-8 terminals as 29-8 STANDARD-DEVIATION function 14-56/14-57 START PROGRAM field 9-286 START statement description of 9-237/9-251 START LESS THAN 9-248 STARTBACKUP statement description of 9-252/9-255 fault-tolerant facility and 32-2, 32-9 migrating to native mode and 33-13 PROGRAM-STATUS data item and 32-10/32-12 Starting points in disk files 28-20/28-30 Startup message portions 13-36 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -53 Index S Statements description of 8-4 arithmetic description of 8-42 common features of 8-43 common semantic rules of 8-21 compiler-directing See Compiler directives conditional 8-6/8-7 delimited-scope 8-7 execution of 8-16 imperative 8-5 nested conditional IF 9-87 delimited-scope IF 9-84 PERFORM 9-160 next executable 8-19 scope of 8-8 summary of 43-1/43-59 types of 8-4 Static calls 23-5 Statistics from Binder 11-29 from compiler 11-29/11-32 Status Key 1 8-29 Status Key 2 8-30 STATUS-3270 message 6-76 STOP statement 9-256 Stopping compilation in Guardian environment 11-44 in OSS environment 19-1 Storage allocation for compiler 22-21 for data items data structures 7-46 elementary 7-46 redefined 7-49 for disk files 28-2 in File Section 7-3, 7-46 Storage allocation (continued) in Linkage Section 7-46 initial programs and 9-27 STRING statement 9-257/9-261 String:length parameters 9-60, 9-65, 23-33, 33-4 Stroke (/) See Slash (/) Structured files description of 28-10 entry-sequenced 28-12, 28-14 improving performance of 28-31/28-35 indexed 28-13/28-14, 28-17/28-18 key-sequenced 28-13/28-14 record blocking for 28-31/28-35 relative 28-12/28-13, 28-16/28-17 SUBORDINATE-NAME message 6-76 Subprograms See Called programs Subscripts description of 4-19/4-21 for fixed-size tables 7-81 indexes and 7-82 indexes instead of 4-21 intrinsic functions and 14-7 MOVE statement and 9-128 number of 4-21 of redefined data items 7-50 operand identification and 8-21 order of 7-82 range of 4-21 syntax of 4-20 SUBSET directive 11-125/11-128 SUBSORT-COUNT parameter 13-56, 13-65 Substring replacement with COPY statement 22-32 with REPLACE statement 22-37 Subsystem Control Facility See SCF user interface HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -54 Index T SUBTRACT statement description of 9-262/9-268 precision of 8-49 Subtraction operator 8-46 SUBTYPE directive description of 11-128 migrating to native mode and 33-17 Subvolumes to be searched 22-19 SUM function 14-58/14-59 Supervisor process 30-3 SUPPRESS directive 11-129, 22-40 Suppressing zero 3-24 Suspending a process 31-39 Swap file MERGE statement and 9-125 redirecting 6-56 SORT statement and 9-230 SWAP-FILE parameter description of 13-54 MERGE statement and 9-125 Switches, external 9-224, 25-6 Switch-status conditions 8-62 Symbol table directives for 22-41 for Inspect debugger 11-130 listing of 22-53 SYMBOLIC CHARACTERS clause 6-18 Symbolic code listing 22-41, 22-55 SYMBOLS directive 11-130 SYMSERV process description of 11-10, 11-12 selecting processor for 11-34 Sync blocks, checkpointing 32-7 SYNCDEPTH LIMIT phrase 6-66 SYNCDEPTH parameter 32-8 SYNCHRONIZED clause description of 7-86/7-87 for COMPUTATIONAL-3 data item 7-74 for COMPUTATIONAL-5 data item 7-75 for INDEX data item 7-76 SYNCHRONIZED clause (continued) for NATIVE-n data item 7-76 for PACKED-DECIMAL data item 7-74 in record description entry 7-46 migrating to native mode and 33-12 Synchronized data items 7-86 Syntax checking 22-18 SYNTAX directive 11-131, 22-22 System code extension 13-7 System code space description of 13-7 COBOLLIB routines in 13-29 System data space 13-7 System file names description of 26-2/26-4 associating with COBOL file names 9-144, 26-5/26-9 for devices 26-3 for nondisk files 26-3 for temporary disk files 26-3 special 26-5 System library 13-8 System messages CRE and 6-76, 18-6 intercepting 26-10 list of 6-73 System numbers 31-23 SYSTEM parameter 13-56, 13-65 SYSTEM-FLAG 26-11 System-Name clause description of 6-11/6-14 with STATUS phrase 6-13 without STATUS phrase 6-12 System-names 3-10 T TABLE OCCURS phrase 6-65 Tables elements of 9-217 fixed-size 7-79 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -55 Index T Tables (continued) implicit FILLER bytes and 4-17 in Data Division 4-12/4-14 in Extended-Storage Section 24-21 multidimensional 7-82, 9-209, 9-212 passed by content 23-22 receive-control 6-70 reply 6-70 variable-size 7-83 TACL commands displaying 22-2 editing 22-4 log of 22-2/22-4 reexecuting 22-3, 22-4 TACL DEFINE file 34-2 TACL DEFINE tool 34-10 TAL routines calling 9-58 in TNS user library 24-19 migrating to native mode 33-4 passing parameters to 9-63, 23-32/23-34 record numbers and 28-17 restrictions on 9-65, 23-19 run-time environment for 23-2 with FORTRAN CHARACTER parameters 9-65 with FORTRAN protocol 23-8 Tallying with replacement 9-107 without replacement 9-95 TAN function 14-60 Tandem Development Suite (TDS) debugging and 34-7 native COBOL cross compiler and 34-4 online help for 34-11 TACL DEFINE files and 34-2 TANDEM directive 11-132 Tandem reference format description of 2-3/2-8 COLUMNS directive and 11-59 compiler listing and 22-42 directive for 11-53 program creation and 22-6 restrictions on 2-6/2-8 text libraries and 22-22 Tangent function 14-60 Tape files blocking 27-2 closing 9-39 DEFINEs for 27-15/27-24 EBCDIC 27-12 executing programs that use 27-24/27-26 input-output 27-1/27-26 labeled See Labeled tape files minimum record length 27-1 other data types in 27-13 other than HP 27-12/27-15 preventing prereading of 27-1 reading and writing description of 27-1/27-15 labeled 27-8/27-12 other than HP 27-12/27-15 unlabeled 27-3/27-8 sharing one tape 27-5 spanning several tapes 27-6 STANDARD and OMITTED in 7-22 unlabeled See Unlabeled tape files variable-length records in 27-15 Tape mount messages description of 27-24 for labeled tapes 27-25 for unlabeled tapes 27-6, 27-25 specifying file for 13-84 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -56 Index T Tape Utility Program (Tapecom) 27-16, 27-22, 27-24 TAPE-DIALOGUE parameter 12-12 Target file description of 11-28 construction of 11-43 in single program unit compilation 11-10, 11-11 TDS See Tandem Development Suite (TDS) TEC See HP Tandem Extensions for Codewright (TEC) TEDIT editor description of 22-8/22-10 commands of 22-10 customizing 22-10 second window of 22-9 Temporary files names for 26-3 placement of 11-11, 22-21 TERM option of RUN command 25-11, 26-7 Terminals ACCEPT statement and 29-2/29-3, 29-13 as files 29-4/29-5 DISPLAY statement and 29-2/29-3, 29-10, 29-13 home 25-11 input-output on 29-1/29-15 logging program activity to 29-14 prompting from 29-6/29-7 receiving from 29-12 sharing 29-7/29-8 writing to 29-12 Terminating compilation in Guardian environment 11-44 in OSS environment 19-1 Terminators, explicit scope 8-7 Tertiary search list adding files to 24-13 binding or linking and 24-6, 24-10 unqualified references and 11-14 Text combining 22-44/22-45 Text lines 2-5 Text replacement 22-36/22-39 Text-names identical 3-16 qualified 3-13, 3-15 Time limit Break and 29-8 expired 8-41 for LOCKFILE statement 9-116, 9-117 for READ statement 9-179, 9-188, 9-199 for START statement 9-241, 9-245 for $RECEIVE 8-42 on disk file input-output 28-7, 28-39 on input-output 8-41/8-42 TIME LIMIT phrase in LOCKFILE statement 9-116, 9-117 in READ statement 9-179 in START statement 9-241, 9-245 TIME LIMITS phrase 9-139 TIME phrase 9-8 Timestamp process names 25-12 Time, current ACCEPT statement and 9-8 CURRENT-DATE function and 14-16 TIME-SIGNAL message 6-76 TMF See HP NonStop Transaction Management Facility (TMF) TNS mode 1-3 TNS user library description of 13-8/13-9, 24-19/24-20 COBOLLIB routines in 13-28 CRE programs in 18-6 in binding 24-6, 24-10 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -57 Index U TNS user library (continued) routines that can go in 24-19/24-20 specifying 24-9 TNSMISALIGN attribute (SCF) 33-8 TNS/R native mode 1-3 Toggles in ENDIF directive 11-71 in IF and IFNOT directives 11-84, 11-86 in RESETTOG directive 11-106 in SETTOG directive 11-115 Tracing facility 33-7/33-8 Transactions description of 32-15/32-16 screen 32-19 Transfer of control explicit 8-18 implicit 8-18 in PERFORM statement 9-159 in SIZE ERROR or NOT SIZE ERROR phrase 8-26 Transfer Tool 34-11 Trap 1 33-9 Trap 2 See Arithmetic overflow TRAP2 directive description of 11-132/11-134 migrating to native mode and 33-19 SIZE ERROR phrase and 8-24 TRAP2-74 directive description of 11-134/11-135 migrating to native mode and 33-19 Trapping arithmetic overflow COBOL85^ARMTRAP and 13-39 TRAP2 and NOTRAP2 and 11-132 TRAP2-74 and NOTRAP2-74 and 11-134 TRUE value 8-54 TS/MP See HP Nonstop TS/MP U UL directive description of 11-135 migrating to native mode and 33-18 Unary arithmetic operators 8-46 Unaudited files 32-3 Unavailable printers 25-6 Unconditional GO TO statement 9-81/9-82 Unconditional PERFORM statement 9-157/9-162 Undefined results 8-22 Underlining lines in output 30-19 Underscore (_) 12-20 Uniqueness in user-defined names 3-10 qualification and 3-16 UNIT phrase 9-38 Unlabeled tape files description of 27-3/27-8 DEFINEs for 27-16/27-18 mount messages for 27-25 UNLOCKFILE statement 9-269/9-270 UNLOCKRECORD statement 9-270/9-271 Unnamed processes 9-254 Unqualified file names 11-36, 22-19 Unqualified references 11-13/11-16 Unresolved references 24-8, 24-9 UNSTRING statement 9-271/9-283 Unstructured disk files description of 28-9 creating and using 28-15 faster processing 28-31 Until loop (PERFORM VARYING) 9-166/9-177 UPPER-CASE function 14-61 USAGE clause description of 7-69/7-78 in record description entry 7-45 USE attribute of DEFINE 27-22 USE PROCEDURE field 9-286 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -58 Index V USE statement description of 9-283/9-291 migrating to native mode and 33-14 User code space description of 13-6 COBOLLIB routines in 13-28 User data space description of 13-6 LARGEDATA directive and 11-88 User extended space description of 13-7 LARGEDATA directive 11-88 User library description of 13-8, 13-9 migrating to native mode and 33-16 native See Native user library specifying 13-10 TNS See TNS user library User library space description of 13-6 COBOLLIB routines in 13-28 User-defined names description of 3-10 scope of 2-11 USESEGMENT routine 24-22 USING phrase in CALL statement 9-21 in ENTER statement 9-61 Linkage Section and 7-40 Utility routines description of 13-1/13-139 dummy 13-23 in OSS environment 19-25 list of 13-3/13-5 V V in PICTURE clause 7-56, 7-64 Validation of parameters 9-27 of references 24-4, 24-6/24-7 VALUE clause description of 7-89/7-90 EXTERNAL clause and 7-52 for condition-name 7-95 for INDEX data item 7-76 for redefined data item 7-50 initializing data items and 7-36 VALUE OF clause 7-23 Value parameters 11-22, 23-23 Variable parameter lists 23-13 Variables conditional See Conditional variables environment 19-7, 35-10 Variable-length records description of 4-5 in disk files 28-6 in EDIT files 28-9 in entry-sequenced files 28-12 in indexed files 28-14 in key-sequenced files 28-14 in relative files 28-13 in tape files 27-15 in terminal files 29-4 preferred description of 7-18 PROMPT phrase and 9-182 READ statement and 9-188 writing 9-298, 9-303 Variable-size data items operand identification and 8-21 tables 7-83 Variable-type intrinsic functions description of 14-6 MAX 14-29/14-30 MIN 14-35/14-36 RANGE 14-50/14-51 SUM 14-58/14-59 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -59 Index W VARIANCE function 14-62/14-63 VARYING phrase 7-31 Verbs description of 9-1/9-305 imperative 8-5 Vertical spacing 30-18/30-20 Virgule (/) See Slash (/) Virtual memory 31-2 Visual Inspect debugger description of 15-4 on PC 34-8/34-10 Visual Studio .NET 34-3 VOLUME attribute of DEFINE 27-23 Volume names 18-3 VS full-screen editor 22-8 W WAITED-IO parameter 12-12 WARN directive 11-136, 22-40 Warning messages description of 8-34 format of 47-3 from Binder 11-136 from compiler 11-75, 11-136, 22-15 in compiler listing 22-50 list of 47-4/47-93 optional 22-50 WHEN-COMPILED function 14-63/14-64 While loop (PERFORM VARYING) 9-166/9-177 Winsock 34-11 Working-Storage Section description of 7-33/7-36 LESS-CODE 1 directive and 24-22 WRITE statement 9-292/9-305 Write-through cache 28-32 Writing numeric data 29-13 to console 29-11 Writing (continued) to printer 29-12, 30-22 to tape files description of 27-1/27-15 labeled 27-8/27-12 other than HP 27-12/27-15 unlabeled 27-3/27-8 to terminal 29-12 X X in PICTURE clause 7-56 XEP (extended entry point) table 24-17 X/Open CALL statement description of 9-18, 23-9 CANCEL statement and 9-33, 23-7 ENTER statement and 9-29, 23-7 Z Z in PICTURE clause 3-24, 7-57, 7-67 ZCOBSRL file overview of 13-29, 13-30 descriptions of routines in 13-85/13-104 list of routines in 13-29 syntax summary of routines in 45-1/45-10 ZCRESRL file 13-37 Zero figurative constant for 3-23 in PICTURE clause 3-24, 7-57, 7-64 negative 8-44 suppression of 3-24, 7-67 ZERO, ZEROS, or ZEROES figurative constant 3-23 Zero-length records 28-11, 28-12 ZSYSCOB file 23-13 ZZBInnnn file 22-17 ZZPTnnnn file 22-17 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -60 Index Special Characters Special Characters 8-45/8-48, 8-54/8-57, 13-23/13-24, 13-26/13-29, 13-29/13-30, 13-31/13-36, 16-1/16-4 ! See Exclamation mark (!) #DYNAMIC special name description of 26-8 ASSIGN command and 26-9 in OSS environment 19-25 #IN special name description of 26-6 in OSS environment 19-11 #OUT special name description of 26-7 in OSS environment 19-11 #RECEIVE blocks 11-24/11-25 #TEMP special name 26-8, 28-43 #TERM special name 26-7 $ See Dollar sign ($) $0 opening 13-77 sending events to 13-79, 29-11 $0.#ZSPI opening 13-77 sending events to 13-79 $RECEIVE as input-output file 31-10/31-12 as separate input and output files 31-7/31-9 Break and 29-8 CRE and 18-4 file number of 28-41 process communication and 31-6/31-12 RECEIVE-CONTROL paragraph and 6-64/6-76 rules for 31-17 $RECEIVE (continued) time limit for 8-42 #RECEIVE blocks and 11-24/11-25 $SYSTEM.SYSnn subvolume ZCOBSRL and 13-29 ZCRESRL and 13-37 $SYSTEM.SYSTEM subvolume 13-23 & See Ampersand (&) * See Asterisk (*) + See Plus sign (+) See Minus sign (-) .cbl file extension 34-4 .cob file extension 34-4 / See Slash (/) : See Colon (:) ; See Semicolon (;) =_DEFAULTS DEFINE 26-3 =_OBJECT_SEARCH DEFINE 11-37, 22-19 =_SORT_DEFAULTS DEFINE establishing parameters with 13-26 MERGE statement and 9-125 =_SOURCE_SEARCH DEFINE 11-37, 22-19 HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -61 Index Special Characters HP COBOL Manual for TNS and TNS/R Programs —522555-006 Index -62
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : Yes XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:08:04 Create Date : 2007:04:18 16:51:48Z Creator Tool : FrameMaker 6.0 Modify Date : 2010:09:16 17:25:11-07:00 Metadata Date : 2010:09:16 17:25:11-07:00 Format : application/pdf Creator : Title : COBOL Manual for TNS and TNS/R Programs Producer : Acrobat Distiller 4.05 for Windows Document ID : uuid:3398d13c-b7b0-4bde-9d67-adbfd775d4e8 Instance ID : uuid:ba2bec21-6aca-4f5f-a0b7-da3cf9a859ed Page Mode : UseOutlines Page Count : 2046 Author :EXIF Metadata provided by EXIF.tools